fix(web): treat only 2xx as a successful display save

Review feedback on #422.

- showDisplaySaveResult tested `xhr.status >= 400` for failure, so a
  network error — which reports status 0 — was waved through as
  "Display settings saved". That's the same class of false-success bug
  this branch set out to fix. Test the 2xx range instead, and let a
  response body refine a successful verdict without overturning a
  failed one.
- Annotate the _copies_fits_hardware helper, matching the annotated
  helpers already in api_v3.py.
- Cover the vertical divisibility branch: chain_length 2 would divide
  evenly, so only parallel 3 can produce the rejection, which pins the
  branch to the right hardware dimension.

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

.cursor/README.md

@@ -0,0 +1,145 @@
+# Cursor Helper Files for LEDMatrix Plugin Development
+
+This directory contains Cursor-specific helper files to assist with plugin development in the LEDMatrix project.
+
+## Files Overview
+
+### `.cursorrules`
+Comprehensive rules file that Cursor uses to understand plugin development patterns, best practices, and workflows. This file is automatically loaded by Cursor and helps guide AI-assisted development.
+
+### `plugins_guide.md`
+Detailed guide covering:
+- Plugin system overview
+- Creating new plugins
+- Running plugins (emulator and hardware)
+- Loading and configuring plugins
+- Development workflow
+- Testing strategies
+- Troubleshooting
+
+### `plugin_templates/`
+Template files for quick plugin creation:
+- `manifest.json.template` - Plugin metadata template
+- `manager.py.template` - Plugin class template
+- `config_schema.json.template` - Configuration schema template
+- `README.md.template` - Plugin documentation template
+- `requirements.txt.template` - Dependencies template
+- `QUICK_START.md` - Quick start guide for using templates
+
+## Quick Reference
+
+### Creating a New Plugin
+
+1. **Using templates** (recommended):
+```bash
+# See QUICK_START.md in plugin_templates/
+cd plugins
+mkdir my-plugin
+cd my-plugin
+cp ../../.cursor/plugin_templates/*.template .
+# Edit files, replacing PLUGIN_ID and other placeholders
+```
+
+2. **Using dev_plugin_setup.sh**:
+```bash
+# Link from GitHub
+./scripts/dev/dev_plugin_setup.sh link-github my-plugin
+
+# Link local repo
+./scripts/dev/dev_plugin_setup.sh link my-plugin /path/to/repo
+```
+
+### Running the Display
+
+```bash
+# Emulator mode (development, no hardware required)
+python3 run.py --emulator
+# (equivalent: EMULATOR=true python3 run.py)
+
+# Hardware (production, requires the rpi-rgb-led-matrix submodule built)
+python3 run.py
+
+# As a systemd service
+sudo systemctl start ledmatrix
+
+# Dev preview server (renders plugins to a browser without running run.py)
+python3 scripts/dev_server.py  # then open http://localhost:5001
+```
+
+The `-e`/`--emulator` CLI flag is defined in `run.py:19-20` and
+sets `os.environ["EMULATOR"] = "true"` before any display imports,
+which `src/display_manager.py:2` then reads to switch between the
+hardware and emulator backends.
+
+### Managing Plugins
+
+```bash
+# List plugins
+./scripts/dev/dev_plugin_setup.sh list
+
+# Check status
+./scripts/dev/dev_plugin_setup.sh status
+
+# Update plugin(s)
+./scripts/dev/dev_plugin_setup.sh update [plugin-name]
+
+# Unlink plugin
+./scripts/dev/dev_plugin_setup.sh unlink <plugin-name>
+```
+
+## Using These Files with Cursor
+
+### `.cursorrules`
+Cursor automatically reads this file to understand:
+- Plugin structure and requirements
+- Development workflows
+- Best practices
+- Common patterns
+- API reference
+
+When asking Cursor to help with plugins, it will use this context to provide better assistance.
+
+### Plugin Templates
+Use templates when creating new plugins:
+1. Copy templates from `.cursor/plugin_templates/`
+2. Replace placeholders (PLUGIN_ID, PluginClassName, etc.)
+3. Customize for your plugin's needs
+4. Follow the guide in `plugins_guide.md`
+
+### Documentation
+Refer to `plugins_guide.md` for:
+- Detailed explanations
+- Troubleshooting steps
+- Best practices
+- Examples and patterns
+
+## Plugin Development Workflow
+
+1. **Plan**: Determine plugin functionality and requirements
+2. **Create**: Use templates or dev_plugin_setup.sh to create plugin structure
+3. **Develop**: Implement plugin logic following BasePlugin interface
+4. **Test**: Test with emulator first, then on hardware
+5. **Configure**: Add plugin config to config/config.json
+6. **Iterate**: Refine based on testing and feedback
+
+## Resources
+
+- **Plugin System**: `src/plugin_system/`
+- **Base Plugin**: `src/plugin_system/base_plugin.py`
+- **Plugin Manager**: `src/plugin_system/plugin_manager.py`
+- **Example Plugins**: see the
+  [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
+  repo for canonical sources (e.g. `plugins/hockey-scoreboard/`,
+  `plugins/football-scoreboard/`). Installed plugins land in
+  `plugin-repos/` (default) or `plugins/` (dev fallback).
+- **Architecture Docs**: `docs/PLUGIN_ARCHITECTURE_SPEC.md`
+- **Development Setup**: `scripts/dev/dev_plugin_setup.sh`
+
+## Getting Help
+
+1. Check `plugins_guide.md` for detailed documentation
+2. Review `.cursorrules` for development patterns
+3. Look at existing plugins for examples
+4. Check logs for error messages
+5. Review plugin system code in `src/plugin_system/`
+

.cursor/plugin_templates/QUICK_START.md

@@ -0,0 +1,247 @@
+# Quick Start: Creating a New Plugin
+
+This guide will help you create a new plugin using the templates in `.cursor/plugin_templates/`.
+
+## Step 1: Create Plugin Directory
+
+```bash
+cd /path/to/LEDMatrix
+mkdir -p plugins/my-plugin
+cd plugins/my-plugin
+```
+
+## Step 2: Copy Templates
+
+```bash
+# Copy all template files
+cp ../../.cursor/plugin_templates/manifest.json.template ./manifest.json
+cp ../../.cursor/plugin_templates/manager.py.template ./manager.py
+cp ../../.cursor/plugin_templates/config_schema.json.template ./config_schema.json
+cp ../../.cursor/plugin_templates/README.md.template ./README.md
+cp ../../.cursor/plugin_templates/requirements.txt.template ./requirements.txt
+```
+
+## Step 3: Customize Files
+
+### manifest.json
+
+Replace placeholders:
+- `PLUGIN_ID` → `my-plugin` (lowercase, use hyphens)
+- `Plugin Name` → Your plugin's display name
+- `PluginClassName` → `MyPlugin` (PascalCase)
+- Update description, author, homepage, etc.
+
+### manager.py
+
+Replace placeholders:
+- `PluginClassName` → `MyPlugin` (must match manifest)
+- Implement `_fetch_data()` method
+- Implement `_render_content()` method
+- Add any custom validation in `validate_config()`
+
+### config_schema.json
+
+Customize:
+- Update description
+- Add/remove configuration properties
+- Set default values
+- Add validation rules
+
+### README.md
+
+Replace placeholders:
+- `PLUGIN_ID` → `my-plugin`
+- `Plugin Name` → Your plugin's name
+- Fill in features, installation, configuration sections
+
+### requirements.txt
+
+Add your plugin's dependencies:
+```txt
+requests>=2.28.0
+pillow>=9.0.0
+```
+
+## Step 4: Enable Plugin
+
+Edit `config/config.json`:
+
+```json
+{
+  "my-plugin": {
+    "enabled": true,
+    "display_duration": 15
+  }
+}
+```
+
+## Step 5: Test Plugin
+
+### Test with Emulator
+
+```bash
+cd /path/to/LEDMatrix
+python run.py --emulator
+```
+
+### Check Plugin Loading
+
+Look for logs like:
+```
+[INFO] Discovered 1 plugin(s)
+[INFO] Loaded plugin: my-plugin v1.0.0
+[INFO] Added plugin mode: my-plugin
+```
+
+### Test Plugin Display
+
+The plugin should appear in the display rotation. Check logs for any errors.
+
+## Step 6: Develop and Iterate
+
+1. Edit `manager.py` to implement your plugin logic
+2. Test with emulator: `python run.py --emulator`
+3. Check logs for errors
+4. Iterate until working correctly
+
+## Step 7: Test on Hardware (Optional)
+
+When ready, test on Raspberry Pi:
+
+```bash
+# Deploy to Pi
+rsync -avz plugins/my-plugin/ pi@raspberrypi:/path/to/LEDMatrix/plugins/my-plugin/
+
+# Or if using git
+ssh pi@raspberrypi "cd /path/to/LEDMatrix/plugins/my-plugin && git pull"
+
+# Restart service
+ssh pi@raspberrypi "sudo systemctl restart ledmatrix"
+```
+
+## Common Customizations
+
+### Adding API Integration
+
+1. Add API key to `config_schema.json`:
+```json
+{
+  "api_key": {
+    "type": "string",
+    "description": "API key for service"
+  }
+}
+```
+
+2. Implement API call in `_fetch_data()`:
+```python
+import requests
+
+def _fetch_data(self):
+    response = requests.get(
+        "https://api.example.com/data",
+        headers={"Authorization": f"Bearer {self.api_key}"}
+    )
+    return response.json()
+```
+
+3. Store API key in `config/config_secrets.json`:
+```json
+{
+  "my-plugin": {
+    "api_key": "your-secret-key"
+  }
+}
+```
+
+### Adding Image Rendering
+
+There is no `draw_image()` helper on `DisplayManager`. To render an
+image, paste it directly onto the underlying PIL `Image`
+(`display_manager.image`) and then call `update_display()`:
+
+```python
+def _render_content(self):
+    # Load and paste image onto the display canvas
+    image = Image.open("assets/logo.png").convert("RGB")
+    self.display_manager.image.paste(image, (0, 0))
+
+    # Draw text overlay
+    self.display_manager.draw_text(
+        "Text",
+        x=10, y=20,
+        color=(255, 255, 255)
+    )
+
+    self.display_manager.update_display()
+```
+
+For transparency, paste with a mask:
+
+```python
+icon = Image.open("assets/icon.png").convert("RGBA")
+self.display_manager.image.paste(icon, (5, 5), icon)
+```
+
+
+### Adding Live Priority
+
+1. Enable in config:
+```json
+{
+  "my-plugin": {
+    "live_priority": true
+  }
+}
+```
+
+2. Implement `has_live_content()`:
+```python
+def has_live_content(self) -> bool:
+    return self.data and self.data.get("is_live", False)
+```
+
+3. Override `get_live_modes()` if needed:
+```python
+def get_live_modes(self) -> list:
+    return ["my_plugin_live_mode"]
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+- Check `manifest.json` syntax (must be valid JSON)
+- Verify `entry_point` file exists
+- Ensure `class_name` matches class name in manager.py
+- Check for import errors in logs
+
+### Configuration Errors
+
+- Validate config against `config_schema.json`
+- Check required fields are present
+- Verify data types match schema
+
+### Display Issues
+
+- Check display dimensions: `display_manager.width`, `display_manager.height`
+- Verify coordinates are within bounds
+- Ensure `update_display()` is called
+- Test with emulator first
+
+## Next Steps
+
+- Review existing plugins for patterns:
+  - `plugins/hockey-scoreboard/` - Sports scoreboard example
+  - `plugins/ledmatrix-music/` - Real-time data example
+  - `plugins/ledmatrix-stocks/` - Data display example
+
+- Read full documentation:
+  - `.cursor/plugins_guide.md` - Comprehensive guide
+  - `docs/PLUGIN_ARCHITECTURE_SPEC.md` - Architecture details
+  - `.cursorrules` - Development rules
+
+- Check plugin system code:
+  - `src/plugin_system/base_plugin.py` - Base class
+  - `src/plugin_system/plugin_manager.py` - Plugin manager
+

.cursor/plugin_templates/README.md.template

@@ -0,0 +1,156 @@
+# Plugin Name
+
+Brief description of what this plugin does.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Installation
+
+1. Link the plugin to your LEDMatrix installation:
+
+```bash
+cd /path/to/LEDMatrix
+./scripts/dev/dev_plugin_setup.sh link-github PLUGIN_ID
+```
+
+Or for local development:
+
+```bash
+./scripts/dev/dev_plugin_setup.sh link PLUGIN_ID /path/to/plugin/repo
+```
+
+2. Install dependencies:
+
+```bash
+pip install -r plugins/PLUGIN_ID/requirements.txt
+```
+
+3. Configure the plugin in `config/config.json`:
+
+```json
+{
+  "PLUGIN_ID": {
+    "enabled": true,
+    "display_duration": 15
+  }
+}
+```
+
+**Note:** API keys and other sensitive credentials must be stored in `config/config_secrets.json`, not in `config/config.json`.
+
+4. Store API keys in `config/config_secrets.json`:
+
+```json
+{
+  "PLUGIN_ID": {
+    "api_key": "your-secret-api-key"
+  }
+}
+```
+
+## Configuration
+
+### Required Settings
+
+- `enabled` (boolean): Enable or disable the plugin
+- `api_key` (string): API key for external service (if required)
+
+### Optional Settings
+
+- `display_duration` (number): How long to display this plugin (default: 15 seconds)
+- `refresh_interval` (integer): How often to refresh data in seconds (default: 60)
+- `live_priority` (boolean): Enable live priority takeover (default: false)
+
+## Display Modes
+
+This plugin provides the following display modes:
+
+- `PLUGIN_ID`: Main display mode
+
+## API Requirements
+
+This plugin requires:
+
+- **API Name**: Description of API requirements
+  - URL: https://api.example.com
+  - Rate Limit: X requests per minute
+  - Authentication: API key required
+
+## Development
+
+### Running Tests
+
+```bash
+cd plugins/PLUGIN_ID
+python test_PLUGIN_ID.py
+```
+
+### Testing with Emulator
+
+```bash
+cd /path/to/LEDMatrix
+python run.py --emulator
+```
+
+### Debugging
+
+Enable debug logging in `config/config.json`:
+
+```json
+{
+  "logging": {
+    "level": "DEBUG"
+  }
+}
+```
+
+Check logs:
+
+```bash
+# On Raspberry Pi (if running as service)
+journalctl -u ledmatrix -f
+
+# Direct execution
+python run.py
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+1. Check that `manifest.json` exists and is valid
+2. Verify `entry_point` file exists
+3. Check that `class_name` matches the class in manager.py
+4. Review logs for import errors
+
+### Configuration Errors
+
+1. Validate config against `config_schema.json`
+2. Check required fields are present
+3. Verify data types match schema
+
+### API Errors
+
+1. Verify API key is correct
+2. Check API rate limits
+3. Review network connectivity
+4. Check API service status
+
+## License
+
+[License information]
+
+## Author
+
+Your Name
+
+## Links
+
+- GitHub: https://github.com/username/ledmatrix-PLUGIN_ID
+- Documentation: [Link to docs]
+- Issues: https://github.com/username/ledmatrix-PLUGIN_ID/issues
+

.cursor/plugin_templates/config_schema.json.template

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Plugin Configuration Schema",
+  "description": "Configuration schema for Plugin Name",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable or disable this plugin"
+    },
+    "display_duration": {
+      "type": "number",
+      "default": 15,
+      "minimum": 1,
+      "maximum": 300,
+      "description": "How long to display this plugin in seconds"
+    },
+    "live_priority": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable live priority takeover when plugin has live content"
+    },
+    "refresh_interval": {
+      "type": "integer",
+      "default": 60,
+      "minimum": 1,
+      "description": "How often to refresh data in seconds"
+    },
+    "api_key": {
+      "type": "string",
+      "description": "API key for external service (store in config_secrets.json)",
+      "default": ""
+    },
+    "custom_setting": {
+      "type": "string",
+      "description": "Example custom setting - replace with your plugin's settings",
+      "default": "default_value"
+    }
+  },
+  "required": ["enabled"],
+  "additionalProperties": false
+}
+

.cursor/plugin_templates/manager.py.template

@@ -0,0 +1,226 @@
+"""
+Plugin Name
+
+Brief description of what this plugin does.
+
+API Version: 1.0.0
+"""
+
+from src.plugin_system.base_plugin import BasePlugin
+from PIL import Image
+from typing import Dict, Any, Optional
+import logging
+import time
+
+
+class PluginClassName(BasePlugin):
+    """
+    Plugin class that inherits from BasePlugin.
+    
+    This plugin demonstrates the basic structure and common patterns
+    for LEDMatrix plugins.
+    """
+    
+    def __init__(
+        self,
+        plugin_id: str,
+        config: Dict[str, Any],
+        display_manager,
+        cache_manager,
+        plugin_manager,
+    ):
+        """Initialize the plugin."""
+        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
+        
+        # Initialize plugin-specific data
+        self.data = None
+        self.last_update_time = None
+        
+        # Load configuration values
+        self.api_key = config.get("api_key", "")
+        self.refresh_interval = config.get("refresh_interval", 60)
+        
+        self.logger.info(f"Plugin {plugin_id} initialized")
+    
+    def update(self) -> None:
+        """
+        Fetch/update data for this plugin.
+        
+        This method is called periodically based on update_interval
+        specified in the manifest. Use cache_manager to avoid
+        excessive API calls.
+        """
+        cache_key = f"{self.plugin_id}_data"
+        
+        # Check cache first
+        cached = self.cache_manager.get(cache_key, max_age=self.refresh_interval)
+        if cached:
+            self.data = cached
+            self.logger.debug("Using cached data")
+            return
+        
+        try:
+            # Fetch new data
+            self.data = self._fetch_data()
+            
+            # Cache the data
+            self.cache_manager.set(cache_key, self.data, ttl=self.refresh_interval)
+            self.last_update_time = time.time()
+            
+            self.logger.info("Data updated successfully")
+            
+        except Exception as e:
+            self.logger.error(f"Failed to update data: {e}")
+            # Use cached data if available, even if expired
+            # Use a very large max_age (1 year) to effectively bypass expiration for fallback
+            expired_cached = self.cache_manager.get(cache_key, max_age=31536000)
+            if expired_cached:
+                self.data = expired_cached
+                self.logger.warning("Using expired cache due to update failure")
+    
+    def display(self, force_clear: bool = False) -> None:
+        """
+        Render this plugin's display.
+        
+        Args:
+            force_clear: If True, clear display before rendering
+        """
+        if force_clear:
+            self.display_manager.clear()
+        
+        # Check if we have data to display
+        if not self.data:
+            self._display_error("No data available")
+            return
+        
+        try:
+            # Render plugin content
+            self._render_content()
+            
+            # Update the display
+            self.display_manager.update_display()
+            
+        except Exception as e:
+            self.logger.error(f"Display error: {e}")
+            self._display_error("Display error")
+    
+    def _fetch_data(self) -> Dict[str, Any]:
+        """
+        Fetch data from external source.
+        
+        Returns:
+            Dictionary containing fetched data
+        """
+        # TODO: Implement data fetching logic
+        # Example:
+        # import requests
+        # response = requests.get("https://api.example.com/data", 
+        #                        headers={"Authorization": f"Bearer {self.api_key}"})
+        # return response.json()
+        
+        # Placeholder
+        return {
+            "message": "Hello, World!",
+            "timestamp": time.time()
+        }
+    
+    def _render_content(self) -> None:
+        """Render the plugin content on the display."""
+        # Get display dimensions
+        width = self.display_manager.width
+        height = self.display_manager.height
+        
+        # Example: Draw text
+        text = self.data.get("message", "No data")
+        x = 5
+        y = height // 2
+        
+        self.display_manager.draw_text(
+            text,
+            x=x,
+            y=y,
+            color=(255, 255, 255)  # White
+        )
+        
+        # Example: Draw image
+        # if hasattr(self, 'logo_image'):
+        #     self.display_manager.draw_image(
+        #         self.logo_image,
+        #         x=0,
+        #         y=0
+        #     )
+    
+    def _display_error(self, message: str) -> None:
+        """Display an error message."""
+        self.display_manager.clear()
+        width = self.display_manager.width
+        height = self.display_manager.height
+        
+        self.display_manager.draw_text(
+            message,
+            x=5,
+            y=height // 2,
+            color=(255, 0, 0)  # Red
+        )
+        self.display_manager.update_display()
+    
+    def validate_config(self) -> bool:
+        """
+        Validate plugin configuration.
+        
+        Returns:
+            True if config is valid, False otherwise
+        """
+        # Call parent validation first
+        if not super().validate_config():
+            return False
+        
+        # Add custom validation
+        # Example: Check for required API key
+        # if self.config.get("require_api_key", True):
+        #     if not self.api_key:
+        #         self.logger.error("API key is required but not provided")
+        #         return False
+        
+        return True
+    
+    def has_live_content(self) -> bool:
+        """
+        Check if plugin has live content to display.
+        
+        Override this method to enable live priority features.
+        
+        Returns:
+            True if plugin has live content, False otherwise
+        """
+        # Example: Check if there's live data
+        # return self.data and self.data.get("is_live", False)
+        return False
+    
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Return plugin info for display in web UI.
+        
+        Returns:
+            Dictionary with plugin information
+        """
+        info = super().get_info()
+        
+        # Add plugin-specific info
+        info.update({
+            "data_available": self.data is not None,
+            "last_update": self.last_update_time,
+            # Add more info as needed
+        })
+        
+        return info
+    
+    def cleanup(self) -> None:
+        """Cleanup resources when plugin is unloaded."""
+        # Clean up any resources (threads, connections, etc.)
+        # Example:
+        # if hasattr(self, 'api_client'):
+        #     self.api_client.close()
+        
+        super().cleanup()
+

.cursor/plugin_templates/manifest.json.template

@@ -0,0 +1,55 @@
+{
+  "id": "PLUGIN_ID",
+  "name": "Plugin Name",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "description": "Brief description of what this plugin does",
+  "homepage": "https://github.com/username/ledmatrix-PLUGIN_ID",
+  "entry_point": "manager.py",
+  "class_name": "PluginClassName",
+  "category": "custom",
+  "tags": ["custom", "example"],
+  "icon": "fas fa-icon-name",
+  "compatible_versions": [">=2.0.0"],
+  "min_ledmatrix_version": "2.0.0",
+  "max_ledmatrix_version": "3.0.0",
+  "requires": {
+    "python": ">=3.9",
+    "display_size": {
+      "min_width": 64,
+      "min_height": 32
+    }
+  },
+  "config_schema": "config_schema.json",
+  "assets": {
+    "logos": "Optional: Description of asset requirements"
+  },
+  "update_interval": 60,
+  "default_duration": 15,
+  "display_modes": [
+    "PLUGIN_ID"
+  ],
+  "api_requirements": [
+    {
+      "name": "API Name",
+      "required": false,
+      "description": "Description of API requirements",
+      "url": "https://api.example.com",
+      "rate_limit": "Rate limit information"
+    }
+  ],
+  "download_url_template": "https://github.com/username/ledmatrix-PLUGIN_ID/archive/refs/tags/v{version}.zip",
+  "versions": [
+    {
+      "released": "2025-01-01",
+      "version": "1.0.0",
+      "ledmatrix_min_version": "2.0.0"
+    }
+  ],
+  "last_updated": "2025-01-01",
+  "stars": 0,
+  "downloads": 0,
+  "verified": false,
+  "screenshot": ""
+}
+

.cursor/plugin_templates/requirements.txt.template

@@ -0,0 +1,13 @@
+# Plugin Dependencies
+# Add your plugin's Python dependencies here
+
+# Example dependencies (uncomment and modify as needed):
+# requests>=2.28.0
+# pillow>=9.0.0
+# python-dateutil>=2.8.0
+
+# Note: Core LEDMatrix dependencies are already available:
+# - PIL/Pillow (for image handling)
+# - Core plugin system classes
+# - Display manager, cache manager, config manager
+

.cursor/plugin_templates/test_manager.py.template

@@ -0,0 +1,136 @@
+"""
+Test file for Plugin Name plugin.
+
+This file provides example unit tests for your plugin.
+Run tests with: python -m pytest test_manager.py
+Or: python test_manager.py
+"""
+
+import unittest
+import sys
+from pathlib import Path
+
+# Add project root to path
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.plugin_system.testing import PluginTestCase
+from manager import PluginClassName
+
+
+class TestPluginClassName(PluginTestCase):
+    """Test cases for PluginClassName plugin."""
+    
+    def setUp(self):
+        """Set up test fixtures."""
+        super().setUp()
+        
+        # Update plugin_id to match the plugin being tested
+        self.plugin_id = 'PLUGIN_ID'
+        
+        # Create plugin instance
+        self.plugin = self.create_plugin_instance(
+            PluginClassName,
+            plugin_id='PLUGIN_ID',
+            config=self.get_mock_config()
+        )
+    
+    def test_plugin_initialization(self):
+        """Test that plugin initializes correctly."""
+        self.assert_plugin_initialized(self.plugin)
+        self.assertTrue(self.plugin.enabled)
+    
+    def test_config_validation(self):
+        """Test configuration validation."""
+        # Valid config should pass
+        self.assertTrue(self.plugin.validate_config())
+        
+        # Test with invalid config if applicable
+        # invalid_config = self.get_mock_config(enabled='not-a-boolean')
+        # invalid_plugin = self.create_plugin_instance(
+        #     PluginClassName,
+        #     config=invalid_config
+        # )
+        # self.assertFalse(invalid_plugin.validate_config())
+    
+    def test_update_method(self):
+        """Test the update() method."""
+        # Reset mocks
+        self.cache_manager.reset()
+        
+        # Call update
+        self.plugin.update()
+        
+        # Assertions
+        # Example: Check that cache was used
+        # self.assert_cache_get('PLUGIN_ID_data')
+        
+        # Example: Check that data was fetched and cached
+        # self.assert_cache_set('PLUGIN_ID_data')
+    
+    def test_display_method(self):
+        """Test the display() method."""
+        # Ensure plugin has data (call update first if needed)
+        # self.plugin.update()
+        
+        # Call display
+        self.plugin.display(force_clear=True)
+        
+        # Assertions
+        self.assert_display_cleared()
+        self.assert_display_updated()
+        
+        # Example: Check that text was drawn
+        # self.assert_text_drawn("Expected Text")
+        
+        # Example: Check that image was drawn
+        # self.assert_image_drawn()
+    
+    def test_display_without_data(self):
+        """Test display() behavior when no data is available."""
+        # Clear any cached data
+        self.cache_manager.reset()
+        
+        # Call display
+        self.plugin.display()
+        
+        # Should handle gracefully (no exceptions)
+        # May show error message or fallback content
+        self.assert_display_updated()
+    
+    def test_get_display_duration(self):
+        """Test display duration configuration."""
+        duration = self.plugin.get_display_duration()
+        self.assertIsInstance(duration, (int, float))
+        self.assertGreater(duration, 0)
+        
+        # Test with custom duration
+        custom_config = self.get_mock_config(display_duration=30.0)
+        custom_plugin = self.create_plugin_instance(
+            PluginClassName,
+            config=custom_config
+        )
+        self.assertEqual(custom_plugin.get_display_duration(), 30.0)
+    
+    def test_enable_disable(self):
+        """Test plugin enable/disable functionality."""
+        self.assertTrue(self.plugin.enabled)
+        
+        self.plugin.on_disable()
+        self.assertFalse(self.plugin.enabled)
+        
+        self.plugin.on_enable()
+        self.assertTrue(self.plugin.enabled)
+    
+    def test_config_change(self):
+        """Test configuration change handling."""
+        new_config = self.get_mock_config(display_duration=20.0)
+        self.plugin.on_config_change(new_config)
+        
+        self.assertEqual(self.plugin.config.get('display_duration'), 20.0)
+
+
+if __name__ == '__main__':
+    unittest.main()
+

.cursor/plugins_guide.md

@@ -0,0 +1,751 @@
+# LEDMatrix Plugin Development Guide
+
+This guide provides comprehensive instructions for creating, running, and loading plugins in the LEDMatrix project.
+
+## Table of Contents
+
+1. [Plugin System Overview](#plugin-system-overview)
+2. [Creating a New Plugin](#creating-a-new-plugin)
+3. [Running Plugins](#running-plugins)
+4. [Loading Plugins](#loading-plugins)
+5. [Plugin Development Workflow](#plugin-development-workflow)
+6. [Testing Plugins](#testing-plugins)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Plugin System Overview
+
+The LEDMatrix project uses a plugin-based architecture where all display functionality (except core calendar) is implemented as plugins. Plugins are dynamically loaded from the `plugins/` directory and integrated into the display rotation.
+
+### Plugin Architecture
+
+```
+LEDMatrix Core
+├── Plugin Manager (discovers, loads, manages plugins)
+├── Display Manager (handles LED matrix rendering)
+├── Cache Manager (data persistence)
+├── Config Manager (configuration management)
+└── Plugins/ (plugin directory)
+    ├── plugin-1/
+    ├── plugin-2/
+    └── ...
+```
+
+### Plugin Lifecycle
+
+1. **Discovery**: PluginManager scans `plugins/` for directories with `manifest.json`
+2. **Loading**: Plugin module is imported and class is instantiated
+3. **Configuration**: Plugin config is loaded from `config/config.json`
+4. **Validation**: `validate_config()` is called to verify configuration
+5. **Registration**: Plugin is added to available display modes
+6. **Execution**: `update()` is called periodically, `display()` is called during rotation
+
+---
+
+## Creating a New Plugin
+
+### Method 1: Using dev_plugin_setup.sh (Recommended)
+
+This method is best for plugins stored in separate Git repositories.
+
+#### From GitHub Repository
+
+```bash
+# Link a plugin from GitHub (auto-detects URL)
+./scripts/dev/dev_plugin_setup.sh link-github <plugin-name>
+
+# Example: Link hockey-scoreboard plugin
+./scripts/dev/dev_plugin_setup.sh link-github hockey-scoreboard
+
+# With custom URL
+./scripts/dev/dev_plugin_setup.sh link-github <plugin-name> https://github.com/user/repo.git
+```
+
+The script will:
+- Clone the repository to `~/.ledmatrix-dev-plugins/` (or configured directory)
+- Create a symlink in `plugins/<plugin-name>/` pointing to the cloned repo
+- Validate the plugin structure
+
+#### From Local Repository
+
+```bash
+# Link a local plugin repository
+./scripts/dev/dev_plugin_setup.sh link <plugin-name> <path-to-repo>
+
+# Example: Link a local plugin
+./scripts/dev/dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
+```
+
+### Method 2: Manual Plugin Creation
+
+1. **Create Plugin Directory**
+
+```bash
+mkdir -p plugins/my-plugin
+cd plugins/my-plugin
+```
+
+2. **Create manifest.json**
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "description": "Description of what this plugin does",
+  "entry_point": "manager.py",
+  "class_name": "MyPlugin",
+  "category": "custom",
+  "tags": ["custom", "example"],
+  "display_modes": ["my_plugin"],
+  "update_interval": 60,
+  "default_duration": 15,
+  "requires": {
+    "python": ">=3.9"
+  },
+  "config_schema": "config_schema.json"
+}
+```
+
+3. **Create manager.py**
+
+```python
+from src.plugin_system.base_plugin import BasePlugin
+from PIL import Image
+import logging
+
+class MyPlugin(BasePlugin):
+    """My custom plugin implementation."""
+    
+    def update(self):
+        """Fetch/update data for this plugin."""
+        # Fetch data from API, files, etc.
+        # Use self.cache_manager for caching
+        cache_key = f"{self.plugin_id}_data"
+        cached = self.cache_manager.get(cache_key, max_age=3600)
+        if cached:
+            self.data = cached
+            return
+        
+        # Fetch new data
+        self.data = self._fetch_data()
+        self.cache_manager.set(cache_key, self.data)
+    
+    def display(self, force_clear=False):
+        """Render this plugin's display."""
+        if force_clear:
+            self.display_manager.clear()
+        
+        # Render content using display_manager
+        self.display_manager.draw_text(
+            "Hello, World!",
+            x=10, y=15,
+            color=(255, 255, 255)
+        )
+        
+        self.display_manager.update_display()
+    
+    def _fetch_data(self):
+        """Fetch data from external source."""
+        # Implement your data fetching logic
+        return {"message": "Hello, World!"}
+    
+    def validate_config(self):
+        """Validate plugin configuration."""
+        # Check required config fields
+        if not super().validate_config():
+            return False
+        
+        # Add custom validation
+        required_fields = ['api_key']  # Example
+        for field in required_fields:
+            if field not in self.config:
+                self.logger.error(f"Missing required field: {field}")
+                return False
+        
+        return True
+```
+
+4. **Create config_schema.json**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable or disable this plugin"
+    },
+    "display_duration": {
+      "type": "number",
+      "default": 15,
+      "minimum": 1,
+      "description": "How long to display this plugin (seconds)"
+    },
+    "api_key": {
+      "type": "string",
+      "description": "API key for external service"
+    }
+  },
+  "required": ["enabled"]
+}
+```
+
+5. **Create requirements.txt** (if needed)
+
+```
+requests>=2.28.0
+pillow>=9.0.0
+```
+
+6. **Create README.md**
+
+Document your plugin's functionality, configuration options, and usage.
+
+---
+
+## Running Plugins
+
+### Development Mode (Emulator)
+
+Run the LEDMatrix system with emulator for plugin testing:
+
+```bash
+# Using run.py
+python run.py --emulator
+
+# Using emulator script
+./run_emulator.sh
+```
+
+The emulator will:
+- Load all enabled plugins
+- Display plugin content in a window (simulating LED matrix)
+- Show logs for plugin loading and execution
+- Allow testing without Raspberry Pi hardware
+
+### Production Mode (Raspberry Pi)
+
+Run on actual Raspberry Pi hardware:
+
+```bash
+# Direct execution
+python run.py
+
+# As systemd service
+sudo systemctl start ledmatrix
+sudo systemctl status ledmatrix
+sudo journalctl -u ledmatrix -f  # View logs
+```
+
+### Plugin-Specific Testing
+
+Test individual plugin loading:
+
+```python
+# test_my_plugin.py
+from src.plugin_system.plugin_manager import PluginManager
+from src.config_manager import ConfigManager
+from src.display_manager import DisplayManager
+from src.cache_manager import CacheManager
+
+# Initialize managers
+config_manager = ConfigManager()
+config = config_manager.load_config()
+display_manager = DisplayManager(config)
+cache_manager = CacheManager()
+
+# Initialize plugin manager
+plugin_manager = PluginManager(
+    plugins_dir="plugins",
+    config_manager=config_manager,
+    display_manager=display_manager,
+    cache_manager=cache_manager
+)
+
+# Discover and load plugin
+plugins = plugin_manager.discover_plugins()
+print(f"Discovered plugins: {plugins}")
+
+if "my-plugin" in plugins:
+    if plugin_manager.load_plugin("my-plugin"):
+        plugin = plugin_manager.get_plugin("my-plugin")
+        plugin.update()
+        plugin.display()
+        print("Plugin loaded and displayed successfully!")
+    else:
+        print("Failed to load plugin")
+```
+
+---
+
+## Loading Plugins
+
+### Enabling Plugins
+
+Plugins are enabled/disabled in `config/config.json`:
+
+```json
+{
+  "my-plugin": {
+    "enabled": true,
+    "display_duration": 15,
+    "api_key": "your-api-key-here"
+  }
+}
+```
+
+### Plugin Configuration Structure
+
+Each plugin has its own section in `config/config.json`:
+
+```json
+{
+  "<plugin-id>": {
+    "enabled": true,                    // Enable/disable plugin
+    "display_duration": 15,             // Display duration in seconds
+    "live_priority": false,             // Enable live priority takeover
+    "high_performance_transitions": false, // Use 120 FPS transitions
+    "transition": {                     // Transition configuration
+      "type": "redraw",                 // Transition type
+      "speed": 2,                       // Transition speed
+      "enabled": true                   // Enable transitions
+    },
+    // ... plugin-specific configuration
+  }
+}
+```
+
+### Secrets Management
+
+Store sensitive data (API keys, tokens) in `config/config_secrets.json`
+under the same plugin id you use in `config/config.json`:
+
+```json
+{
+  "my-plugin": {
+    "api_key": "secret-api-key-here"
+  }
+}
+```
+
+At load time, the config manager deep-merges `config_secrets.json` into
+the main config (verified at `src/config_manager.py:162-172`). So in
+your plugin's code:
+
+```python
+class MyPlugin(BasePlugin):
+    def __init__(self, plugin_id, config, display_manager, cache_manager, plugin_manager):
+        super().__init__(plugin_id, config, display_manager, cache_manager, plugin_manager)
+        self.api_key = config.get("api_key")  # already merged from secrets
+```
+
+There is no separate `config_secrets` reference field — just put the
+secret value under the same plugin namespace and read it from the
+merged config.
+
+### Plugin Discovery
+
+Plugins are automatically discovered when:
+- Directory exists in `plugins/`
+- Directory contains `manifest.json`
+- Manifest has required fields (`id`, `entry_point`, `class_name`)
+
+Check discovered plugins:
+
+```bash
+# Using dev_plugin_setup.sh
+./scripts/dev/dev_plugin_setup.sh list
+
+# Output shows:
+# ✓ plugin-name (symlink)
+#   → /path/to/repo
+#   ✓ Git repo is clean (branch: main)
+```
+
+### Plugin Status
+
+Check plugin status and git information:
+
+```bash
+./scripts/dev/dev_plugin_setup.sh status
+
+# Output shows:
+# ✓ plugin-name
+#   Path: /path/to/repo
+#   Branch: main
+#   Remote: https://github.com/user/repo.git
+#   Status: Clean and up to date
+```
+
+---
+
+## Plugin Development Workflow
+
+### 1. Initial Setup
+
+```bash
+# Create or clone plugin repository
+git clone https://github.com/user/ledmatrix-my-plugin.git
+cd ledmatrix-my-plugin
+
+# Link to LEDMatrix project
+cd /path/to/LEDMatrix
+./scripts/dev/dev_plugin_setup.sh link my-plugin ../ledmatrix-my-plugin
+```
+
+### 2. Development Cycle
+
+1. **Edit plugin code** in linked repository
+2. **Test with the dev preview server**:
+   `python3 scripts/dev_server.py` (then open `http://localhost:5001`).
+   Or run the full display in emulator mode with
+   `python3 run.py --emulator` (or equivalently
+   `EMULATOR=true python3 run.py`). The `-e`/`--emulator` CLI flag is
+   defined in `run.py:19-20` and sets the same `EMULATOR` environment
+   variable internally.
+3. **Check logs** for errors or warnings
+4. **Update configuration** in `config/config.json` if needed
+5. **Iterate** until plugin works correctly
+
+### 3. Testing on Hardware
+
+```bash
+# Deploy to Raspberry Pi
+rsync -avz plugins/my-plugin/ ledpi@your-pi-ip:/path/to/LEDMatrix/plugins/my-plugin/
+
+# Or if using git, pull on Pi
+ssh ledpi@your-pi-ip "cd /path/to/LEDMatrix/plugins/my-plugin && git pull"
+
+# Restart service
+ssh ledpi@your-pi-ip "sudo systemctl restart ledmatrix"
+```
+
+### 4. Updating Plugins
+
+```bash
+# Update single plugin from git
+./scripts/dev/dev_plugin_setup.sh update my-plugin
+
+# Update all linked plugins
+./scripts/dev/dev_plugin_setup.sh update
+```
+
+### 5. Unlinking Plugins
+
+```bash
+# Remove symlink (preserves repository)
+./scripts/dev/dev_plugin_setup.sh unlink my-plugin
+```
+
+---
+
+## Testing Plugins
+
+### Unit Testing
+
+Create test files in plugin directory:
+
+```python
+# plugins/my-plugin/test_my_plugin.py
+import unittest
+from unittest.mock import Mock, MagicMock
+from manager import MyPlugin
+
+class TestMyPlugin(unittest.TestCase):
+    def setUp(self):
+        self.config = {"enabled": True}
+        self.display_manager = Mock()
+        self.cache_manager = Mock()
+        self.plugin_manager = Mock()
+        
+        self.plugin = MyPlugin(
+            plugin_id="my-plugin",
+            config=self.config,
+            display_manager=self.display_manager,
+            cache_manager=self.cache_manager,
+            plugin_manager=self.plugin_manager
+        )
+    
+    def test_plugin_initialization(self):
+        self.assertEqual(self.plugin.plugin_id, "my-plugin")
+        self.assertTrue(self.plugin.enabled)
+    
+    def test_config_validation(self):
+        self.assertTrue(self.plugin.validate_config())
+    
+    def test_update(self):
+        self.cache_manager.get.return_value = None
+        self.plugin.update()
+        # Assert data was fetched and cached
+    
+    def test_display(self):
+        self.plugin.display()
+        self.display_manager.draw_text.assert_called()
+        self.display_manager.update_display.assert_called()
+
+if __name__ == '__main__':
+    unittest.main()
+```
+
+Run tests:
+
+```bash
+cd plugins/my-plugin
+python -m pytest test_my_plugin.py
+# or
+python test_my_plugin.py
+```
+
+### Integration Testing
+
+Test plugin with actual managers:
+
+```python
+# test_plugin_integration.py
+from src.plugin_system.plugin_manager import PluginManager
+from src.config_manager import ConfigManager
+from src.display_manager import DisplayManager
+from src.cache_manager import CacheManager
+
+def test_plugin_loading():
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    display_manager = DisplayManager(config)
+    cache_manager = CacheManager()
+    
+    plugin_manager = PluginManager(
+        plugins_dir="plugins",
+        config_manager=config_manager,
+        display_manager=display_manager,
+        cache_manager=cache_manager
+    )
+    
+    plugins = plugin_manager.discover_plugins()
+    assert "my-plugin" in plugins
+    
+    assert plugin_manager.load_plugin("my-plugin")
+    plugin = plugin_manager.get_plugin("my-plugin")
+    assert plugin is not None
+    assert plugin.enabled
+    
+    plugin.update()
+    plugin.display()
+```
+
+### Emulator Testing
+
+Test plugin rendering visually:
+
+```bash
+# Run with emulator
+python run.py --emulator
+
+# Plugin should appear in display rotation
+# Check logs for plugin loading and execution
+```
+
+### Hardware Testing
+
+1. Deploy plugin to Raspberry Pi
+2. Enable in `config/config.json`
+3. Restart LEDMatrix service
+4. Observe LED matrix display
+5. Check logs: `journalctl -u ledmatrix -f`
+
+---
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+**Symptoms**: Plugin doesn't appear in available modes, no logs about plugin
+
+**Solutions**:
+1. Check plugin directory exists: `ls plugins/my-plugin/`
+2. Verify `manifest.json` exists and is valid JSON
+3. Check manifest has required fields: `id`, `entry_point`, `class_name`
+4. Verify entry_point file exists: `ls plugins/my-plugin/manager.py`
+5. Check class name matches: `grep "class.*Plugin" plugins/my-plugin/manager.py`
+6. Review logs for import errors
+
+### Plugin Loading but Not Displaying
+
+**Symptoms**: Plugin loads successfully but doesn't appear in rotation
+
+**Solutions**:
+1. Check plugin is enabled: `config/config.json` has `"enabled": true`
+2. Verify display_modes in manifest match config
+3. Check plugin is in rotation schedule
+4. Review `display()` method for errors
+5. Check logs for runtime errors
+
+### Configuration Errors
+
+**Symptoms**: Plugin fails to load, validation errors in logs
+
+**Solutions**:
+1. Validate config against `config_schema.json`
+2. Check required fields are present
+3. Verify data types match schema
+4. Check for typos in config keys
+5. Review `validate_config()` method
+
+### Import Errors
+
+**Symptoms**: ModuleNotFoundError or ImportError in logs
+
+**Solutions**:
+1. Install plugin dependencies: `pip install -r plugins/my-plugin/requirements.txt`
+2. Check Python path includes plugin directory
+3. Verify relative imports are correct
+4. Check for circular import issues
+5. Ensure all dependencies are in requirements.txt
+
+### Display Issues
+
+**Symptoms**: Plugin renders incorrectly or not at all
+
+**Solutions**:
+1. Check display dimensions: `display_manager.width`, `display_manager.height`
+2. Verify coordinates are within display bounds
+3. Check color values are valid (0-255)
+4. Ensure `update_display()` is called after rendering
+5. Test with emulator first to debug rendering
+
+### Performance Issues
+
+**Symptoms**: Slow display updates, high CPU usage
+
+**Solutions**:
+1. Use `cache_manager` to avoid excessive API calls
+2. Implement background data fetching
+3. Optimize rendering code
+4. Consider using `high_performance_transitions`
+5. Profile plugin code to identify bottlenecks
+
+### Git/Symlink Issues
+
+**Symptoms**: Plugin changes not appearing, broken symlinks
+
+**Solutions**:
+1. Check symlink: `ls -la plugins/my-plugin`
+2. Verify target exists: `readlink -f plugins/my-plugin`
+3. Update plugin: `./scripts/dev/dev_plugin_setup.sh update my-plugin`
+4. Re-link plugin if needed: `./scripts/dev/dev_plugin_setup.sh unlink my-plugin && ./scripts/dev/dev_plugin_setup.sh link my-plugin <path>`
+5. Check git status: `cd plugins/my-plugin && git status`
+
+---
+
+## Best Practices
+
+### Code Organization
+
+- Keep plugin code in `plugins/<plugin-id>/` directory
+- Use descriptive class and method names
+- Follow existing plugin patterns
+- Place shared utilities in `src/common/` if reusable
+
+### Configuration
+
+- Always use `config_schema.json` for validation
+- Store secrets in `config_secrets.json`
+- Provide sensible defaults
+- Document all configuration options in README
+
+### Error Handling
+
+- Use plugin logger for all logging
+- Handle API failures gracefully
+- Provide fallback displays when data unavailable
+- Cache data to avoid excessive requests
+
+### Performance
+
+- Cache API responses appropriately
+- Use background data fetching for long operations
+- Optimize rendering for Pi's limited resources
+- Test performance on actual hardware
+
+### Testing
+
+- Write unit tests for core logic
+- Test with emulator before hardware
+- Test on Raspberry Pi before deploying
+- Test with other plugins enabled
+
+### Documentation
+
+- Document plugin functionality in README
+- Include configuration examples
+- Document API requirements and rate limits
+- Provide usage examples
+
+---
+
+## Resources
+
+- **Plugin System Documentation**: `docs/PLUGIN_ARCHITECTURE_SPEC.md`
+- **Base Plugin Class**: `src/plugin_system/base_plugin.py`
+- **Plugin Manager**: `src/plugin_system/plugin_manager.py`
+- **Example Plugins**: 
+  - `plugins/hockey-scoreboard/` - Sports scoreboard example
+  - `plugins/football-scoreboard/` - Complex multi-league example
+  - `plugins/ledmatrix-music/` - Real-time data example
+- **Development Setup**: `dev_plugin_setup.sh`
+- **Example Config**: `dev_plugins.json.example`
+
+---
+
+## Quick Reference
+
+### Common Commands
+
+```bash
+# Link plugin from GitHub
+./scripts/dev/dev_plugin_setup.sh link-github <name>
+
+# Link local plugin
+./scripts/dev/dev_plugin_setup.sh link <name> <path>
+
+# List all plugins
+./scripts/dev/dev_plugin_setup.sh list
+
+# Check plugin status
+./scripts/dev/dev_plugin_setup.sh status
+
+# Update plugin(s)
+./scripts/dev/dev_plugin_setup.sh update [name]
+
+# Unlink plugin
+./scripts/dev/dev_plugin_setup.sh unlink <name>
+
+# Run with emulator
+python run.py --emulator
+
+# Run on Pi
+python run.py
+```
+
+### Plugin File Structure
+
+```
+plugins/my-plugin/
+├── manifest.json          # Required: Plugin metadata
+├── manager.py             # Required: Plugin class
+├── config_schema.json     # Required: Config validation
+├── requirements.txt       # Optional: Dependencies
+├── README.md              # Optional: Documentation
+└── ...                    # Plugin-specific files
+```
+
+### Required Manifest Fields
+
+- `id`: Plugin identifier
+- `entry_point`: Python file (usually "manager.py")
+- `class_name`: Plugin class name
+- `display_modes`: Array of mode names
+

.cursor/rules/coding-standards.mdc

@@ -0,0 +1,38 @@
+---
+globs: *.py
+---
+
+# Python Coding Standards
+
+## Code Quality Principles
+- **Simplicity First**: Prefer clear, readable code over clever optimizations
+- **Explicit over Implicit**: Make intentions clear through naming and structure
+- **Fail Fast**: Validate inputs and handle errors early
+- **Documentation**: Use docstrings for classes and complex functions
+
+## Naming Conventions
+- **Classes**: PascalCase (e.g., `NHLRecentManager`)
+- **Functions/Variables**: snake_case (e.g., `fetch_game_data`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `ESPN_NHL_SCOREBOARD_URL`)
+- **Private methods**: Leading underscore (e.g., `_fetch_data`)
+
+## Error Handling
+- **Logging**: Use structured logging with context (e.g., `[NHL Recent]`)
+- **Exceptions**: Catch specific exceptions, not bare `except:`
+- **User-friendly messages**: Explain what went wrong and potential solutions
+- **Graceful degradation**: Continue operation when non-critical features fail
+
+## Manager Pattern
+All sports managers should follow this structure:
+```python
+class BaseManager:
+    def __init__(self, config, display_manager, cache_manager)
+    def update(self)  # Fetch and process data
+    def display(self, force_clear=False)  # Render to display
+```
+
+## Configuration Management
+- **Type hints**: Use for function parameters and return values
+- **Configuration validation**: Check required fields on initialization
+- **Default values**: Provide sensible defaults in code, not config
+- **Environment awareness**: Handle different deployment contexts

.cursor/rules/configuration-management.mdc

@@ -0,0 +1,42 @@
+---
+globs: config/*.json,src/*.py
+---
+
+# Configuration Management
+
+## Configuration Structure
+- **Main config**: [config/config.json](mdc:config/config.json) - Primary configuration
+- **Secrets**: [config/config_secrets.json](mdc:config/config_secrets.json) - API keys and sensitive data
+- **Templates**: [config/config.template.json](mdc:config/config.template.json) - Default values
+
+## Configuration Principles
+- **Validation**: Check required fields and data types on startup
+- **Defaults**: Provide sensible defaults in code, not just config
+- **Environment awareness**: Handle development vs production differences
+- **Security**: Never commit secrets to version control
+
+## Manager Configuration Pattern
+```python
+def __init__(self, config, display_manager, cache_manager):
+    self.mode_config = config.get("sport_scoreboard", {})
+    self.favorite_teams = self.mode_config.get("favorite_teams", [])
+    self.show_favorite_only = self.mode_config.get("show_favorite_teams_only", False)
+```
+
+## Required Configuration Sections
+- **Display settings**: Update intervals, display durations
+- **API settings**: Timeouts, retry logic, rate limiting
+- **Background service**: Threading, caching, priority settings
+- **Team preferences**: Favorite teams, filtering options
+
+## Configuration Validation
+- **Type checking**: Ensure numeric values are numbers, lists are lists
+- **Range validation**: Check that intervals are reasonable
+- **Dependency checking**: Verify required services are available
+- **Fallback values**: Provide defaults when config is missing or invalid
+
+## Best Practices
+- **Documentation**: Comment complex configuration options
+- **Examples**: Provide working examples in templates
+- **Migration**: Handle configuration changes between versions
+- **Testing**: Validate configuration in test environments

.cursor/rules/error-handling-logging.mdc

@@ -0,0 +1,50 @@
+---
+globs: src/*.py
+---
+
+# Error Handling and Logging
+
+## Logging Standards
+- **Structured prefixes**: Use consistent tags like `[NHL Recent]`, `[NFL Live]`
+- **Context information**: Include relevant details (team names, game status, dates)
+- **Appropriate levels**: 
+  - `info`: Normal operations and status updates
+  - `debug`: Detailed information for troubleshooting
+  - `warning`: Non-critical issues that should be noted
+  - `error`: Problems that need attention
+
+## Error Handling Patterns
+```python
+try:
+    data = self._fetch_data()
+    if not data or 'events' not in data:
+        self.logger.warning("[Manager] No events found in API response")
+        return
+except requests.exceptions.RequestException as e:
+    self.logger.error(f"[Manager] API error: {e}")
+    return None
+```
+
+## User-Friendly Messages
+- **Explain the situation**: "No games available during off-season"
+- **Provide context**: "NHL season typically runs October-June"
+- **Suggest solutions**: "Check back when season starts"
+- **Distinguish issues**: API problems vs no data vs filtering results
+
+## Graceful Degradation
+- **Fallback content**: Show alternative games when favorites unavailable
+- **Cached data**: Use cached data when API fails
+- **Service continuity**: Continue operation when non-critical features fail
+- **Clear communication**: Explain what's happening to users
+
+## Debugging Support
+- **Comprehensive logging**: Log API responses, filtering results, display updates
+- **State tracking**: Log current state and transitions
+- **Performance monitoring**: Track timing and resource usage
+- **Error context**: Include stack traces for debugging
+
+## Off-Season Awareness
+- **Seasonal messaging**: Different messages for different times of year
+- **Helpful context**: Explain why no games are available
+- **Future planning**: Mention when season starts
+- **Realistic expectations**: Set appropriate expectations during off-season

.cursor/rules/git-workflow.mdc

@@ -0,0 +1,51 @@
+---
+alwaysApply: true
+---
+
+# Git Workflow and Branching
+
+## Branch Naming Conventions
+- **Features**: `feature/description-of-feature` (e.g., `feature/weather-forecast-improvements`)
+- **Bug fixes**: `fix/description-of-bug` (e.g., `fix/nhl-manager-improvements`)
+- **Hotfixes**: `hotfix/critical-issue-description`
+- **Refactoring**: `refactor/description-of-refactor`
+
+## Commit Message Format
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types**: feat, fix, docs, style, refactor, test, chore
+**Examples**:
+- `feat(nhl): Add enhanced logging for data visibility`
+- `fix(display): Resolve rendering performance issue`
+- `docs(api): Update ESPN API integration guide`
+
+## Pull Request Guidelines
+- **Self-review**: Review your own PR before requesting review
+- **Testing**: Test thoroughly on Raspberry Pi hardware
+- **Documentation**: Update relevant documentation if needed
+- **Clean history**: Squash commits if necessary for clean history
+
+## Code Review Checklist
+- **Code Quality**: Proper error handling, logging, type hints
+- **Architecture**: Follows project patterns, doesn't break existing functionality
+- **Performance**: No negative impact on display performance
+- **Testing**: Works on Raspberry Pi hardware
+- **Documentation**: Comments added for complex logic
+
+## Merge Strategies
+- **Squash and Merge**: Preferred for feature branches and bug fixes
+- **Merge Commit**: For complex features with multiple logical commits
+- **Rebase and Merge**: For simple, single-commit changes
+
+## Best Practices
+- **Keep branches small and focused**
+- **Commit frequently with meaningful messages**
+- **Update branch regularly with main**
+- **Test changes incrementally**
+- **Delete feature branches after merge**

.cursor/rules/github-branches-rule.mdc

@@ -0,0 +1,213 @@
+---
+description: GitHub branching and pull request best practices for LEDMatrix project
+globs: ["**/*.py", "**/*.md", "**/*.json", "**/*.sh"]
+alwaysApply: true
+---
+
+# GitHub Branching and Pull Request Guidelines
+
+## Branch Naming Conventions
+
+### Feature Branches
+- **Format**: `feature/description-of-feature`
+- **Examples**: 
+  - `feature/weather-forecast-improvements`
+  - `feature/stock-api-integration`
+  - `feature/nba-live-scores`
+
+### Bug Fix Branches
+- **Format**: `fix/description-of-bug`
+- **Examples**:
+  - `fix/leaderboard-scrolling-performance`
+  - `fix/weather-api-timeout`
+  - `fix/display-rendering-issue`
+
+### Hotfix Branches
+- **Format**: `hotfix/critical-issue-description`
+- **Examples**:
+  - `hotfix/display-crash-fix`
+  - `hotfix/api-rate-limit-fix`
+
+### Refactoring Branches
+- **Format**: `refactor/description-of-refactor`
+- **Examples**:
+  - `refactor/sports-manager-architecture`
+  - `refactor/cache-management-system`
+
+## Branch Management Rules
+
+### Main Branch Protection
+- **`main`** branch is protected and requires PR reviews
+- Never commit directly to `main`
+- All changes must go through pull requests
+
+### Branch Lifecycle
+1. **Create** branch from `main` when starting work
+2. **Keep** branch up-to-date with `main` regularly
+3. **Test** thoroughly before creating PR
+4. **Delete** branch after successful merge
+
+### Branch Updates
+```bash
+# Before starting new work
+git checkout main
+git pull origin main
+
+# Create new branch
+git checkout -b feature/your-feature-name
+
+# Keep branch updated during development
+git checkout main
+git pull origin main
+git checkout feature/your-feature-name
+git merge main
+```
+
+## Pull Request Guidelines
+
+### PR Title Format
+- **Feature**: `feat: Add weather forecast improvements`
+- **Fix**: `fix: Resolve leaderboard scrolling performance issue`
+- **Refactor**: `refactor: Improve sports manager architecture`
+- **Docs**: `docs: Update API integration guide`
+- **Test**: `test: Add unit tests for weather manager`
+
+### PR Description Template
+```markdown
+## Description
+Brief description of changes and motivation.
+
+## Type of Change
+- [ ] Bug fix (non-breaking change)
+- [ ] New feature (non-breaking change)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Refactoring
+
+## Testing
+- [ ] Tested on Raspberry Pi hardware
+- [ ] Verified display rendering works correctly
+- [ ] Checked API integration functionality
+- [ ] Tested error handling scenarios
+
+## Screenshots/Videos
+(If applicable, add screenshots or videos of the changes)
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] No hardcoded values or API keys
+- [ ] Error handling implemented
+- [ ] Logging added where appropriate
+```
+
+### PR Review Requirements
+
+#### For Reviewers
+- **Code Quality**: Check for proper error handling, logging, and type hints
+- **Architecture**: Ensure changes follow project patterns and don't break existing functionality
+- **Performance**: Verify changes don't negatively impact display performance
+- **Testing**: Confirm changes work on Raspberry Pi hardware
+- **Documentation**: Check if documentation needs updates
+
+#### For Authors
+- **Self-Review**: Review your own PR before requesting review
+- **Testing**: Test thoroughly on Pi hardware before submitting
+- **Documentation**: Update relevant documentation if needed
+- **Clean History**: Squash commits if necessary for clean history
+
+## Commit Message Guidelines
+
+### Format
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+- **feat**: New feature
+- **fix**: Bug fix
+- **docs**: Documentation changes
+- **style**: Code style changes (formatting, etc.)
+- **refactor**: Code refactoring
+- **test**: Adding or updating tests
+- **chore**: Maintenance tasks
+
+### Examples
+```
+feat(weather): Add hourly forecast display
+fix(nba): Resolve live score update issue
+docs(api): Update ESPN API integration guide
+refactor(sports): Improve base class architecture
+```
+
+## Merge Strategies
+
+### Squash and Merge (Preferred)
+- Use for feature branches and bug fixes
+- Creates clean, linear history
+- Combines all commits into single commit
+
+### Merge Commit
+- Use for complex features with multiple logical commits
+- Preserves commit history
+- Use when commit messages are meaningful
+
+### Rebase and Merge
+- Use sparingly for simple, single-commit changes
+- Creates linear history without merge commits
+
+## Release Management
+
+### Version Tags
+- Use semantic versioning: `v1.2.3`
+- Tag releases on `main` branch
+- Create release notes with technical details
+
+### Release Branches
+- **Format**: `release/v1.2.3`
+- Use for release preparation
+- Include version bumps and final testing
+
+## Emergency Procedures
+
+### Hotfix Process
+1. Create `hotfix/` branch from `main`
+2. Make minimal fix
+3. Test thoroughly
+4. Create PR with expedited review
+5. Merge to `main` and tag release
+6. Cherry-pick to other branches if needed
+
+### Rollback Process
+1. Identify last known good commit
+2. Create revert PR if possible
+3. Use `git revert` for clean rollback
+4. Tag rollback release
+5. Document issue and resolution
+
+## Best Practices
+
+### Before Creating PR
+- [ ] Run all tests locally
+- [ ] Test on Raspberry Pi hardware
+- [ ] Check for linting errors
+- [ ] Update documentation if needed
+- [ ] Ensure commit messages are clear
+
+### During Development
+- [ ] Keep branches small and focused
+- [ ] Commit frequently with meaningful messages
+- [ ] Update branch regularly with main
+- [ ] Test changes incrementally
+
+### After PR Approval
+- [ ] Delete feature branch after merge
+- [ ] Update local main branch
+- [ ] Verify changes work in production
+- [ ] Update any related documentation

.cursor/rules/project-structure.mdc

@@ -0,0 +1,23 @@
+---
+alwaysApply: true
+---
+
+# LEDMatrix Project Structure
+
+## Core Architecture
+- **Main entry point**: [run.py](mdc:run.py) - Primary application launcher
+- **Configuration**: [config/config.json](mdc:config/config.json) - Main configuration file
+- **Display management**: [src/display_controller.py](mdc:src/display_controller.py) - Core display logic
+- **Web interface**: [web_interface_v2.py](mdc:web_interface_v2.py) - Modern web UI
+
+## Source Code Organization
+- **Managers**: [src/](mdc:src/) - All sports/weather/stock managers
+- **Assets**: [assets/](mdc:assets/) - Logos, fonts, and static resources
+- **Tests**: [test/](mdc:test/) - Unit and integration tests
+- **Documentation**: [LEDMatrix.wiki/](mdc:LEDMatrix.wiki/) - Comprehensive guides
+
+## Key Design Principles
+- **Single Responsibility**: Each manager handles one sport/domain
+- **Consistent Patterns**: All managers follow similar structure
+- **Configuration-Driven**: Behavior controlled via [config/config.json](mdc:config/config.json)
+- **Raspberry Pi Focus**: Optimized for Pi hardware, not Windows development

.cursor/rules/raspberry-pi-development.mdc

@@ -0,0 +1,41 @@
+---
+alwaysApply: true
+---
+
+# Raspberry Pi Development Guidelines
+
+## Hardware Constraints
+- **Pi-only execution**: Code must run on Raspberry Pi, not Windows development machine
+- **LED matrix library**: Uses [rpi-rgb-led-matrix-master/](mdc:rpi-rgb-led-matrix-master/) for hardware control
+- **Memory limitations**: Optimize for Pi's limited RAM
+- **Performance**: Consider Pi's CPU capabilities in design
+
+## Development Workflow
+- **Local development**: Write and test code on Windows
+- **Pi deployment**: Deploy and test on actual Pi hardware
+- **SSH access**: Use SSH for Pi-based testing and debugging
+- **Service management**: Use systemd services for production deployment
+
+## Testing Strategy
+- **Unit tests**: Test logic without hardware dependencies
+- **Integration tests**: Test with mock display managers
+- **Hardware tests**: Validate on actual Pi with LED matrix
+- **Performance tests**: Monitor memory and CPU usage
+
+## Deployment Considerations
+- **Service files**: [ledmatrix.service](mdc:ledmatrix.service), [ledmatrix-web.service](mdc:ledmatrix-web.service)
+- **Installation scripts**: [first_time_install.sh](mdc:first_time_install.sh), [install_service.sh](mdc:install_service.sh)
+- **Dependencies**: [requirements.txt](mdc:requirements.txt) for Pi environment
+- **Permissions**: Handle file permissions for Pi user
+
+## Performance Optimization
+- **Caching**: Use [src/cache_manager.py](mdc:src/cache_manager.py) for data persistence
+- **Background services**: Non-blocking data fetching
+- **Memory management**: Clean up resources regularly
+- **Display optimization**: Minimize unnecessary redraws
+
+## Debugging on Pi
+- **Logging**: Comprehensive logging for remote debugging
+- **Error reporting**: Clear error messages for troubleshooting
+- **Status monitoring**: Health checks and status reporting
+- **Remote access**: Web interface for configuration and monitoring

.cursor/rules/sports-managers.mdc

@@ -0,0 +1,42 @@
+---
+globs: src/*_managers.py
+---
+
+# Sports Manager Development
+
+## Manager Architecture
+All sports managers inherit from base classes and follow consistent patterns:
+- **Base classes**: [src/nhl_managers.py](mdc:src/nhl_managers.py), [src/nfl_managers.py](mdc:src/nfl_managers.py)
+- **Common functionality**: Data fetching, caching, display rendering
+- **Configuration-driven**: Behavior controlled via config sections
+
+## Required Methods
+```python
+def __init__(self, config, display_manager, cache_manager)
+def update(self)  # Fetch fresh data
+def display(self, force_clear=False)  # Render current data
+```
+
+## Data Flow Pattern
+1. **Fetch**: Get data from API (with caching)
+2. **Process**: Extract relevant game information
+3. **Filter**: Apply favorite team preferences
+4. **Display**: Render to LED matrix
+
+## Logging Standards
+- **Structured prefixes**: `[NHL Recent]`, `[NFL Live]`, etc.
+- **Context information**: Include team names, game status, dates
+- **Debug levels**: Use appropriate log levels (info, debug, warning, error)
+- **User-friendly messages**: Explain what's happening and why
+
+## Error Handling
+- **API failures**: Log and continue with cached data if available
+- **No data scenarios**: Distinguish between API issues vs no games available
+- **Off-season awareness**: Provide helpful context during non-active periods
+- **Fallback behavior**: Show alternative content when preferred content unavailable
+
+## Configuration Integration
+- **Required settings**: Validate on initialization
+- **Optional settings**: Provide sensible defaults
+- **Background service**: Use for non-blocking data fetching
+- **Caching strategy**: Implement intelligent cache management

.cursor/rules/testing-standards.mdc

@@ -0,0 +1,51 @@
+---
+globs: test/*.py,src/*.py
+---
+
+# Testing Standards
+
+## Test Organization
+- **Test directory**: [test/](mdc:test/) - All test files
+- **Unit tests**: Test individual components in isolation
+- **Integration tests**: Test component interactions
+- **Hardware tests**: Validate on Raspberry Pi with actual LED matrix
+
+## Testing Principles
+- **Test behavior, not implementation**: Focus on what the code does, not how
+- **Mock external dependencies**: Use mocks for APIs, display managers, cache
+- **Test edge cases**: Empty data, API failures, configuration errors
+- **Pi-specific testing**: Validate hardware integration
+
+## Test Structure
+```python
+def test_manager_initialization():
+    """Test that manager initializes with valid config"""
+    config = {"sport_scoreboard": {"enabled": True}}
+    manager = ManagerClass(config, mock_display, mock_cache)
+    assert manager.enabled == True
+
+def test_api_failure_handling():
+    """Test graceful handling of API failures"""
+    # Test that system continues when API fails
+    # Verify fallback to cached data
+    # Check appropriate error logging
+```
+
+## Mock Patterns
+- **Display Manager**: Mock for testing without hardware
+- **Cache Manager**: Mock for testing data persistence
+- **API responses**: Mock for consistent test data
+- **Configuration**: Use test-specific configs
+
+## Test Categories
+- **Unit tests**: Individual manager methods
+- **Integration tests**: Manager interactions with services
+- **Configuration tests**: Validate config loading and validation
+- **Error handling tests**: API failures, invalid data, edge cases
+
+## Testing Best Practices
+- **Descriptive names**: Test names should explain what they test
+- **Single responsibility**: Each test should verify one thing
+- **Independent tests**: Tests should not depend on each other
+- **Clean setup/teardown**: Reset state between tests
+- **Pi compatibility**: Ensure tests work in Pi environment

.cursorignore

@@ -0,0 +1 @@
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)

.cursorrules

@@ -0,0 +1,364 @@
+# LEDMatrix Plugin Development Rules
+
+## Plugin System Overview
+
+The LEDMatrix project uses a plugin-based architecture. All display
+functionality (except core calendar) is implemented as plugins that are
+dynamically loaded from the directory configured by
+`plugin_system.plugins_directory` in `config.json` — the default is
+`plugin-repos/` (per `config/config.template.json:130`).
+
+> **Fallback note (scoped):** `PluginManager.discover_plugins()`
+> (`src/plugin_system/plugin_manager.py:154`) only scans the
+> configured directory — there is no fallback to `plugins/` in the
+> main discovery path. A fallback to `plugins/` does exist in two
+> narrower places:
+> - `store_manager.py:1700-1718` — store operations (install/update/
+>   uninstall) check `plugins/` if the plugin isn't found in the
+>   configured directory, so plugin-store flows work even when your
+>   dev symlinks live in `plugins/`.
+> - `schema_manager.py:70-80` — `get_schema_path()` probes both
+>   `plugins/` and `plugin-repos/` for `config_schema.json` so the
+>   web UI form generation finds the schema regardless of where the
+>   plugin lives.
+>
+> The dev workflow in `scripts/dev/dev_plugin_setup.sh` creates
+> symlinks under `plugins/`, which is why the store and schema
+> fallbacks exist. For day-to-day development, set
+> `plugin_system.plugins_directory` to `plugins` so the main
+> discovery path picks up your symlinks.
+
+## Plugin Structure
+
+### Required Files
+- **manifest.json**: Plugin metadata, entry point, class name, dependencies
+- **manager.py**: Main plugin class (must inherit from `BasePlugin`)
+- **config_schema.json**: JSON schema for plugin configuration validation
+- **requirements.txt**: Python dependencies (if any)
+- **README.md**: Plugin documentation
+
+### Plugin Class Requirements
+- Must inherit from `src.plugin_system.base_plugin.BasePlugin`
+- Must implement `update()` method for data fetching
+- Must implement `display()` method for rendering
+- Should implement `validate_config()` for configuration validation
+- Optional: Override `has_live_content()` for live priority features
+
+## Plugin Development Workflow
+
+### 1. Creating a New Plugin
+
+**Option A: Use dev_plugin_setup.sh (Recommended)**
+```bash
+# Link from GitHub
+./scripts/dev/dev_plugin_setup.sh link-github <plugin-name>
+
+# Link local repository
+./scripts/dev/dev_plugin_setup.sh link <plugin-name> <path-to-repo>
+```
+
+**Option B: Manual Setup**
+1. Create directory in `plugin-repos/<plugin-id>/` (or `plugins/<plugin-id>/`
+   if you're using the dev fallback location)
+2. Add `manifest.json` with required fields
+3. Create `manager.py` with plugin class
+4. Add `config_schema.json` for configuration
+5. Enable plugin in `config/config.json` under `"<plugin-id>": {"enabled": true}`
+
+### 2. Plugin Configuration
+
+Plugins are configured in `config/config.json`:
+```json
+{
+  "<plugin-id>": {
+    "enabled": true,
+    "display_duration": 15,
+    "live_priority": false,
+    "high_performance_transitions": false,
+    "transition": {
+      "type": "redraw",
+      "speed": 2,
+      "enabled": true
+    },
+    // ... plugin-specific config
+  }
+}
+```
+
+### 3. Testing Plugins
+
+**On Development Machine:**
+- Run the dev preview server: `python3 scripts/dev_server.py` (then
+  open `http://localhost:5001`) — renders plugins in the browser
+  without running the full display loop
+- Or run the full display in emulator mode:
+  `python3 run.py --emulator` (or equivalently
+  `EMULATOR=true python3 run.py`, or `./scripts/dev/run_emulator.sh`).
+  The `-e`/`--emulator` CLI flag is defined in `run.py:19-20`.
+- Test plugin loading: Check logs for plugin discovery and loading
+- Validate configuration: Ensure config matches `config_schema.json`
+
+**On Raspberry Pi:**
+- Deploy and test on actual hardware
+- Monitor logs: `journalctl -u ledmatrix -f` (if running as service)
+- Check plugin status in web interface
+
+### 4. Plugin Development Best Practices
+
+**Code Organization:**
+- Keep plugin code in `plugin-repos/<plugin-id>/` (or its dev-time
+  symlink in `plugins/<plugin-id>/`)
+- Use shared assets from `assets/` directory when possible
+- Follow existing plugin patterns — canonical sources live in the
+  [`ledmatrix-plugins`](https://github.com/ChuckBuilds/ledmatrix-plugins)
+  repo (`plugins/hockey-scoreboard/`, `plugins/football-scoreboard/`,
+  `plugins/clock-simple/`, etc.)
+- Place shared utilities in `src/common/` if reusable across plugins
+
+**Configuration Management:**
+- Use `config_schema.json` for validation
+- Store secrets in `config/config_secrets.json` under the same plugin
+  id namespace as the main config — they're deep-merged into the main
+  config at load time (`src/config_manager.py:162-172`), so plugin
+  code reads them directly from `config.get(...)` like any other key
+- There is no separate `config_secrets` reference field
+- Validate all required fields in `validate_config()`
+
+**Error Handling:**
+- Use plugin's logger: `self.logger.info/error/warning()`
+- Handle API failures gracefully
+- Cache data to avoid excessive API calls
+- Provide fallback displays when data unavailable
+
+**Performance:**
+- Use `cache_manager` for API response caching
+- Implement background data fetching if needed
+- Use `high_performance_transitions` for smoother animations
+- Optimize rendering for Pi's limited resources
+
+**Display Rendering:**
+- Use `display_manager` for all drawing operations
+- Support different display sizes (check `display_manager.width/height`)
+- Use `apply_transition()` for smooth transitions between displays
+- Clear display before rendering: `display_manager.clear()`
+- Always call `display_manager.update_display()` after rendering
+
+## Plugin API Reference
+
+### BasePlugin Class
+Located in: `src/plugin_system/base_plugin.py`
+
+**Required Methods:**
+- `update()`: Fetch/update data (called based on `update_interval` in manifest)
+- `display(force_clear=False)`: Render plugin content
+
+**Optional Methods:**
+- `validate_config()`: Validate plugin configuration
+- `has_live_content()`: Return True if plugin has live/urgent content
+- `get_live_modes()`: Return list of modes for live priority
+- `cleanup()`: Clean up resources on unload
+- `on_config_change(new_config)`: Handle config updates
+- `on_enable()`: Called when plugin enabled
+- `on_disable()`: Called when plugin disabled
+
+**Available Properties:**
+- `self.plugin_id`: Plugin identifier
+- `self.config`: Plugin configuration dict
+- `self.display_manager`: Display manager instance
+- `self.cache_manager`: Cache manager instance
+- `self.plugin_manager`: Plugin manager reference
+- `self.logger`: Plugin-specific logger
+- `self.enabled`: Boolean enabled status
+- `self.transition_manager`: Transition system (if available)
+
+### Display Manager
+Located in: `src/display_manager.py`
+
+**Key Methods:**
+- `clear()`: Clear the display
+- `draw_text(text, x, y, color, font, small_font, centered)`: Draw text
+- `update_display()`: Push the buffer to the physical display
+- `draw_weather_icon(condition, x, y, size)`: Draw a weather icon
+- `width`, `height`: Display dimensions
+
+**Image rendering**: there is no `draw_image()` helper. Paste directly
+onto the underlying PIL Image:
+```python
+self.display_manager.image.paste(pil_image, (x, y))
+self.display_manager.update_display()
+```
+For transparency, paste with a mask: `image.paste(rgba, (x, y), rgba)`.
+
+### Cache Manager
+Located in: `src/cache_manager.py`
+
+**Key Methods:**
+- `get(key, max_age=300)`: Get cached value (returns None if missing/stale)
+- `set(key, value, ttl=None)`: Cache a value
+- `delete(key)` / `clear_cache(key=None)`: Remove a single cache entry,
+  or (for `clear_cache` with no argument) every cached entry. `delete`
+  is an alias for `clear_cache(key)`.
+- `get_cached_data_with_strategy(key, data_type)`: Cache get with
+  data-type-aware TTL strategy
+- `get_background_cached_data(key, sport_key)`: Cache get for the
+  background-fetch service path
+
+## Plugin Manifest Schema
+
+Required fields in `manifest.json`:
+- `id`: Unique plugin identifier (matches directory name)
+- `name`: Human-readable plugin name
+- `version`: Semantic version (e.g., "1.0.0")
+- `entry_point`: Python file (usually "manager.py")
+- `class_name`: Plugin class name (must match class in entry_point)
+- `display_modes`: Array of mode names this plugin provides
+
+Common optional fields:
+- `description`: Plugin description
+- `author`: Plugin author
+- `homepage`: Plugin homepage URL
+- `category`: Plugin category (e.g., "sports", "weather")
+- `tags`: Array of tags
+- `update_interval`: Seconds between update() calls (default: 60)
+- `default_duration`: Default display duration (default: 15)
+- `requires`: Python version, display size requirements
+- `config_schema`: Path to config schema file
+- `api_requirements`: API dependencies and rate limits
+
+## Plugin Loading Process
+
+1. **Discovery**: PluginManager scans `plugins/` directory for directories containing `manifest.json`
+2. **Validation**: Validates manifest structure and required fields
+3. **Loading**: Imports plugin module and instantiates plugin class
+4. **Configuration**: Loads plugin config from `config/config.json`
+5. **Validation**: Calls `validate_config()` on plugin instance
+6. **Registration**: Adds plugin to available modes and stores instance
+7. **Enablement**: Calls `on_enable()` if plugin is enabled
+
+## Common Plugin Patterns
+
+### Sports Scoreboard Plugin
+- Use `background_data_service.py` pattern for API fetching
+- Implement live/recent/upcoming game modes
+- Use `scoreboard_renderer.py` for consistent rendering
+- Support team filtering and game filtering
+- Use shared sports logos from `assets/sports/`
+
+### Data Display Plugin
+- Fetch data in `update()` method
+- Cache API responses using `cache_manager`
+- Render in `display()` method
+- Handle API errors gracefully
+- Provide configuration for refresh intervals
+
+### Real-time Content Plugin
+- Implement `has_live_content()` for live priority
+- Use `get_live_modes()` to specify which modes are live
+- Set `live_priority: true` in config to enable live takeover
+- Update data frequently when live content exists
+
+## Debugging Plugins
+
+**Check Plugin Loading:**
+- Review logs for plugin discovery messages
+- Verify manifest.json syntax is valid JSON
+- Check that class_name matches actual class name
+- Ensure entry_point file exists and is importable
+
+**Check Plugin Execution:**
+- Add logging statements in `update()` and `display()`
+- Use `self.logger` for plugin-specific logging
+- Check cache_manager for cached data
+- Verify display_manager is rendering correctly
+
+**Common Issues:**
+- Import errors: Check Python path and dependencies
+- Config errors: Validate against config_schema.json
+- Display issues: Check display dimensions and coordinate calculations
+- Performance: Monitor CPU/memory usage on Pi
+
+## Plugin Testing
+
+**Unit Tests:**
+- Test plugin class instantiation
+- Test `update()` data fetching logic
+- Test `display()` rendering logic
+- Test `validate_config()` with various configs
+- Mock `display_manager` and `cache_manager` for testing
+
+**Integration Tests:**
+- Test plugin loading via PluginManager
+- Test plugin with actual config
+- Test plugin with emulator display
+- Test plugin with cache_manager
+
+**Hardware Tests:**
+- Test on Raspberry Pi with LED matrix
+- Verify display rendering on actual hardware
+- Test performance under load
+- Test with other plugins enabled
+
+## File Organization
+
+```
+plugins/
+  <plugin-id>/
+    manifest.json          # Plugin metadata
+    manager.py             # Main plugin class
+    config_schema.json     # Config validation schema
+    requirements.txt       # Python dependencies
+    README.md             # Plugin documentation
+    # Plugin-specific files
+    data_manager.py
+    renderer.py
+    etc.
+```
+
+## Git Workflow for Plugins
+
+**Plugin Development:**
+- Plugins are typically separate repositories
+- Use `dev_plugin_setup.sh` to link plugins for development
+- Symlinks are used to connect plugin repos to `plugins/` directory
+- Plugin repos follow naming: `ledmatrix-<plugin-name>`
+
+**Branching:**
+- Develop plugins in feature branches
+- Follow project branching conventions
+- Test plugins before merging to main
+
+**Automatic Version Bumping:**
+- **Automatic Version Management**: Version bumping is handled automatically via the pre-push git hook - no manual version bumping is required for normal development workflows
+- **GitHub as Source of Truth**: Plugin store always fetches latest versions from GitHub (releases/tags/manifest/commit)
+- **Pre-Push Hook**: Automatically bumps patch version and creates git tags when pushing code changes
+  - The hook is self-contained (no external dependencies) and works on any dev machine
+  - Installation: Copy the hook from LEDMatrix repo to your plugin repo:
+    ```bash
+    # From your plugin repository directory
+    cp /path/to/LEDMatrix/scripts/git-hooks/pre-push-plugin-version .git/hooks/pre-push
+    chmod +x .git/hooks/pre-push
+    ```
+  - Or use the installer script from the main LEDMatrix repo (one-time setup)
+  - The hook automatically:
+    1. Bumps the patch version (x.y.Z) in manifest.json when code changes are detected
+    2. Creates a git tag (v{version}) for the new version
+    3. Stages manifest.json for commit
+  - Skip auto-tagging: Set `SKIP_TAG=1` environment variable before pushing
+- **Manual Version Bumping (Edge Cases Only)**: Manual version bumps are only needed in rare circumstances:
+  - CI/CD pipelines that bypass git hooks
+  - Forked repositories without the pre-push hook installed
+  - Major/minor version bumps (hook only handles patch versions)
+  - When skipping auto-tagging but still needing a version bump
+  - For manual bumps, use the standalone script: `scripts/bump_plugin_version.py`
+- **Registry**: The plugin registry (plugins.json) stores only metadata (name, description, repo URL) - no versions
+- **Version Priority**: Plugin store checks versions in this order: GitHub Releases → GitHub Tags → Manifest from branch → Git commit hash
+
+## Resources
+
+- Plugin System Docs: `docs/PLUGIN_ARCHITECTURE_SPEC.md`
+- Plugin Examples: `plugins/hockey-scoreboard/`, `plugins/football-scoreboard/`
+- Base Plugin: `src/plugin_system/base_plugin.py`
+- Plugin Manager: `src/plugin_system/plugin_manager.py`
+- Development Setup: `dev_plugin_setup.sh`
+- Example Config: `dev_plugins.json.example`
+

.github/workflows/release-version-check.yml

@@ -1,40 +0,0 @@
-name: Release version check
-
-# A release tag, the CHANGELOG, and src.__version__ must agree. They have not
-# always: v3.1.0 was tagged while src/__init__.py still said "1.0.0", which
-# silently exempted every device installed from that release from plugin
-# compatibility warnings. See docs/SPORTS_UNIFICATION.md (phase B4).
-on:
-  push:
-    tags: ["v*"]
-  release:
-    types: [published]
-  # Pre-flight: run this against the tag you are about to create.
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: "Tag to check (e.g. v3.2.0)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-
-jobs:
-  version-matches-tag:
-    name: Tag matches src.__version__
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: "3.12"
-
-      # No dependencies: the script reads src/__init__.py and CHANGELOG.md only.
-      - name: Assert the tag, CHANGELOG and src.__version__ agree
-        run: python scripts/check_release_version.py "${TAG}"
-        env:
-          TAG: ${{ inputs.tag || github.ref_name }}

.github/workflows/test.yml

@@ -5,10 +5,6 @@ on:
   push:
     branches: [main]
 
-# Both jobs only check out the repo and run pytest.
-permissions:
-  contents: read
-
 jobs:
   plugin-safety:
     name: Plugin safety harness + unit tests
@@ -35,55 +31,3 @@ jobs:
             test/plugins/test_harness.py \
             test/plugins/test_visual_rendering.py \
             test/plugins/test_plugin_matrix.py
-
-  unit-tests:
-    name: Core unit tests
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
-        with:
-          python-version: "3.12"
-          cache: pip
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt -r requirements-test.txt
-          pip install RGBMatrixEmulator
-
-      # Safety net for the shared sports/scroll/style infrastructure. These
-      # suites existed but were not enrolled in CI, so a refactor of
-      # src/base_classes or src/common could regress them silently. Enrolled
-      # explicitly (not `pytest test/`) so known hardware-only suites don't
-      # break CI; grow this list as more suites are made headless.
-      - name: Run core unit suites
-        run: |
-          pytest --no-cov \
-            test/test_skin_system.py \
-            test/test_font_manager.py \
-            test/test_data_sources.py \
-            test/test_api_extractors.py \
-            test/test_scroll_helper.py \
-            test/test_scroll_helper_continuous.py \
-            test/test_adaptive_layout.py \
-            test/test_loader_compat_warning.py \
-            test/test_sports_base_characterization.py \
-            test/test_element_style.py \
-            test/test_sports_core_promotions.py \
-            test/test_sports_modes_promotions.py \
-            test/test_sports_capabilities.py \
-            test/test_sports_scroll.py \
-            test/test_version_consistency.py \
-            test/test_plugin_compatibility_gate.py \
-            test/test_install_preserves_existing.py \
-            test/test_core_owned_config_keys.py \
-            test/test_async_plugin_updates.py \
-            test/test_plugin_update_reservation.py \
-            test/test_template_targets.py \
-            test/test_widget_scripts.py \
-            test/test_doc_links.py \
-            test/web_interface/test_cache.py

CHANGELOG.md

@@ -1,176 +0,0 @@
-# Changelog
-
-Notable changes to the LEDMatrix core. The version below is the value of
-`src.__version__`, which the plugin loader reports to compatibility checks and
-which plugin manifests reference via `ledmatrix_min_version`.
-
-**Why this file exists:** the plugin monorepo bundles fallback copies of several
-core modules (see `docs/plugin-development/08-shared-sports-code.md` in
-[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)). A plugin
-may delete its bundled copy only when its manifest floors on the first core
-release that ships the module — which requires module additions to be recorded
-here, against a version number. When you add a module plugins will import via
-`src.*`, note it in the Unreleased section and bump `src/__init__.py` in the
-release that ships it.
-
-**Use `ledmatrix_min_version` in manifests, not `ledmatrix_min`.** The loader
-accepts both, but the store flags the old spelling as deprecated
-(`store_manager.py`) and only the new one is in `schema/manifest_schema.json`.
-
-## 3.2.0
-
-**The first release shipping the unified sports library.** This is the version
-a sports plugin floors `ledmatrix_min_version` at before deleting its bundled
-copy of `sports.py`, `scroll_display.py`, `data_sources.py` or
-`base_odds_manager.py` — the sunset rule in
-`docs/plugin-development/08-shared-sports-code.md` keys on exactly this number.
-
-Adoption is deliberately staged: the modules below ship here, plugins adopt them
-behind guarded imports, and only then do the bundled copies go away. Nothing in
-this release changes what an existing plugin loads.
-
-**This is also the first release that *enforces* `ledmatrix_min_version`.**
-Before it, the floor was advisory — the loader logged a warning and continued,
-and the plugin store never compared the core version at all, so an update could
-deliver a plugin that could not run. From 3.2.0 the store refuses such an
-install. That matters for the sunset rule: a plugin may only delete its bundled
-fallback once the cores in the field actually enforce the floor, which means
-waiting for 3.2.0 to be widely installed rather than merely released. See
-`docs/SPORTS_UNIFICATION.md`, phase B6.
-
-One deliberate exception: a core reporting a version below `2.0.0` is treated as
-*unknown* rather than old and is never blocked. The v3.1.0 release ships
-`__version__ = "1.0.0"` (the tag was cut before the string was bumped), and
-nearly every published manifest floors at `2.0.0` — so blocking on that number
-would lock those users out of the plugin store entirely.
-
-### Added
-- `src/element_style.py` — per-element style resolver backing the
-  `x-style-elements` config-schema extension. Already consumed (behind guarded
-  imports with classic fallbacks) by the `of-the-day`, `ledmatrix-music`, and
-  `football-scoreboard` plugins.
-- Core unit-test CI job enrolling the previously unenrolled suites (skin
-  system, data sources, API extractors, scroll helper, adaptive layout, loader
-  compatibility warning) plus new characterization tests for
-  `src/base_classes/sports.py` ahead of the shared sports-code unification.
-- `src/base_classes/sports/` — `sports.py` is now a package (`core.py` +
-  `modes.py`). The import path is unchanged: `from src.base_classes.sports
-  import SportsCore` still works.
-- Nine methods promoted onto the sports base classes from the plugins'
-  bundled copies, plus the override points `_favorite_key`,
-  `_config_schema_path` and `_font_root` and the class attributes
-  `FINAL_PERIOD` / `CLOCK_COUNTS_DOWN`. See `docs/SPORTS_UNIFICATION.md`.
-  A plugin may start calling these once its manifest floors
-  `ledmatrix_min_version` at the release that ships them.
-
-- `src/base_classes/sports/capabilities/` — opt-in capabilities for the sports
-  scoreboards, composed by inheritance rather than gated by config branches
-  inside the base classes:
-  - `CelebrationMixin` — the score/win takeover, merging the goal and score
-    dialects behind the `score_phrase()` / `win_phrase()` hooks, the
-    `COALESCE_SCORING_SEQUENCE` class attribute and the `_favorite_key` seam.
-    Reads both the `celebrate_opponent_goals` and `celebrate_opponent_scores`
-    config spellings. Sports that do not mix it in have none of this code in
-    their MRO.
-  - `RotationStrategy` + a name registry (`swrr`, `weighted`, `simple`,
-    plus `register_rotation_strategy` for plugin-supplied orderings). Each
-    built-in is verified against a verbatim transcription of the plugin
-    implementation it replaces. An unknown name degrades to `simple`.
-
-- `src/common/sports_scroll.py` — `SportsScrollDisplay` and
-  `SportsScrollDisplayManager`, the shared scroll **orchestration** layer for
-  the sports scoreboards, plus native support for
-  `global_config['target_fps']` (the bundled plugin copies hardcode ~100 FPS
-  via `scroll_delay` and never consult the global target). Content building
-  (`prepare_scroll_content`, `_load_separator_icons`) is per-sport and stays an
-  override point — see `docs/SPORTS_UNIFICATION.md` for where the line falls
-  and why.
-
-- `src/plugin_system/compatibility.py` — the single place that answers "can this
-  plugin run on this core?", shared by the loader (advisory, at load time) and
-  the store (blocking, at install/update time) so the two cannot drift. Reads
-  every spelling published manifests use, including the deprecated
-  `versions[].ledmatrix_min`. It does **not** yet evaluate `compatible_versions`,
-  which is the schema-required field and can express upper bounds; closing that
-  is tracked in `docs/SPORTS_UNIFICATION.md` before B6.
-- `scripts/check_release_version.py` and a `Release version check` workflow —
-  assert that a tag, the newest CHANGELOG heading and `src.__version__` agree,
-  on pushed `v*` tags and published releases. Runnable via `workflow_dispatch`
-  to check a tag *before* creating it. Added because `v3.1.0` was tagged six
-  weeks before `src/__init__.py` was bumped to match, which is why devices
-  installed from that release report `1.0.0`.
-
-### Changed
-- `src/__init__.py` bumped to **3.2.0** — the number the sunset rule keys on.
-- **The plugin store refuses an incompatible install.**
-  `StoreManager.install_plugin` now checks the downloaded manifest's declared
-  floor against `src.__version__` and refuses when the plugin needs a newer
-  core. The check sits in `install_plugin` because `_reinstall_with_rollback`
-  calls it, so a refused *update* restores the version the user already had.
-  Refusal requires evidence: an undeclared floor, an unparseable version on
-  either side, or an untrustworthy core version all allow the install.
-- **A failed install no longer destroys the plugin it replaced.**
-  `install_plugin` previously deleted the existing plugin directory before
-  downloading, so any later failure — a dropped connection, a malformed
-  manifest, or the new compatibility refusal — left the user with nothing. The
-  existing copy is now set aside and restored if the install fails, matching
-  the protection `_reinstall_with_rollback` already gave the update path.
-- `web_interface.__version__` re-exports `src.__version__` instead of carrying
-  its own hardcoded `"3.0.0"`, which had drifted two majors from the core.
-- **Live games are no longer dropped when the feed omits a game clock.**
-  `SportsLive._is_game_really_over` previously (in the baseball and UFC
-  plugin lineages) coerced a missing or non-string clock to the literal
-  `"0:00"` and then treated the game as finished once `period >= 4`. Baseball
-  has no game clock and `period` is the inning, so live MLB games disappeared
-  from the scoreboard from the 5th inning onward; UFC was affected the same
-  way. The clock check is now skipped when the clock is unusable, and the
-  period threshold is the per-sport `FINAL_PERIOD` (hockey ends in P3).
-  Sports whose clocks count up — soccer, AFL, NRL — set
-  `CLOCK_COUNTS_DOWN = False` and never run the check at all, since `0:00`
-  there means kickoff rather than expiry.
-
-### Fixed
-- **Plugin updates could hang the web request thread.** The per-plugin reinstall
-  locks were non-reentrant, and `_reinstall_with_rollback` holds one across its
-  call to `install_plugin` — which now takes the same lock to protect the
-  set-aside/restore above. That nesting deadlocked
-  `update_plugin → _reinstall_with_rollback → install_plugin`, the standard
-  path for every monorepo plugin update. The locks are now `RLock`s.
-- `FontManager` resolves `assets/fonts` against the core install root instead
-  of the process working directory, so font loading works when the process
-  starts elsewhere (e.g. the plugin safety harness on CI).
-- Hockey events whose competitors carry no `statistics` array are no longer
-  discarded. The extractor read `competitor["statistics"]` unguarded, so a
-  `KeyError` inside the generator dropped the entire event despite valid
-  scores and status; shot counts now fall back to `0`.
-- Live baseball events that populate status only at the competition level are
-  no longer discarded. The extractor read the event top-level
-  `game_event["status"]` for the inning; real ESPN events duplicate it, but
-  MiLB events synthesized from the MLB Stats API do not, so the lookup raised
-  a bare `KeyError`. It now reads the already-validated competition-level
-  status.
-- `SportsLive._is_game_really_over` no longer crashes the live-update pass when
-  a feed sends an explicit null `period`. `None >= FINAL_PERIOD` raised
-  `TypeError`, and the only caller (`_detect_stale_games`) has no `try/except`
-  — the same failure shape as the already-fixed null `period_text`.
-- An expired clock spelled `"00:00"` now ends the game. The check compared the
-  colon-stripped clock against a hand-listed set of literals, which `"0000"` is
-  not a member of, so a finished game with a two-digit-minute clock stayed on
-  the scoreboard indefinitely. The comparison is now numeric.
-- `SportsCore._load_fonts` resolves `assets/fonts` through the `_font_root()`
-  seam instead of the process working directory. Started outside the install
-  root, every scoreboard font silently degraded to PIL's default bitmap face.
-- `SportsCore._should_log` no longer raises `AttributeError` on the first
-  warning of a run; `_last_warning_time` is initialized in `__init__` rather
-  than lazily by an unrelated method.
-- `SportsCore._resolve_project_path` resolved relative logo directories
-  against `<root>/src` instead of the repo root after `sports.py` became a
-  package — the class bodies moved byte-identically but `__file__` gained a
-  directory. Both it and `_font_root` now derive from one `_INSTALL_ROOT`
-  constant.
-
-## 3.1.0
-
-Baseline for this changelog. Highlights already shipped at this version:
-skin system for sports scoreboards (#419), Vegas continuous-scroll overhaul
-(#423), plugin update surfacing (#421).

CLAUDE.md

@@ -6,16 +6,12 @@
 - `config/config.json` — User plugin configuration (persists across plugin reinstalls)
 - `plugin-repos/` — **Default** plugin install directory used by the
   Plugin Store, set by `plugin_system.plugins_directory` in
-  `config.json` (default per `config/config.template.json:167`).
+  `config.json` (default per `config/config.template.json:130`).
   Not gitignored.
 - `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`).
   Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin
-  loader does NOT fall back to it — `PluginManager.discover_plugins()`
-  (`src/plugin_system/plugin_manager.py`) scans only the configured
-  directory. Fallbacks exist in two narrower places: store operations
-  (`StoreManager._find_plugin_path()` in `store_manager.py`) and schema
-  lookup (`SchemaManager.get_schema_path()` in `schema_manager.py`,
-  which probes `plugins/` *before* `plugin-repos/`).
+  loader falls back to it when something isn't found in `plugin-repos/`
+  (`src/plugin_system/schema_manager.py:77`).
 
 ## Plugin System
 - Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py`
@@ -24,16 +20,6 @@
 - Plugin instantiation args: `plugin_id, config, display_manager, cache_manager, plugin_manager`
 - Config schemas use JSON Schema Draft-7
 - Display dimensions: always read dynamically from `self.display_manager.matrix.width/height`
-- Secrets: namespaced by plugin id in `config/config_secrets.json`, declared
-  via `"x-secret": true` in the plugin's config schema, and deep-merged into
-  the plugin's config dict at load time — plugins read them with plain
-  `config.get(...)`, never a separate accessor
-
-## Dev Workflow
-- Link a plugin for development: `./scripts/dev/dev_plugin_setup.sh link-github <name>` (or `link <name> <path>`); symlinks land in `plugins/` — set `plugin_system.plugins_directory` to `plugins` so discovery picks them up
-- Browser preview without the display loop: `python3 scripts/dev_server.py` → http://localhost:5001
-- Full display in emulator mode: `python3 run.py -e` (or `EMULATOR=true python3 run.py`)
-- Validate one plugin headlessly: `python3 scripts/check_plugin.py --plugin <id>`
 
 ## Plugin Store Architecture
 - Official plugins live in the `ledmatrix-plugins` monorepo (not individual repos)
@@ -47,7 +33,7 @@
 
 ## Skin System (visual overlays for sports scoreboards)
 - Skins live in `skins/<skin-id>/` (skin.json + skin.py), NOT in plugin dirs — plugin reinstall deletes plugin dirs
-- Core: `src/skin_system/` (ScoreboardSkin, SkinContext, runtime); hook: `SportsCore._render_game()` in `src/base_classes/sports/core.py`
+- Core: `src/skin_system/` (ScoreboardSkin, SkinContext, runtime); hook: `SportsCore._render_game()` in `src/base_classes/sports.py`
 - Skins render onto `ctx.canvas` only; fallback to built-in renderer on `False`/exception (3 strikes disables for session)
 - View-model guaranteed keys are frozen (see `test/test_skin_system.py::TestViewModelContract`) — renaming keys in `_extract_game_details_common` or sport extractors breaks published skins
 - Validate skins headlessly: `python scripts/validate_skin.py --skin <id>`; docs: `docs/SKIN_SYSTEM.md`, `docs/CREATING_SKINS.md`
@@ -56,7 +42,4 @@
 ## Common Pitfalls
 - paho-mqtt 2.x needs `callback_api_version=mqtt.CallbackAPIVersion.VERSION1` for v1 compat
 - BasePlugin uses `get_logger()` from `src.logging_config`, not standard `logging.getLogger()`
-- `DisplayManager` has no `draw_image()` — paste onto the PIL image directly:
-  `self.display_manager.image.paste(img, (x, y))` then `update_display()`
-  (use a mask for transparency: `image.paste(rgba, (x, y), rgba)`)
 - When modifying a plugin in the monorepo, you MUST bump `version` in its `manifest.json` and run `python update_registry.py` — otherwise users won't receive the update

CONTRIBUTING.md

@@ -40,7 +40,7 @@ improvements, and code changes.
 ## Running the tests
 
 ```bash
-pip install -r requirements.txt -r requirements-test.txt
+pip install -r requirements.txt
 pytest
 ```
 
@@ -57,12 +57,9 @@ integration tests.
    `docs/<short-description>`.
 3. **Keep PRs focused.** One conceptual change per PR. If you find
    adjacent bugs while working, fix them in a separate PR.
-4. **Follow the existing code style.** The pre-commit hooks run
-   `flake8` (E9, F63, F7, F82 plus bugbear `B` checks), `mypy` on
-   `src/`, `bandit`, and `gitleaks` — install them with
-   `pre-commit install` so they run on every commit; HTML/JS in
-   `web_interface/` follows the patterns already in `templates/v3/`
-   and `static/v3/`.
+4. **Follow the existing code style.** Python code uses standard
+   `black`/`ruff` conventions; HTML/JS in `web_interface/` follows the
+   patterns already in `templates/v3/` and `static/v3/`.
 5. **Update documentation** alongside code changes. If you add a
    config key, document it in the relevant `*.md` file (or, for
    plugins, in `config_schema.json` so the form is auto-generated).

README.md

@@ -50,15 +50,7 @@ I'm trying to be open to constructive criticism and support, as long as it's a r
 
 <details>
 <summary>Core Features</summary>
-LEDMatrix is a plugin platform: the displays below are plugins installed
-from the built-in Plugin Store (web interface → Plugins), where each can be
-individually enabled, ordered, and configured — display durations, teams,
-stocks, weather, timezones, and more. The core repo ships with just two
-bundled plugins (`starlark-apps` and `web-ui-info`); the official plugins
-live in the [ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)
-monorepo and install with one click, and third-party plugins can be
-installed from their own GitHub repositories. Displays available in the
-store include:
+The following plugins are available inside of the LEDMatrix project. These modular, rotating Displays that can be individually enabled or disabled per the user's needs with some configuration around display durations, teams, stocks, weather, timezones, and more. Displays include:
 
 ### Time and Weather
 - Real-time clock display (2x 64x32 Displays 4mm Pixel Pitch)
@@ -149,7 +141,6 @@ The system supports live, recent, and upcoming game information for multiple spo
     sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh
     ```
   - Pi 5 config: leave `rp1_rio` at `0` (PIO mode, default) and set `gpio_slowdown` to `1` or `2`.
-  - **1GB models (Pi 3B / 3B+) and other low-memory boards**: supported, but the `rpi-rgb-led-matrix` C++ build needs more memory than the Pi has. The installer detects this automatically, compiles with fewer parallel jobs, and adds a temporary swapfile for the build which it removes afterwards. Expect that step to take 15-25 minutes instead of 2-5, and leave at least **3GB free** on the SD card. If you manage swap yourself, opt out with `--skip-swap`. To pin the compiler down further, use `--build-jobs 1`.
 
 
 ### RGB Matrix Bonnet / HAT
@@ -323,12 +314,12 @@ curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/
 ```
 
 This one-shot installer will automatically:
-- Check system prerequisites (network, disk space, memory, sudo access)
+- Check system prerequisites (network, disk space, sudo access)
 - Install required system packages (git, python3, build tools, etc.)
 - Clone or update the LEDMatrix repository
 - Run the complete first-time installation script
 
-The installation process typically takes 10-30 minutes depending on your internet connection and Pi model. Pi 3B/3B+ and other 1GB boards land at the top of that range, because the C++ library is compiled serially to stay within available memory. All errors are reported explicitly with actionable fixes.
+The installation process typically takes 10-30 minutes depending on your internet connection and Pi model. All errors are reported explicitly with actionable fixes.
 
 **Note:** The script is safe to run multiple times and will handle existing installations gracefully.
 
@@ -380,10 +371,6 @@ This single script installs services, dependencies, configures permissions and s
 
 ### Initial Setup
 
-For a complete list of every key in `config.json` and
-`config_secrets.json`, see
-[docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md).
-
 For most settings I recommend using the web interface:
 Edit the project via the web interface at http://[IP ADDRESS or HOSTNAME]:5000 or http://ledpi:5000 .
 
@@ -429,7 +416,7 @@ I recommend using the web-ui "Quick Actions" to control the Display.
 ## Plugins
 
 <details>
-LEDMatrix uses a plugin-based architecture where all display functionality is implemented as plugins. All managers that were previously built into the core system are now available as plugins through the Plugin Store.
+LEDMatrix uses a plugin-based architecture where all display functionality (except the core calendar) is implemented as plugins. All managers that were previously built into the core system are now available as plugins through the Plugin Store.
 
 ### Plugin Store
 See the [Plugin Store documentation](https://github.com/ChuckBuilds/ledmatrix-plugins) for detailed installation instructions.
@@ -622,7 +609,12 @@ These settings control runtime behavior and GPIO timing:
 
 ### Display Durations (`display.display_durations`)
 
-Controls how long each installed plugin stays visible in seconds before switching to the next one, keyed by plugin id.
+Controls how long each display module stays visible in seconds before switching to the next one.
+
+- **`calendar`** (integer, default: 30)
+  - Duration in seconds for the calendar display
+  - Increase for more time to read dates/events
+  - Decrease to cycle through other displays faster
 
 - **Plugin-specific durations**
   - Each plugin can have its own duration setting

assets/README.md

@@ -1,22 +0,0 @@
-# assets/
-
-Static assets bundled with LEDMatrix. **Do not delete these directories** —
-several look unused from core code alone but are resolved at runtime by
-installed store plugins.
-
-| Directory | Used by |
-|---|---|
-| `fonts/` | Core (`FontManager`, `DisplayManager`) and most plugins |
-| `sports/` | Core logo tooling (`src/logo_downloader.py`) and the sports scoreboard plugins; team logos are downloaded here on demand |
-| `stocks/` | `ledmatrix-stocks` plugin (`crypto_icons/`, `ticker_icons/`) |
-| `weather/` | `ledmatrix-weather` plugin (weather icons) |
-| `news_logos/` | `news` plugin |
-| `broadcast_logos/` | `news` and `odds-ticker` plugins |
-| `static_images/` | Legacy examples referenced in the `static-image` plugin's docs; the plugin itself stores uploads under `assets/plugins/<plugin-id>/uploads/` |
-| `plugins/` | Per-plugin uploaded files (`assets/plugins/<plugin-id>/uploads/`), served by the web interface |
-
-Plugins resolve these paths relative to the LEDMatrix install directory, so
-the directories are part of the de-facto plugin API even where no file in
-this repo references them. New plugins should bundle their own assets or
-use the per-plugin upload directory instead of adding top-level
-directories here.

config/config.template.json

@@ -88,7 +88,6 @@
         }
     },
     "timezone": "America/New_York",
-    "target_fps": 100,
     "location": {
         "city": "Tampa",
         "state": "Florida",
@@ -110,11 +109,7 @@
             "inverse_colors": false,
             "show_refresh_rate": false,
             "led_rgb_sequence": "RGB",
-            "limit_refresh_rate_hz": 100,
-            "pixel_mapper_config": "",
-            "row_address_type": 0,
-            "multiplexing": 0,
-            "panel_type": ""
+            "limit_refresh_rate_hz": 100
         },
         "runtime": {
             "gpio_slowdown": 3,
@@ -135,27 +130,7 @@
             "plugin_order": [],
             "excluded_plugins": [],
             "target_fps": 125,
-            "buffer_ahead": 2,
-            "intra_plugin_gap": 8,
-            "render_width_pct": 100,
-            "min_content_separation": 24,
-            "min_cut_gap": 6,
-            "continuous_scroll": true,
-            "smooth_scroll": true,
-            "extend_threshold_screens": 2.0,
-            "auto_trim": true,
-            "trim_threshold": 10,
-            "content_padding": 8,
-            "min_plugin_width": 8,
-            "lead_in_width": 0,
-            "plugins_per_cycle": 6,
-            "max_plugin_width_ratio": 3.0,
-            "overflow_mode": "rotate",
-            "dynamic_duration_enabled": true,
-            "min_cycle_duration": 60,
-            "max_cycle_duration": 240,
-            "frame_based_scrolling": true,
-            "scroll_delay": 0.02
+            "buffer_ahead": 2
         }
     },
     "sync": {
@@ -166,8 +141,7 @@
     "plugin_system": {
         "plugins_directory": "plugin-repos",
         "auto_discover": true,
-        "auto_load_enabled": true,
-        "development_mode": false
+        "auto_load_enabled": true
     },
     "web-ui-info": {
         "enabled": true,

config/config_secrets.template.json

@@ -1,4 +1,8 @@
 {
+    "youtube": {
+        "api_key": "YOUR_YOUTUBE_API_KEY",
+        "channel_id": "YOUR_YOUTUBE_CHANNEL_ID"
+    },
     "github": {
         "api_token": "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
     }

docs/ADVANCED_FEATURES.md

@@ -47,11 +47,6 @@ Enable Vegas mode in `config/config.json`:
 }
 ```
 
-Vegas mode can also be configured entirely from the web UI — the
-**Display** tab has a Vegas Scroll Mode section (enable toggle, scroll
-speed, separator width, dynamic duration, and more), so hand-editing
-JSON is optional.
-
 **Configuration Options:**
 
 | Setting | Default | Description |
@@ -62,11 +57,7 @@ JSON is optional.
 | `plugin_order` | `[]` | Plugin display order (empty = auto) |
 | `excluded_plugins` | `[]` | Plugins to exclude from Vegas mode |
 | `target_fps` | `125` | Target frame rate |
-| `buffer_ahead` | `2` | Number of plugins buffered ahead |
-
-This table is a subset — `display.vegas_scroll` supports 26 keys in
-total. See the full list in
-[CONFIG_REFERENCE.md](CONFIG_REFERENCE.md#displayvegas_scroll--continuous-scroll-mode).
+| `buffer_ahead` | `2` | Number of panels to render ahead |
 
 ### Per-Plugin Configuration
 
@@ -88,13 +79,9 @@ Override Vegas behavior for specific plugins:
 | Setting | Values | Description |
 |---------|--------|-------------|
 | `vegas_mode` | `scroll`, `fixed`, `static` | Display mode for this plugin |
-| `vegas_panel_count` | any positive integer | Width in panels (1 panel = display width) |
+| `vegas_panel_count` | `1-10` | Width in panels (1 panel = display width) |
 | `display_duration` | seconds | Pause duration for STATIC mode |
 
-Plugins may also set `vegas_overflow` and `vegas_max_width_screens` in
-their config section to control how oversized content is handled (see
-`PluginManager` in `src/plugin_system/plugin_manager.py`).
-
 ### Plugin Integration (Developer Guide)
 
 **1. Implement Content Method:**
@@ -464,7 +451,7 @@ 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` (`web_interface/app.py:144`).
 
 #### Start On-Demand Display
 
@@ -531,15 +518,13 @@ curl http://localhost:5000/api/v3/display/on-demand/status
 
 > 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
-> manager under the `display_on_demand_request` key, which
-> `DisplayController._poll_on_demand_requests()`
-> (`src/display_controller.py`) picks up. A separate
+> above (or the web UI buttons), which write a request into the cache
+> manager under the `display_on_demand_request` key
+> (`web_interface/blueprints/api_v3.py:1622,1687`) that the controller
+> polls at `src/display_controller.py:921`. A separate
 > `display_on_demand_config` key is used by the controller itself
-> during activation (`_activate_on_demand()`) to track what's
-> currently running, and is cleared by `_clear_on_demand()`.
+> during activation to track what's currently running (written at
+> `display_controller.py:1195`, cleared at `:1221`).
 
 ### Duration Modes
 
@@ -661,13 +646,13 @@ keys helps troubleshoot stuck states.
 **When Set:** Every display loop iteration
 **Auto-Cleared:** Never (continuously updated)
 
-**4. display_on_demand_processed_id** (TTL: 1 hour)
+**4. display_on_demand_processed_id** (TTL: 5 minutes)
 ```
 "uuid-string-of-last-processed-request"
 ```
 **Purpose:** Prevents duplicate request processing
 **When Set:** After processing request
-**Auto-Cleared:** After 1 hour TTL
+**Auto-Cleared:** After 5 minutes TTL
 
 ### When Manual Clearing is Needed
 
@@ -700,9 +685,9 @@ keys helps troubleshoot stuck states.
 The cache is stored as JSON files under one of:
 
 - `/var/cache/ledmatrix/` (preferred when the service has permission)
-- `~/.ledmatrix_cache/`
+- `~/.cache/ledmatrix/`
 - `/opt/ledmatrix/cache/`
-- `$TMPDIR/ledmatrix_cache/` (fallback)
+- `/tmp/ledmatrix-cache/` (fallback)
 
 ```bash
 # Find the cache dir actually in use
@@ -726,9 +711,8 @@ cache.clear_cache('display_on_demand_request')
 cache.clear_cache('display_on_demand_processed_id')
 ```
 
-> `CacheManager` also has a `delete(key)` method — a thin wrapper over
-> `clear_cache(key)` — so `cache.delete('display_on_demand_config')`
-> works equally well.
+> The actual public method is `clear_cache(key=None)` — there is no
+> `delete()` method on `CacheManager`.
 
 ### Cache Impact on Running Service
 
@@ -746,7 +730,7 @@ The display controller automatically handles cleanup:
 - **Config key**: Cleared when on-demand stops
 - **State key**: Updated every display loop iteration
 - **Request key**: Expires after 1 hour TTL (or after processing)
-- **Processed ID**: Expires after 1 hour TTL
+- **Processed ID**: Expires after 5 minutes TTL
 
 ---
 
@@ -837,6 +821,9 @@ same shape as the example above.
 ### Testing
 
 ```bash
+# Run background service test
+python test_background_service.py
+
 # Check logs for background operations
 sudo journalctl -u ledmatrix -f | grep "background"
 ```
@@ -845,10 +832,9 @@ sudo journalctl -u ledmatrix -f | grep "background"
 
 **View Statistics:**
 ```python
-from src.background_data_service import get_background_service
-from src.cache_manager import CacheManager
+from src.background_data_service import BackgroundDataService
 
-service = get_background_service(CacheManager())
+service = BackgroundDataService()
 stats = service.get_statistics()
 print(f"Active tasks: {stats['active_tasks']}")
 print(f"Completed: {stats['completed']}")
@@ -889,7 +875,6 @@ from src.common.permission_utils import (
     ensure_file_permissions,
     get_config_file_mode,
     get_assets_file_mode,
-    get_assets_dir_mode,
     get_plugin_file_mode,
     get_cache_dir_mode
 )
@@ -898,10 +883,7 @@ from src.common.permission_utils import (
 ensure_directory_permissions(Path("assets/sports"), get_assets_dir_mode())
 
 # Set file permissions after writing
-# (get_config_file_mode requires the file path — secrets files get a
-# stricter mode than the main config)
-config_path = Path("config/config.json")
-ensure_file_permissions(config_path, get_config_file_mode(config_path))
+ensure_file_permissions(Path("config/config.json"), get_config_file_mode())
 ```
 
 ### When to Use Utilities
@@ -956,7 +938,7 @@ from src.common.permission_utils import ensure_file_permissions, get_config_file
 config_path = Path("config/config.json")
 with open(config_path, 'w') as f:
     json.dump(data, f)
-ensure_file_permissions(config_path, get_config_file_mode(config_path))
+ensure_file_permissions(config_path, get_config_file_mode())
 ```
 
 **Pattern 3: Downloading Logo**
@@ -1002,11 +984,8 @@ These core utilities **already handle permissions** - you don't need to call per
 If you encounter permission issues:
 
 ```bash
-# Targeted permission fixes (see scripts/fix_perms/README.md)
-sudo ./scripts/fix_perms/fix_assets_permissions.sh   # assets/ tree (logos, fonts)
-sudo ./scripts/fix_perms/fix_cache_permissions.sh    # all cache directories
-sudo ./scripts/fix_perms/fix_plugin_permissions.sh   # plugin directories
-sudo ./scripts/fix_perms/fix_web_permissions.sh      # web interface files
+# Fix all permissions at once
+sudo ./scripts/fix_permissions.sh
 
 # Fix specific directory
 sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix/config
@@ -1038,7 +1017,7 @@ stat -c "%a %n" config/config.json
 
 ## Related Documentation
 
-- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) - Creating plugins with Vegas/on-demand support
+- [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) - Creating plugins with Vegas/on-demand support
 - [WEB_INTERFACE_GUIDE.md](WEB_INTERFACE_GUIDE.md) - Using on-demand controls in web UI
 - [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) - Complete API documentation
 - [DEVELOPMENT.md](DEVELOPMENT.md) - Development environment and testing

docs/CONFIG_REFERENCE.md

@@ -1,172 +0,0 @@
-# Configuration Reference
-
-Every key in `config/config.json`, what it does, its default, and where the
-code reads it. The file is created from `config/config.template.json` on
-first run, and `ConfigManager._migrate_config()` merges any template keys
-added by later releases into your existing config (your values are never
-overwritten). Secrets live in `config/config_secrets.json` and are merged
-into the config at load time.
-
-Most settings are editable from the web interface; this page documents the
-underlying keys for people editing `config.json` directly or writing
-tooling against it.
-
-## Top level
-
-| Key | Type / default | Meaning | Read by |
-|---|---|---|---|
-| `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` |
-| `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
-| `target_fps` | int, `100` | Frame-rate ceiling for plugin rendering | `src/plugin_system/base_plugin.py`, `src/common/sports_scroll.py` |
-| `location` | object | `city` / `state` / `country`, offered to plugins that need a location (weather, etc.) | plugins via merged config |
-
-## `schedule` — display on/off hours
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `enabled` | bool, `false` | Master switch for scheduled display on/off |
-| `mode` | `"global"` or `"per-day"`, template uses `"per-day"` | Whether one time range applies to all days or each day has its own |
-| `start_time` / `end_time` | `"HH:MM"`, `07:00`–`23:00` | Global-mode on/off times |
-| `days.<weekday>.{enabled,start_time,end_time}` | per-day objects | Per-day-mode overrides |
-
-Read by `DisplayController` (`src/display_controller.py`, `_check_schedule`
-around line 603). Managed in the web UI under Schedule.
-
-## `dim_schedule` — scheduled brightness dimming
-
-Same shape as `schedule`, plus:
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `dim_brightness` | int, `30` | Brightness percentage applied while the dim window is active |
-
-Read by `DisplayController` (`src/display_controller.py` around line 770;
-saved via `POST /api/v3/config/dim-schedule`). The display returns to
-`display.hardware.brightness` outside the window.
-
-## `display.hardware` — matrix panel hardware
-
-All keys map to the corresponding `rpi-rgb-led-matrix` options and are read
-in `DisplayManager` (`src/display_manager.py`, ~lines 270–295).
-
-| Key | Type / default |
-|---|---|
-| `rows` / `cols` | int, `32` / `64` |
-| `chain_length` | int, `2` |
-| `parallel` | int, `1` |
-| `brightness` | int, `90` |
-| `hardware_mapping` | string, `"adafruit-hat"` (code default `"adafruit-hat-pwm"`) |
-| `scan_mode` | int, `0` |
-| `pwm_bits` | int, `9` (code default 10) |
-| `pwm_dither_bits` | int, `1` |
-| `pwm_lsb_nanoseconds` | int, `130` (code default 150) |
-| `disable_hardware_pulsing` | bool, `false` |
-| `inverse_colors` | bool, `false` |
-| `show_refresh_rate` | bool, `false` |
-| `led_rgb_sequence` | string, `"RGB"` |
-| `limit_refresh_rate_hz` | int, `100` (code default 90) |
-| `pixel_mapper_config` | string, `""` — e.g. `"U-mapper"` / `"Rotate:90"` |
-| `row_address_type` | int, `0` — non-standard panel row addressing |
-| `multiplexing` | int, `0` — panel multiplexing scheme |
-| `panel_type` | string, `""` — set to `"FM6126A"` or `"FM6127"` for panels needing init |
-
-Where "code default" differs from the template value, the code default only
-applies if the key is missing entirely from your config.
-
-## `display.runtime`
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `gpio_slowdown` | int, `3` | GPIO timing slowdown for faster Pis |
-| `rp1_rio` | int, `0` | RP1 RIO mode on Pi 5 (applied only if the installed matrix library supports it) |
-
-## `display.double_sided`
-
-Drives `_LogicalMatrix` in `src/display_manager.py` — renders the same
-logical image to multiple chained physical panels.
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `enabled` | bool, `false` | Mirror output across panel copies |
-| `copies` | int, `2` | Number of physical copies in the chain |
-| `axis` | `"horizontal"`, default | Axis along which panels are chained |
-
-## `display` — other keys
-
-| Key | Type / default | Meaning | Read by |
-|---|---|---|---|
-| `display_durations` | object, `{}` | Per-plugin display duration in seconds, keyed by plugin id (e.g. `"clock": 15`) | `src/display_controller.py:1030` |
-| `plugin_rotation_order` | array, `[]` | Explicit rotation order of plugin ids; empty = all enabled plugins in discovery order | `src/display_controller.py:2894` |
-| `use_short_date_format` | bool, `true` | Compact date rendering in sports scoreboards | `src/base_classes/sports/core.py` |
-| `dynamic_duration.max_duration_seconds` | int, optional | Cap for plugins that request dynamic display time | `src/display_controller.py:405` |
-
-## `display.vegas_scroll` — continuous scroll mode
-
-Read by `src/vegas_mode/config.py` (`VegasScrollConfig.from_config`). See
-[ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for behavior details.
-
-| Key | Type / default |
-|---|---|
-| `enabled` | bool, `false` |
-| `scroll_speed` | int, `50` (px/s) |
-| `separator_width` | int, `32` |
-| `plugin_order` | array, `[]` |
-| `excluded_plugins` | array, `[]` |
-| `target_fps` | int, `125` |
-| `buffer_ahead` | int, `2` |
-| `intra_plugin_gap` | int, `8` |
-| `render_width_pct` | int, `100` |
-| `min_content_separation` | int, `24` |
-| `min_cut_gap` | int, `6` |
-| `continuous_scroll` | bool, `true` |
-| `smooth_scroll` | bool, `true` |
-| `extend_threshold_screens` | float, `2.0` |
-| `auto_trim` | bool, `true` |
-| `trim_threshold` | int, `10` |
-| `content_padding` | int, `8` |
-| `min_plugin_width` | int, `8` |
-| `lead_in_width` | int, `0` |
-| `plugins_per_cycle` | int, `6` |
-| `max_plugin_width_ratio` | float, `3.0` |
-| `overflow_mode` | string, `"rotate"` |
-| `dynamic_duration_enabled` | bool, `true` |
-| `min_cycle_duration` | int, `60` |
-| `max_cycle_duration` | int, `240` |
-| `frame_based_scrolling` | bool, `true` — frame-count-based scroll stepping |
-| `scroll_delay` | float, `0.02` — seconds between scroll updates (~50 FPS) |
-
-## `sync` — multi-display synchronization
-
-Read by `src/common/sync_manager.py` and `src/display_controller.py`.
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `role` | `"standalone"` (default), `"leader"`, or `"follower"` | This device's role in a synced pair |
-| `port` | int, `5765` | TCP port used for sync traffic |
-| `follower_position` | `"left"` (default) or `"right"` | Which half of the combined image this follower renders (`src/display_controller.py:522`) |
-
-## `plugin_system`
-
-Read by the plugin loader/manager (`src/plugin_system/`).
-
-| Key | Type / default | Meaning |
-|---|---|---|
-| `plugins_directory` | string, `"plugin-repos"` | Where the Plugin Store installs plugins |
-| `auto_discover` | bool, `true` | Scan the plugins directory at startup |
-| `auto_load_enabled` | bool, `true` | Load discovered plugins automatically |
-| `development_mode` | bool, `false` | Development conveniences in the web UI (editable under General settings) |
-
-## Plugin config blocks
-
-Every installed plugin stores its settings under a top-level key equal to
-its plugin id (the template ships one for the bundled `web-ui-info`
-plugin). The shape of each block is defined by that plugin's
-`config_schema.json`; common keys are `enabled` and `display_duration`.
-See [PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md).
-
-## `config/config_secrets.json`
-
-| Key | Meaning |
-|---|---|
-| `github.api_token` | Optional GitHub token the Plugin Store uses to avoid API rate limits (`src/plugin_system/store_manager.py:348`) |
-| `<plugin-id>.*` | Secrets a plugin declares with `"x-secret": true` in its config schema; merged into that plugin's config at load time |

docs/DEVELOPER_QUICK_REFERENCE.md

@@ -31,7 +31,7 @@ POST /api/v3/system/action
 
 **Base URL**: `http://your-pi-ip:5000/api/v3`
 
-See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete documentation.
+See [API_REFERENCE.md](API_REFERENCE.md) for complete documentation.
 
 ## Display Manager Quick Methods
 
@@ -190,13 +190,12 @@ def display(self, force_clear=False):
 
 ```
 LEDMatrix/
-├── plugin-repos/         # Installed plugins (default; plugins/ is only
-│                         #   for dev symlinks via scripts/dev/dev_plugin_setup.sh)
+├── plugins/              # Installed plugins
 ├── config/
 │   ├── config.json      # Main configuration
 │   └── config_secrets.json  # API keys and secrets
 ├── docs/                 # Documentation
-│   ├── REST_API_REFERENCE.md
+│   ├── API_REFERENCE.md
 │   ├── PLUGIN_API_REFERENCE.md
 │   └── ...
 └── src/
@@ -208,7 +207,7 @@ LEDMatrix/
 
 ## Quick Links
 
-- [Complete REST API Reference](REST_API_REFERENCE.md)
+- [Complete API Reference](API_REFERENCE.md)
 - [Plugin API Reference](PLUGIN_API_REFERENCE.md)
 - [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)
 - [Advanced Patterns](ADVANCED_PLUGIN_DEVELOPMENT.md)

docs/EMULATOR_SETUP_GUIDE.md

@@ -69,24 +69,23 @@ default configuration as it ships in the repo:
 ```json
 {
     "pixel_outline": 0,
-    "pixel_size": 16,
+    "pixel_size": 5,
     "pixel_style": "square",
     "pixel_glow": 6,
-    "display_adapter": "browser",
-    "allow_adapter_fallback": true,
+    "display_adapter": "pygame",
     "icon_path": null,
     "emulator_title": null,
     "suppress_font_warnings": false,
+    "suppress_adapter_load_errors": false,
     "browser": {
         "_comment": "For use with the browser adapter only.",
         "port": 8888,
-        "target_fps": 60,
+        "target_fps": 24,
         "fps_display": false,
         "quality": 70,
         "image_border": true,
         "debug_text": false,
-        "image_format": "JPEG",
-        "open_immediately": false
+        "image_format": "JPEG"
     },
     "log_level": "info"
 }
@@ -97,13 +96,13 @@ default configuration as it ships in the repo:
 | Option | Description | Default | Values |
 |--------|-------------|---------|--------|
 | `pixel_outline` | Pixel border thickness | 0 | 0-5 |
-| `pixel_size` | Size of each pixel | 16 | 1-64 (8–16 is typical for testing) |
+| `pixel_size` | Size of each pixel | 5 | 1-64 (8–16 is typical for testing) |
 | `pixel_style` | Pixel shape | "square" | "square", "circle" |
 | `pixel_glow` | Glow effect intensity | 6 | 0-20 |
-| `display_adapter` | Display backend | "browser" | "browser", "pygame" |
-| `allow_adapter_fallback` | Fall back to another adapter if the configured one fails to load | true | true/false |
+| `display_adapter` | Display backend | "pygame" | "pygame", "browser" |
 | `emulator_title` | Window title | null | Any string |
 | `suppress_font_warnings` | Hide font warnings | false | true/false |
+| `suppress_adapter_load_errors` | Hide adapter errors | false | true/false |
 
 ### 3. Browser Adapter Configuration
 
@@ -112,32 +111,18 @@ When using the browser adapter, additional options are available:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `port` | Web server port | 8888 |
-| `target_fps` | Target frames per second | 60 |
+| `target_fps` | Target frames per second | 24 |
 | `fps_display` | Show FPS counter | false |
 | `quality` | Image compression quality | 70 |
 | `image_border` | Show image border | true |
 | `debug_text` | Show debug information | false |
 | `image_format` | Image format | "JPEG" |
-| `open_immediately` | Open the browser page automatically on start | false |
 
 ## Running the Emulator
 
-### 1. Use the `-e` Flag (Recommended)
+### 1. Set Environment Variable
 
-`run.py` accepts exactly two flags: `-e`/`--emulator` and
-`-d`/`--debug`.
-
-```bash
-python3 run.py -e
-
-# With verbose logging
-python3 run.py -e -d
-```
-
-### 2. Alternative: Set the Environment Variable
-
-You can also enable emulator mode via the `EMULATOR` environment
-variable:
+Enable emulator mode by setting the `EMULATOR` environment variable:
 
 **Windows (Command Prompt):**
 ```cmd
@@ -152,6 +137,15 @@ python run.py
 ```
 
 **Linux/macOS:**
+```bash
+export EMULATOR=true
+python3 run.py
+```
+
+### 2. Alternative: Direct Python Execution
+
+You can also run the emulator directly:
+
 ```bash
 EMULATOR=true python3 run.py
 ```
@@ -159,8 +153,7 @@ EMULATOR=true python3 run.py
 ### 3. Verify Emulator Mode
 
 When running in emulator mode, you should see:
-- The emulated matrix — a web page at `http://localhost:8888` with the
-  default browser adapter, or a desktop window with the pygame adapter
+- A window displaying the LED matrix simulation
 - Console output indicating emulator mode
 - No hardware initialization errors
 
@@ -168,36 +161,7 @@ When running in emulator mode, you should see:
 
 LEDMatrix supports two display adapters for the emulator:
 
-### 1. Browser Adapter (Default)
-
-The browser adapter runs a web server and displays the matrix as a web
-page at `http://localhost:8888`. This is the adapter the shipped
-`emulator_config.json` uses.
-
-**Features:**
-- Web-based interface
-- Remote access capability
-- Mobile-friendly
-- Screenshot capture
-
-**Configuration:**
-```json
-{
-    "display_adapter": "browser",
-    "browser": {
-        "port": 8888,
-        "target_fps": 60,
-        "quality": 70
-    }
-}
-```
-
-**Usage:**
-1. Start the emulator (`python3 run.py -e`)
-2. Open browser to `http://localhost:8888`
-3. View the LED matrix display
-
-### 2. Pygame Adapter (Alternative)
+### 1. Pygame Adapter (Default)
 
 The pygame adapter provides a native desktop window with real-time display.
 
@@ -222,6 +186,33 @@ The pygame adapter provides a native desktop window with real-time display.
 - `+/-` - Zoom in/out
 - `R` - Reset zoom
 
+### 2. Browser Adapter
+
+The browser adapter runs a web server and displays the matrix in a web browser.
+
+**Features:**
+- Web-based interface
+- Remote access capability
+- Mobile-friendly
+- Screenshot capture
+
+**Configuration:**
+```json
+{
+    "display_adapter": "browser",
+    "browser": {
+        "port": 8888,
+        "target_fps": 24,
+        "quality": 70
+    }
+}
+```
+
+**Usage:**
+1. Start the emulator with browser adapter
+2. Open browser to `http://localhost:8888`
+3. View the LED matrix display
+
 ## Troubleshooting
 
 ### Common Issues
@@ -308,18 +299,17 @@ Modify the display dimensions in your main config:
 
 ### 2. Plugin Development
 
-`run.py` always runs the full rotation — it has no single-plugin flag.
-To preview or check one plugin in isolation, use the dev tools:
+For plugin development with the emulator:
 
 ```bash
-# Run the full display in emulator mode (optionally with debug logging)
-python3 run.py -e -d
+# Enable emulator mode
+export EMULATOR=true
 
-# Live single-plugin preview in the browser (port 5001)
-python3 scripts/dev_server.py
+# Run with specific plugin
+python run.py --plugin my-plugin
 
-# Headless render/validation of one plugin
-python3 scripts/check_plugin.py --plugin my-plugin
+# Debug mode
+python run.py --debug
 ```
 
 ### 3. Performance Tuning
@@ -354,10 +344,11 @@ The emulator can work alongside the web interface:
 
 ```bash
 # Terminal 1: Start emulator
-python3 run.py -e
+export EMULATOR=true
+python run.py
 
-# Terminal 2: Start web interface (supported entry point)
-python3 web_interface/start.py
+# Terminal 2: Start web interface
+python web_interface/app.py
 ```
 
 Access the web interface at `http://localhost:5000` while the emulator runs.
@@ -374,14 +365,13 @@ Access the web interface at `http://localhost:5000` while the emulator runs.
 ### 2. Plugin Testing
 
 ```bash
-# Test a specific plugin (headless check)
-python3 scripts/check_plugin.py --plugin clock-simple
+# Test specific plugin
+export EMULATOR=true
+python run.py --plugin clock-simple
 
-# Preview a single plugin live in the browser (port 5001)
-python3 scripts/dev_server.py
-
-# Test the full rotation in the emulator
-python3 run.py -e
+# Test all plugins
+export EMULATOR=true
+python run.py --test-plugins
 ```
 
 ### 3. Configuration Management
@@ -395,8 +385,9 @@ python3 run.py -e
 ### Basic Clock Display
 
 ```bash
-# Start emulator with clock enabled in config.json
-python3 run.py -e
+# Start emulator with clock
+export EMULATOR=true
+python run.py
 ```
 
 ### Sports Scores
@@ -404,16 +395,16 @@ python3 run.py -e
 ```bash
 # Configure for sports display
 # Edit config/config.json to enable sports plugins
-python3 run.py -e
+export EMULATOR=true
+python run.py
 ```
 
 ### Custom Text Display
 
 ```bash
-# Preview the text display plugin on its own
-python3 scripts/check_plugin.py --plugin text-display
-# or use the live dev preview server
-python3 scripts/dev_server.py
+# Use text display plugin
+export EMULATOR=true
+python run.py --plugin text-display --text "Hello World"
 ```
 
 ## Support

docs/GETTING_STARTED.md

@@ -21,30 +21,18 @@ This guide will help you set up your LEDMatrix display for the first time and ge
 
 ---
 
-## Quick Start
+## Quick Start (5 Minutes)
 
-### 1. Install LEDMatrix
+### 1. First Boot
 
-There is no prebuilt SD card image — you install LEDMatrix onto stock
-Raspberry Pi OS Lite yourself:
+1. Insert the MicroSD card with LEDMatrix installed
+2. Connect the LED matrix to your Raspberry Pi
+3. Plug in the power supply
+4. Wait for the Pi to boot (about 60 seconds)
 
-1. Flash Raspberry Pi OS Lite to the MicroSD card (Raspberry Pi Imager)
-2. Connect the LED matrix to your Raspberry Pi, insert the card, and
-   power on
-3. SSH into the Pi and run the one-shot installer:
-   ```bash
-   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | bash
-   ```
-   or clone the repo and run `sudo ./first_time_install.sh` — see the
-   [README Installation Steps / Quick Install](../README.md#installation-steps)
-   for full details
-
-**Expected Behavior after install:**
+**Expected Behavior:**
 - LED matrix will light up
-- A fresh install ships only the bundled `starlark-apps` and
-  `web-ui-info` plugins — clock, weather, sports, etc. must be
-  installed from the Plugin Store (web UI → Plugin Manager) before
-  anything else displays
+- Display will show default plugins (clock, weather, etc.)
 - Pi creates WiFi network "LEDMatrix-Setup" if not connected
 
 ### 2. Connect to WiFi
@@ -85,7 +73,7 @@ You should see:
 2. Set your matrix configuration:
    - **Rows**: 32 or 64 (match your hardware)
    - **Columns**: commonly 64 or 96; the web UI accepts any integer
-     in the 1–128 range, but 64 and 96 are the values the bundled
+     in the 16–128 range, but 64 and 96 are the values the bundled
      panel hardware ships with
    - **Chain Length**: Number of panels chained horizontally
    - **Hardware Mapping**: usually `adafruit-hat-pwm` (with the PWM jumper
@@ -127,16 +115,11 @@ You can also install community plugins straight from a GitHub URL using the
 
 1. Each installed plugin gets its own tab in the second navigation row
 2. Open that plugin's tab to edit its settings (favorite teams, API keys,
-   update intervals, etc.)
+   update intervals, display duration, etc.)
 3. Click **Save**
 4. Restart the display service from **Overview** so the new settings take
    effect
 
-**Note:** how long each plugin stays on screen is not set in the
-plugin's own tab — use the **Rotation** tab's **Screen Durations**
-section instead (saved to `display.display_durations` in
-`config.json`).
-
 **Example: Weather Plugin**
 - Set your location (city, state, country)
 - Add an API key from OpenWeatherMap (free signup) to
@@ -225,14 +208,12 @@ The fastest way to verify a plugin works without waiting for the rotation:
 ### Customize Your Display
 
 **Adjust display durations:**
-- Open the **Rotation** tab and use the **Screen Durations** section to
-  set how long each plugin stays on screen per rotation (saved to
-  `display.display_durations`).
+- Each plugin's tab has a **Display Duration (seconds)** field — set how
+  long that plugin stays on screen each rotation.
 
 **Organize plugin order:**
-- The **Rotation** tab also has a drag-and-drop **Rotation Order** list
-  (saved to `display.plugin_rotation_order`). Enable/disable plugins
-  from the **Plugin Manager** tab.
+- Use the **Plugin Manager** tab to enable/disable plugins. The display
+  cycles through enabled plugins in the order they appear.
 
 **Add more plugins:**
 - Check the **Plugin Store** section of **Plugin Manager** for new plugins.
@@ -299,14 +280,10 @@ sudo journalctl -u ledmatrix-web -f
 │   ├── config_secrets.json   # API keys and secrets
 │   └── wifi_config.json      # WiFi settings
 ├── plugin-repos/             # Installed plugins (default location)
+├── cache/                    # Cached data
 └── web_interface/            # Web interface files
 ```
 
-> Cached data 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 plugin install location is configurable via
 > `plugin_system.plugins_directory` in `config.json`. The default is
 > `plugin-repos/`. Plugin discovery (`PluginManager.discover_plugins()`)
@@ -326,14 +303,11 @@ System tabs:
 - WiFi              Network selection and AP-mode setup
 - Schedule          Power and dim schedules
 - Display           Matrix hardware configuration
-- Rotation          Rotation order (drag-and-drop) and screen durations
 - Config Editor     Raw config.json editor
-- Backup & Restore  Config backup and restore
 - Fonts             Upload and manage fonts
 - Logs              Real-time log viewing
 - Cache             Cached data inspection and cleanup
 - Operation History Recent service operations
-- Tools             System diagnostics, updates, dependencies, maintenance
 
 Plugin tabs (second row):
 - Plugin Manager    Browse the Plugin Store, install/enable plugins

docs/HOW_TO_RUN_TESTS.md

@@ -10,7 +10,10 @@ Make sure you have the testing packages installed:
 
 ```bash
 # Install all dependencies including test packages
-pip install -r requirements.txt -r requirements-test.txt
+pip install -r requirements.txt
+
+# Or install just the test dependencies
+pip install pytest pytest-cov pytest-mock
 ```
 
 ### 2. Set Environment Variables
@@ -250,6 +253,7 @@ test/
 ├── test_error_aggregator.py             # Error aggregation tests
 ├── test_schema_manager.py               # Schema manager tests
 ├── test_web_api.py                      # Web API tests
+├── test_nba_*.py                        # NBA-specific test suites
 ├── plugins/                             # Per-plugin test suites
 │   ├── test_clock_simple.py
 │   ├── test_calendar.py
@@ -299,7 +303,7 @@ If tests fail due to missing packages:
 
 ```bash
 # Install all dependencies
-pip install -r requirements.txt -r requirements-test.txt
+pip install -r requirements.txt
 
 # Or install specific missing package
 pip install <package-name>
@@ -331,15 +335,15 @@ pytest --cov=src --cov-report=html
 
 ## Continuous Integration
 
-The repo runs the pytest suite via
-[`.github/workflows/test.yml`](../.github/workflows/test.yml) on every
-push and pull request: a plugin-safety job (harness, visual rendering
-and plugin-matrix tests) plus a unit-test job that runs an explicit
-allowlist of suites — new test files must be added to that list to run
-in CI. Release version consistency is checked by
-[`.github/workflows/release-version-check.yml`](../.github/workflows/release-version-check.yml).
-Bandit, flake8, mypy and gitleaks run as pre-commit hooks (see
-`.pre-commit-config.yaml`), not in CI.
+The repo runs
+[`.github/workflows/security-audit.yml`](../.github/workflows/security-audit.yml)
+(bandit + semgrep) on every push. A pytest CI workflow at
+`.github/workflows/tests.yml` is queued to land alongside this
+PR ([ChuckBuilds/LEDMatrix#307](https://github.com/ChuckBuilds/LEDMatrix/pull/307));
+the workflow file itself was held back from that PR because the
+push token lacked the GitHub `workflow` scope, so it needs to be
+committed separately by a maintainer. Once it's in, this section
+will be updated to describe what the job runs.
 
 ## Best Practices
 

docs/MIGRATION_GUIDE.md

@@ -86,7 +86,7 @@ The plugin system has been enhanced but remains backward compatible with existin
 
 If you encounter issues during migration:
 
-1. Check the [project root README](../README.md) for current installation and usage instructions
+1. Check the [README.md](README.md) for current installation and usage instructions
 2. Review script README files:
    - [`scripts/install/README.md`](../scripts/install/README.md) - Installation scripts documentation
    - [`scripts/fix_perms/README.md`](../scripts/fix_perms/README.md) - Permission scripts documentation

docs/PLUGIN_API_REFERENCE.md

@@ -201,9 +201,8 @@ the mode selector for this plugin.
 
 #### `get_vegas_segment_width() -> Optional[int]`
 
-For `FIXED_SEGMENT` plugins, the number of *panels* the segment
-occupies in the scroll (pixel width = panels × `single_panel_width`,
-from `display.hardware.cols`). `None` uses the default of 1 panel.
+For `FIXED_SEGMENT` plugins, the width in pixels of the segment they
+occupy in the scroll. `None` lets the controller pick a default.
 
 > The full source for `BasePlugin` lives in
 > `src/plugin_system/base_plugin.py`. If a method here disagrees with the

docs/PLUGIN_ARCHITECTURE_SPEC.md

@@ -8,12 +8,9 @@
 > - 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 is mounted at `/api/v3` (`web_interface/app.py:144`).
 > - 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`;
->   the shipped base classes live in `src/base_classes/` (e.g.
->   `src.base_classes.sports.SportsCore`, `src.base_classes.hockey.Hockey`).
 > - The "Migration Strategy" and "Implementation Roadmap" sections
 >   describe work that has now shipped.
 >

docs/PLUGIN_CONFIG_ARCHITECTURE.md

@@ -1,11 +1,5 @@
 # Plugin Configuration Tabs - Architecture
 
-> This page covers internals (how the config system works under the
-> hood). For designing a plugin's config schema, the canonical guide is
-> [PLUGIN_CONFIGURATION_GUIDE.md](PLUGIN_CONFIGURATION_GUIDE.md); for
-> the user-facing tabs feature, see
-> [PLUGIN_CONFIGURATION_TABS.md](PLUGIN_CONFIGURATION_TABS.md).
-
 ## System Architecture
 
 ### Component Overview

docs/PLUGIN_CUSTOM_ICONS.md

@@ -296,7 +296,7 @@ Want to change icons programmatically? While not officially supported, you could
 ## Related Documentation
 
 - [Plugin Configuration Tabs](PLUGIN_CONFIGURATION_TABS.md) - Main plugin tabs documentation
-- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - How to create plugins
+- [Plugin Development Guide](plugin_docs/) - How to create plugins
 - [Font Awesome Icons](https://fontawesome.com/icons) - Browse all available icons
 - [Emoji Reference](https://unicode.org/emoji/charts/full-emoji-list.html) - All emoji options
 

docs/PLUGIN_DEPENDENCY_TROUBLESHOOTING.md

@@ -169,6 +169,6 @@ If you continue to experience issues:
 ## Related Documentation
 
 - [Plugin Dependency Guide](PLUGIN_DEPENDENCY_GUIDE.md)
-- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)
-- [Troubleshooting](TROUBLESHOOTING.md)
+- [Plugin Development Guide](docs/plugin_development.md)
+- [Troubleshooting Quick Start](TROUBLESHOOTING_QUICK_START.md)
 

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -589,24 +589,11 @@ Your plugin must:
 ### Versioning Best Practices
 
 - **Use semantic versioning**: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
-- **GitHub as source of truth**: the plugin store resolves versions in this
-  order: GitHub Releases → GitHub Tags → manifest from branch → git commit hash
-- **Automatic version bumping**: install the self-contained pre-push hook in
-  your plugin repo and patch versions bump themselves on push (a git tag
-  `v{version}` is created and `manifest.json` staged automatically):
+- **Automatic version bumping**: Use the pre-push git hook for automatic patch version bumps
+- **Manual versioning**: Only needed for major/minor bumps or special cases
+- **GitHub as source of truth**: Plugin store fetches versions from GitHub releases/tags/manifest
 
-  ```bash
-  # From your plugin repository directory
-  cp /path/to/LEDMatrix/scripts/git-hooks/pre-push-plugin-version .git/hooks/pre-push
-  chmod +x .git/hooks/pre-push
-  ```
-
-  Set `SKIP_TAG=1` in the environment to skip auto-tagging for one push.
-- **Manual versioning**: only needed for major/minor bumps, CI pipelines that
-  bypass hooks, or forks without the hook — use
-  `scripts/bump_plugin_version.py`.
-- **Registry stores no versions**: `plugins.json` holds only metadata (name,
-  description, repo URL).
+See the [Git Workflow rules](../.cursorrules) for version management details.
 
 ### Submitting to Official Registry
 
@@ -680,5 +667,5 @@ For your plugin to work well in the plugin store:
 - [Advanced Plugin Development](ADVANCED_PLUGIN_DEVELOPMENT.md) - Advanced patterns and examples
 - [Plugin Quick Reference](PLUGIN_QUICK_REFERENCE.md) - Quick development reference
 - [Plugin Configuration Guide](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup
-- [Plugin Store Guide](PLUGIN_STORE_GUIDE.md) - Using the plugin store
+- [Plugin Store User Guide](PLUGIN_STORE_USER_GUIDE.md) - Using the plugin store
 

docs/PLUGIN_QUICK_REFERENCE.md

@@ -14,10 +14,8 @@ and [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md).
 ✅ **GitHub Store**: Discovery from `ledmatrix-plugins` registry plus
    any GitHub URL
 ✅ **Plugin Location**: configured by `plugin_system.plugins_directory`
-   in `config.json` (default `plugin-repos/`). Plugin discovery scans
-   only this directory — there is no loader fallback to `plugins/`
-   (only Plugin Store operations and schema lookup additionally probe
-   `plugins/`)
+   in `config.json` (default `plugin-repos/`; the loader also searches
+   `plugins/` as a fallback)
 
 ## File Structure
 
@@ -111,7 +109,7 @@ git push -u origin main
 git tag v1.0.0
 git push origin v1.0.0
 
-# Submit to registry (PR to ChuckBuilds/ledmatrix-plugins)
+# Submit to registry (PR to ChuckBuilds/ledmatrix-plugin-registry)
 ```
 
 ## Using Plugins
@@ -122,12 +120,12 @@ git push origin v1.0.0
 2. **Install**: Click **Install** in the plugin's row
 3. **Configure**: open the plugin's tab in the second nav row
 4. **Enable/Disable**: toggle switch in the **Installed Plugins** list
-5. **Reorder**: use the drag-and-drop **Rotation Order** list in the
-   **Rotation** tab (saved to `display.plugin_rotation_order`)
+5. **Reorder**: order is set by the position in `display_modes` /
+   plugin order; rearranging via drag-and-drop is not yet supported
 
 ### REST API
 
-The API is mounted at `/api/v3` (`web_interface/app.py:199`).
+The API is mounted at `/api/v3` (`web_interface/app.py:144`).
 
 ```bash
 # Install plugin from the registry

docs/PLUGIN_REGISTRY_SETUP_GUIDE.md

@@ -323,22 +323,16 @@ curl -X POST http://pi:5000/api/v3/plugins/install-from-url \
 ### Regular Updates
 
 ```bash
-# Refresh local clones of all plugin repos
-python3 scripts/update_plugin_repos.py
+# Update stars/downloads counts
+python3 scripts/update_stats.py
 
-# (Re-)create local plugin repo checkouts from the registry
-python3 scripts/setup_plugin_repos.py
+# Validate all plugin entries
+python3 scripts/validate_registry.py
 
-# Audit installed plugins for manifest/schema problems
-python3 scripts/audit_plugins.py
-
-# Validate a single plugin
-python3 scripts/check_plugin.py --plugin <plugin-id>
+# Check for plugin updates
+python3 scripts/check_updates.py
 ```
 
-Registry regeneration (`update_registry.py`) lives in the
-`ledmatrix-plugins` monorepo, not in this repo.
-
 ## Converting Existing Plugins
 
 To convert your existing plugins (hello-world, clock-simple) to this system:
@@ -406,7 +400,7 @@ print(f'Found {len(registry[\"plugins\"])} plugins')
 
 ## References
 
-- Plugin Store Implementation: See `PLUGIN_IMPLEMENTATION_SUMMARY.md`
-- User Guide: See `PLUGIN_STORE_GUIDE.md`
+- Plugin Store Implementation: See `PLUGIN_STORE_IMPLEMENTATION_SUMMARY.md`
+- User Guide: See `PLUGIN_STORE_USER_GUIDE.md`
 - Architecture: See `PLUGIN_ARCHITECTURE_SPEC.md`
 

docs/PLUGIN_STORE_GUIDE.md

@@ -481,13 +481,13 @@ A: Yes, if a plugin needs API keys, it can access them like core managers do.
 A: Most plugins are small (1-5MB). Check individual plugin documentation for specific requirements.
 
 **Q: Can I create my own plugin?**
-A: Yes! See [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) for instructions.
+A: Yes! See [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) for instructions.
 
 ---
 
 ## Related Documentation
 
-- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) - Create your own plugins
+- [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) - Create your own plugins
 - [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) - Plugin API documentation
-- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) - Plugin system architecture (historical)
+- [PLUGIN_ARCHITECTURE.md](PLUGIN_ARCHITECTURE.md) - Plugin system architecture
 - [REST_API_REFERENCE.md](REST_API_REFERENCE.md) - Complete REST API reference

docs/README.md

@@ -29,16 +29,15 @@ Start here:
 Going deeper:
 
 - [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) — advanced patterns
-- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — original plugin-system design spec (historical; see its banner for what has drifted)
+- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — full plugin-system spec
 - [PLUGIN_DEPENDENCY_GUIDE.md](PLUGIN_DEPENDENCY_GUIDE.md) /
   [PLUGIN_DEPENDENCY_TROUBLESHOOTING.md](PLUGIN_DEPENDENCY_TROUBLESHOOTING.md)
 - [PLUGIN_WEB_UI_ACTIONS.md](PLUGIN_WEB_UI_ACTIONS.md) (+ [example JSON](PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json))
-- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md)
+- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.md) /
+  [PLUGIN_CUSTOM_ICONS_FEATURE.md](PLUGIN_CUSTOM_ICONS_FEATURE.md)
 - [PLUGIN_REGISTRY_SETUP_GUIDE.md](PLUGIN_REGISTRY_SETUP_GUIDE.md) (+ [registry template](plugin_registry_template.json))
 - [STARLARK_APPS_GUIDE.md](STARLARK_APPS_GUIDE.md) — Starlark-based mini-apps
 - [widget-guide.md](widget-guide.md) — widget development
-- [ADAPTIVE_LAYOUT.md](ADAPTIVE_LAYOUT.md) — render legibly on any panel size (opt-in font/layout scaling)
-- [plugin-safety-harness.md](plugin-safety-harness.md) — test a plugin across every screen and matrix size
 
 ## Configuring plugins
 
@@ -53,12 +52,9 @@ Going deeper:
 - [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) — Vegas scroll, on-demand display,
   cache management, background services, permissions
 - [FONT_MANAGER.md](FONT_MANAGER.md) — font system
-- [SKIN_SYSTEM.md](SKIN_SYSTEM.md) — skin architecture for sports scoreboards
-- [CREATING_SKINS.md](CREATING_SKINS.md) — writing and validating a skin
 
 ## Reference
 
-- [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) — every key in config.json and config_secrets.json
 - [REST_API_REFERENCE.md](REST_API_REFERENCE.md) — all web-interface HTTP endpoints
 - [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) — Python APIs available to plugins
 - [DEVELOPER_QUICK_REFERENCE.md](DEVELOPER_QUICK_REFERENCE.md) — common dev tasks
@@ -70,7 +66,6 @@ Going deeper:
 - [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) — running the test suite
 - [MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) — multi-repo workspace
 - [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) — breaking changes between releases
-- [SPORTS_UNIFICATION.md](SPORTS_UNIFICATION.md) — how the sports scoreboard base classes are organized
 
 ## Archive
 

docs/REST_API_REFERENCE.md

@@ -31,9 +31,9 @@ All endpoints return JSON responses with a standard format:
 - [Plugin-specific endpoints](#plugin-specific-endpoints)
 - [Starlark Apps](#starlark-apps)
 
-> The API blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
+> The API blueprint is mounted at `/api/v3` (`web_interface/app.py:144`).
 > SSE stream endpoints (`/api/v3/stream/*`) are defined directly on the
-> Flask app at `app.py:799-809`. There are 94 routes total — see
+> Flask app at `app.py:607-615`. There are about 92 routes total — see
 > `web_interface/blueprints/api_v3.py` for the canonical list.
 
 ---

docs/SKIN_SYSTEM.md

@@ -33,7 +33,7 @@ crashing) simply restores the built-in look.
 ## The render funnel
 
 Every sports scoreboard (baseball, football, basketball, hockey — anything
-built on the `src/base_classes/sports/` package, `core.py`) renders through exactly one seam:
+built on `src/base_classes/sports.py`) renders through exactly one seam:
 `SportsCore._render_game(game, force_clear)`.
 
 1. The mode class's `display()` (live, `SportsUpcoming`, `SportsRecent`)

docs/SPORTS_UNIFICATION.md

@@ -1,387 +0,0 @@
-# Sports Code Unification — Architecture
-
-How the nine sports scoreboard plugins converge onto shared core code **without**
-becoming nine clients of a god class.
-
-## The problem
-
-Nine plugins (`afl`, `baseball`, `basketball`, `football`, `hockey`, `lacrosse`,
-`nrl`, `soccer`, `ufc`) each ship a ~3,000-line `sports.py` descended from this
-repo's `src/base_classes/sports.py`. They have drifted into three lineages, and
-only 28 of the 66 methods appearing across them are present in all nine. One
-logical fix (the UTC start-time bug) cost 75 files.
-
-Merging everything into one base class would fix the duplication and create a
-worse problem: a single 2,500-line class that all nine plugins inherit, where any
-change has a nine-plugin blast radius and per-sport behavior survives only as
-`if self.sport == "hockey"` branches.
-
-## Three properties, three mechanisms
-
-These are independent concerns. Conflating them is what produces god classes.
-
-### Upgradability — a plugin keeps working across core versions
-
-| Rule | Mechanism |
-|---|---|
-| Plugin loads on a core that predates a module | Guarded import with a bundled fallback (`try: from src.X import Y / except ModuleNotFoundError: from y import Y`) |
-| Plugin loads on a core that predates a *method* | Capability probing — `hasattr(SportsCore, "_detect_stale_games")` — never a version comparison. The loader's compat check is advisory-only (it logs and continues), so probing is the real protection. |
-| Core changes never break a plugin's rendering | The **view-model contract**: `_extract_game_details_common` returns a dict whose `GUARANTEED_KEYS` are frozen by `test/test_skin_system.py::TestViewModelContract`. Keys may be added, never renamed or removed. |
-| A plugin can drop its bundled copy safely | The **sunset rule**: its manifest must floor `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`) — *necessary but not sufficient*. Nothing enforces that floor today, so the copy also waits for the B6 gate below. |
-
-The core API is **additive-only**. A method the plugins call is never removed or
-given a new required parameter; new behavior arrives as new methods with
-defaults, or as capabilities they opt into.
-
-### Reusability — write once, nine plugins benefit
-
-Only code that is **identical in intent across all nine** moves into the base
-class. That set is small and knowable — it is exactly the methods present in every
-copy today (phase B1 below). Everything else stays where it is until it earns
-promotion.
-
-### Modularity — a change to one feature cannot reach a plugin that doesn't use it
-
-This is the property the naive merge destroys, and it is enforced structurally:
-
-1. **Capabilities are separate modules composed by inheritance, not config
-   branches inside the base class.** Hockey has no celebrations, so
-   `HockeyLive` does not inherit `CelebrationMixin` — the celebration code is not
-   merely disabled for hockey, it is *not in hockey's MRO at all*. No shared
-   state, no dead branches, no risk. Contrast with
-   `if self.celebrations_enabled:` inside `SportsLive`, where a bug in
-   celebration code can still crash a plugin that never wanted the feature.
-
-2. **Variant behavior is a strategy object chosen by name, not a branch.**
-   Live rotation exists in three dialects across the lineages; core ships all
-   three behind `rotation_strategy: "swrr" | "weighted" | "simple"` and a plugin
-   may register its own. Core never learns sport names.
-
-3. **Sport-specific behavior is a documented override point.** The base class
-   declares the seam; the plugin fills it. Basketball's tournament-round parsing
-   and baseball's BDF sizing stay in their plugins forever — they are not
-   candidates for promotion, and core must never grow a branch for them.
-
-4. **Files bound the blast radius.** Capabilities live in their own modules so a
-   diff shows at a glance which plugins a change can reach.
-
-## Layering
-
-```
-src/base_classes/sports/
-  __init__.py            re-exports the public API (import path unchanged)
-  core.py                SportsCore — fetch, cache, config, logos, fonts, odds,
-                         view-model extraction, the skin seam
-  modes.py               SportsUpcoming / SportsRecent / SportsLive
-  capabilities/
-    celebrations.py      CelebrationMixin        (opt-in: 4 of 9 plugins)
-    rotation.py          RotationStrategy + registry
-
-src/common/
-  sports_scroll.py       SportsScrollDisplay / …Manager — scroll orchestration
-                         (content building stays in the plugins)
-```
-
-`from src.base_classes.sports import SportsCore` keeps working — the package
-`__init__` re-exports, so the conversion is invisible to every existing importer.
-
-## Override points (the plugin-facing seam)
-
-The base class calls these; plugins implement or override them. This table is the
-contract — additions require a default implementation, removals require a
-deprecation cycle.
-
-| Hook | Purpose | Default |
-|---|---|---|
-| `_fetch_data()` | Sport's schedule source | abstract |
-| `_extract_game_details(event)` | Sport-specific view-model fields on top of the common ones | delegates to `_extract_game_details_common` |
-| `_draw_scorebug_layout(game, force_clear)` | Sport's card rendering | base layout |
-| `_custom_scorebug_layout(game, draw)` | Per-sport overlay on the base layout | no-op |
-| `render_skin_card(game, size)` | Skin-system entry point | built-in fallback |
-| `score_phrase(points, team_abbr)` | Celebration wording (`"GOOOOAAALLL!"` vs `"TOUCHDOWN!"`). `points` is the score delta, which sports with variable-value scores use to name the play | `"<abbr> SCORES!"` — only consulted when `CelebrationMixin` is present |
-| `win_phrase(team_abbr)` | Win-celebration wording | `"<abbr> WINS!"` — mixin only |
-| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching | `game["<side>_abbr"]` |
-| `_config_schema_path()` | Plugin's `config_schema.json` — returning it routes `_get_layout_offset` through the `src.element_style` resolver (and gives it the defaults to compare against) | `None`, i.e. the classic inline `customization.layout` read |
-| `_font_root()` | Directory to resolve `assets/fonts` against | core install root |
-
-Two class attributes serve the same purpose for values that are per-sport
-constants rather than behavior:
-
-| Attribute | Meaning | Default |
-|---|---|---|
-| `FINAL_PERIOD` | Period at/after which a zero clock can mean "over" | `4` (hockey overrides to `3`) |
-| `CLOCK_COUNTS_DOWN` | Whether `0:00` means "expired" | `True` (soccer/afl/nrl override to `False` — their clocks count up, so `0:00` is kickoff) |
-| `COALESCE_SCORING_SEQUENCE` | Fold score increments arriving during an active celebration into that one celebration | `False` (football overrides to `True` — a touchdown lands as +6, then +1 for the extra point) |
-
-### Why these are seams and not branches
-
-`_favorite_key` exists because NRL abbreviations are **not unique** — "NEW" is both
-Newcastle Knights and New Zealand Warriors, "CAN" both Canberra and Canterbury —
-so NRL matches favorites on team ID. Flattening every plugin to abbreviations
-would silently select the wrong club for NRL users. The base declares the seam,
-NRL fills it, and core never learns the string `"nrl"`.
-
-`CLOCK_COUNTS_DOWN` exists for the same reason in the opposite direction: a
-soccer clock reading `0:00` means the match has not kicked off, so running the
-clock-expiry branch there would evict live games.
-
-`COALESCE_SCORING_SEQUENCE` is the third of the same kind. In football one
-scoring play arrives as two score updates, so the follow-up must be folded into
-the first celebration; in soccer two increments a few seconds apart are two real
-goals, and folding them would swallow one. Neither default is "right" — which is
-precisely why it is a declared per-sport constant rather than a hidden
-assumption baked into the shared body.
-
-## Capabilities
-
-```
-capabilities/
-  celebrations.py   CelebrationMixin        opt-in: afl, nrl, soccer, football
-  rotation.py       RotationStrategy + registry
-```
-
-**`CelebrationMixin`** merges the two dialects the lineages grew
-(`_check_for_goal`/`celebrate_opponent_goals` vs
-`_check_for_score`/`celebrate_opponent_scores`). Their bodies were identical
-apart from three things, each now a seam: wording (`score_phrase`), follow-up
-suppression (`COALESCE_SCORING_SEQUENCE`), and team identity (`_favorite_key`,
-so NRL matches on id). Both config spellings are read, so a plugin adopting the
-mixin keeps working with the keys already in its published schema.
-
-Mix it in **before** the mode class — `class SoccerLive(CelebrationMixin,
-SportsLive)` — so the celebration `display()` runs first and falls through to
-the scorebug via `super()`.
-
-**Rotation strategies.** The three "dialects" turned out to be one algorithm
-(Smooth Weighted Round-Robin) in two shapes: an incremental picker holding state
-across calls (afl/nrl/soccer) and a precomputed per-cycle list
-(football/baseball/basketball, and hockey with a different loop shape). They
-agree within a cycle and differ only at the boundary — the incremental form has
-no restart seam — so core ships both rather than declaring a winner:
-
-```python
-self.rotation = get_rotation_strategy("swrr", weight_for=self._live_weight)
-```
-
-`weight_for` is supplied by the host, so the *favorites* policy stays with the
-plugin and `rotation.py` never learns what a favorite is. An unknown strategy
-name degrades to `simple` rather than raising: the name comes from user config,
-and a typo should cost the boost, not the scoreboard. When a plugin needs an
-ordering that core does not ship, it calls `register_rotation_strategy` to add
-its own — rather than core growing a branch for it.
-
-`test_sports_capabilities.py` checks each strategy against a **verbatim
-transcription** of the plugin code it replaces, over every live-game shape up to
-four games. That differential is what B5 deletes the bundled copies on the
-strength of.
-
-## Scroll display — where the promotion line falls
-
-`src/common/sports_scroll.py` is deliberately *not* a superset of the ten
-`scroll_display.py` copies. A method-level comparison of the eight that share a
-shape (f1 and ufc are genuine forks) found a sharp split:
-
-| Layer | Evidence | Outcome |
-|---|---|---|
-| Orchestration — `get_all_vegas_content_items`, `clear_all`, `get_scroll_info`, `get_dynamic_duration`, `is_complete`, `display_frame` | identical to 96–100% similar across all eight | **promoted** |
-| Settings — `_get_scroll_settings` | one algorithm; the copies differ *only* in which league keys they walk | **promoted**, with the ladder as data (`SCROLL_LEAGUE_KEYS`) |
-| Content — `prepare_scroll_content`, `_load_separator_icons` | 8 distinct bodies across 8 plugins (145 lines, 53% similar at worst); icons 6% | **override point, permanently** |
-
-Same name, different job: `prepare_scroll_content` draws *this sport's* game
-card. Merging the eight bodies would be the exact mistake the promotion rule
-exists to prevent, so the base class raises `NotImplementedError` rather than
-rendering something plausible — a base that rendered *something* would let a
-plugin ship a silently blank scroll.
-
-The one behavior the upstreamed version adds is native
-`global_config['target_fps']` support. The bundled copies hardcode ~100 FPS via
-`scroll_delay = 0.01` and never consult the global smooth-scrolling target;
-Part A threaded it through each copy by hand, and this makes that threading
-legacy compatibility rather than the mechanism.
-
-## Phases
-
-B0–B3 are merged and shipping in core 3.2.0. Everything that remains is
-**rollout**, and it splits into three phases with very different risk profiles.
-The original plan folded the last two together; they are separated here because
-one of them is safe by construction and the other is not.
-
-| Phase | Scope | Status | Gate |
-|---|---|---|---|
-| **B0** | Characterization tests, CI unit job, `element_style`, font cwd fix, CHANGELOG discipline | ✅ | — |
-| **B1** | Promote the nine universal methods; convert `sports.py` → package | ✅ | Characterization suite green; no behavior change intended |
-| **B2** | `CelebrationMixin` + rotation strategies as opt-in capabilities | ✅ | Non-adopters have zero new code in their MRO; strategies checked against verbatim plugin transcriptions |
-| **B3** | Upstream the scroll **orchestration** layer as `src/common/sports_scroll.py`, reading `global_config['target_fps']` natively | ✅ | Content building stays per-sport |
-| **B4** | Ship 3.2.0 *and* make version reporting trustworthy | ⏳ **next** | Tag, release, and `src.__version__` agree; compatibility gate merged |
-| **B5** | Adoption — guarded core imports: three pilots, then the remaining six. **Bundled copies stay.** | after B4 | Per plugin: harness + goldens byte-identical, then a device soak |
-| **B6** | Sunset — delete the bundled copies | **blocked** | B4's gate shipped *and* in users' hands (see below) |
-
-### B4 — what "ship 3.2.0" actually requires
-
-Cutting the tag is the small part. The version *number* has to become something
-a floor can be trusted against, and today it is not:
-
-- **The tag and `src.__version__` have never agreed.** `v3.1.0` was tagged
-  2026-05-31; `__version__` only became `"3.1.0"` on 2026-07-12 (`7f7f0d64`).
-  The v3.1.0 release therefore reports `__version__ = "1.0.0"`.
-- **Which silences the compatibility warning entirely for that population.**
-  `PluginLoader._warn_if_incompatible` skips the check when the parsed core
-  version is below `(2, 0, 0)` — an anti-spam guard that, given the above,
-  matches exactly the users most likely to be behind.
-- **Nothing enforces a floor anyway.** The check is advisory (it logs and
-  continues), and neither `StoreManager.install_plugin` nor
-  `StoreManager.update_plugin` compares the core version at all — `update_plugin`
-  compares the plugin's manifest version against the registry's
-  `latest_version` and nothing else.
-
-So B4 is: tag and release 3.2.0; make the tag, the release, and `__version__`
-agree, and keep them agreeing; reconsider the `< 2.0.0` skip; migrate manifests
-from `ledmatrix_min` to `ledmatrix_min_version`; and add the install/update
-compatibility gate that B6 depends on.
-
-#### Two fields express compatibility, and the gate only reads one
-
-`compatible_versions` is the canonical contract: `schema/manifest_schema.json`
-**requires** it, all 42 published manifests carry it, and it holds semver
-*ranges* — `[">=2.0.0"]` in 41 of them, `[">=1.0.0"]` in `7-segment-clock`.
-`ledmatrix_min_version` is the optional per-release floor inside `versions[]`.
-
-The gate as merged reads only the floor. Today that is harmless: no manifest
-uses an upper bound, and the two fields agree everywhere except
-`7-segment-clock` (`>=1.0.0` against a `2.0.0` floor). But the fields *can*
-disagree, and the range syntax the schema already permits includes upper bounds
-— a plugin declaring `["2.0.0 - 2.9.9"]` means "not compatible with 3.x" and
-the gate would install it on 3.2.0 regardless.
-
-**Before B6, the gate must evaluate `compatible_versions` as well**, and the
-manifest migration must reconcile the two fields rather than only renaming the
-floor. Deciding which wins when they disagree is part of that work; the safe
-default is the more restrictive.
-
-(The schema also deprecates a top-level `ledmatrix_version` in favour of
-`compatible_versions`. No manifest still carries it, so there is nothing to
-migrate there.)
-
-### B5 — adoption is safe by construction
-
-A plugin adopting core imports keeps its bundled copy and reaches it through the
-guarded import (see the Upgradability table above). On a core that ships the
-module the plugin uses core code; on one that doesn't it falls back and behaves
-exactly as it does today. There is no version of this step that breaks a user,
-which is why it does not wait for B6's gate.
-
-The hockey scroll-display pilot is **already validated**: adopted against a core
-carrying 3.2.0, `scroll_display.py` went from 691 to 289 lines and all 16 harness
-renders (8 sizes × 2 screens) came out byte-for-byte identical to the
-pre-adoption run. That byte-comparison is the acceptance gate for every
-adoption. The recipe and its two gotchas are in the plugins repo's
-`docs/plugin-development/08-shared-sports-code.md`.
-
-### B6 — why the sunset needs more than a version floor
-
-Deleting a bundled copy removes the fallback, so the guarded import becomes a
-hard dependency. On a core without the module the plugin raises
-`ModuleNotFoundError` at load; `PluginManager.load_plugin` catches it, records
-`PluginState.ERROR`, logs one line, and continues. Nothing crashes — the user
-simply loses that scoreboard, with no visible explanation.
-
-Verified against a `v3.1.0` worktree: `src/common/sports_scroll.py`,
-`src/element_style.py` and the `src/base_classes/sports/` package are all absent
-there, and the import fails with `exc.name == 'src.common.sports_scroll'`. Guard
-sets must name that exact dotted path — `{"src"}` alone does not match it.
-
-Combined with the B4 findings, a plugin that deletes its copy today reaches an
-un-updated user through a normal store update, fails to load, and warns nobody.
-**B6 therefore waits for B4's compatibility gate to have shipped and to have
-been in users' hands long enough that the population running a core without it
-is small.** The bundled copies cost disk space; deleting them early costs
-scoreboards, silently. That trade is not close.
-
-Before the first sunset, add a **compatibility regression test**. It has to
-cover four cases, not one — B5's safety claim and B6's failure mode are
-different propositions and only the second is obvious:
-
-| | bundled copy present | bundled copy removed |
-|---|---|---|
-| **pinned old core** | **loads** — this is B5's whole guarantee, that the guarded import falls back | `PluginState.ERROR`, and the recorded error names the exact missing module |
-| **current core** | loads, using core code | loads, using core code |
-
-The top-left cell is the one worth writing first: nothing in the suite currently
-proves that an adopted plugin still works on a core that predates the module,
-which is the entire basis for saying B5 is safe to run ahead of the gate.
-
-Assert the old-core/removed-copy case as `PluginState.ERROR` **plus the missing
-module path**, not as an uncaught exception. `PluginManager.load_plugin` catches
-`ModuleNotFoundError`, so nothing propagates — a test expecting a raise would
-pass for the wrong reason on a core where the module is merely broken rather
-than absent. "Fails loudly" is aspirational, not what the code does today: it
-fails into `ERROR` state with one log line, which is precisely why B6 needs the
-gate rather than trusting the failure to be noticed.
-
-The same suite should exercise the install/update gate, since it is the other
-half of the guarantee.
-
-## What's next
-
-In order. Each step is independently useful and independently revertible.
-
-1. **Tag and publish v3.2.0.** The code is already on `main` (`21825cbf`).
-   Nothing else blocks this, and it is what makes `ledmatrix_min_version:
-   "3.2.0"` refer to something real.
-2. **Make the version number honest.** Have the release process assert that the
-   tag, the GitHub release, and `src.__version__` agree — a check in CI is
-   cheaper than the confusion of the last two releases. Then revisit the
-   `< 2.0.0` skip in `_warn_if_incompatible`, which currently silences the
-   warning for the users who most need it.
-3. **Add the compatibility gate** to `StoreManager.install_plugin` and
-   `.update_plugin`: refuse a plugin whose declared floor exceeds
-   `src.__version__`, and surface the reason in the store UI rather than only
-   the log. This is the single change that turns the floor from documentation
-   into a guarantee, and B6 depends on it.
-4. **Migrate the manifests** to `ledmatrix_min_version`, and reconcile them with
-   `compatible_versions` (see above — that field is the required, canonical one,
-   and the gate does not read it yet). Currently 28 plugins spell the floor both
-   ways across their `versions[]` entries, 12 use only the old spelling, and 2
-   only the new. Scope the sweep to the nine sports plugins if a 42-plugin
-   version-bump wave isn't worth it — but the `compatible_versions` half has to
-   cover every manifest the gate can refuse, or define explicit legacy handling,
-   before the gate is allowed to block anything.
-5. **Run B5 adoption** — hockey, soccer, football, then the remaining six.
-   Bundled copies stay. Byte-identical harness output per plugin, then a soak.
-6. **Only then plan B6**, with the compatibility regression test described above
-   in CI first.
-
-## How to keep this project healthy
-
-Lessons this migration paid for, worth applying beyond it:
-
-- **A version number is a promise; keep it in one place.** Three different
-  answers to "what version am I on" (tag, release, `__version__`) is what made
-  the floor untrustworthy. Assert their agreement mechanically.
-- **Advisory checks protect nobody.** If a rule matters, enforce it where the
-  action happens — the install path, not a log line the user will never read.
-  If it doesn't matter enough to enforce, don't write the rule.
-- **Prefer failures that are loud and early.** A plugin that dies at load with
-  one journal line is indistinguishable, to a user, from a plugin that was never
-  installed. Surface plugin health in the UI.
-- **Keep the two repos' rules in sync deliberately.** The sunset rule lives in
-  both this file and the plugins repo's
-  `docs/plugin-development/08-shared-sports-code.md`. When one changes, change
-  the other in the same PR — drift between them is how a contributor ends up
-  following a rule that was superseded.
-- **Measure before and after, on real hardware.** Byte-identical harness renders
-  and a device soak caught what unit tests could not. Reserve "it should be
-  fine" for things you have actually looked at.
-
-## Rules for contributors
-
-- **Promote on evidence, not intuition.** A method moves to core when every copy
-  has it and they agree on intent. Otherwise it stays in the plugins.
-- **Never add a sport name to core.** If core needs to know which sport it is,
-  the design is wrong — add an override point instead.
-- **A capability that is not opted into must not execute.** If you find yourself
-  writing `if self.<capability>_enabled` inside a base class, it belongs in a
-  mixin.
-- **Touch the view-model keys only additively.** Published skins depend on them.
-- **Every promotion lands with the characterization suite green**, and every
-  pilot adoption lands with that plugin's harness and golden suites green.

docs/TROUBLESHOOTING.md

@@ -82,70 +82,6 @@ python3 web_interface/start.py
 
 ## Common Issues by Category
 
-### Installation & Build Issues
-
-#### Step 6 fails: "Failed building wheel for rgbmatrix"
-
-**Symptoms:**
-
-```
-note: This error originates from a subprocess, and is likely not a problem with pip.
-  ERROR: Failed building wheel for rgbmatrix
-Failed to build rgbmatrix
-✗ Failed to install rpi-rgb-led-matrix Python package
-```
-
-**Cause:**
-
-Almost always the kernel's out-of-memory killer, not missing build tools. The
-`rpi-rgb-led-matrix` library compiles roughly 45 C++ translation units, two of
-them Cython-generated — a single `cc1plus` on those can peak near 800MB. The
-build system defaults to running several of those at once, which exceeds RAM on
-512MB and 1GB boards. Because the OOM killer writes nothing to pip's output, the
-failure looks like a toolchain problem, and `sudo apt install -y
-python-dev-is-python3 cmake build-essential` will report everything is already
-up to date.
-
-**How to confirm:**
-
-```bash
-dmesg -T | grep -i "out of memory"     # look for "Killed process ... (cc1plus)"
-free -h                                 # total RAM and swap
-```
-
-**Fix:**
-
-Current versions of the installer handle this automatically: they cap build
-parallelism based on available RAM and add a temporary swapfile for the build,
-removing it when the build finishes. If you are on an older checkout, or the
-temporary swapfile could not be created, either force a serial compile:
-
-```bash
-sudo ./first_time_install.sh --build-jobs 1
-```
-
-or add permanent swap and re-run the installer, which resumes at Step 6:
-
-```bash
-sudo apt install -y dphys-swapfile
-sudo sed -i 's/^#\?CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile
-sudo sed -i 's/^#\?CONF_MAXSWAP=.*/CONF_MAXSWAP=2048/' /etc/dphys-swapfile
-sudo dphys-swapfile swapoff && sudo dphys-swapfile setup && sudo dphys-swapfile swapon
-sudo ./first_time_install.sh
-```
-
-`CONF_MAXSWAP` matters: it defaults to 2048 and silently clamps `CONF_SWAPSIZE`,
-so setting only `CONF_SWAPSIZE` to a larger value has no effect.
-
-**Related:**
-
-- The installer needs roughly 3GB free on the card to place the swapfile. If
-  disk is tight it will say so and skip the swapfile: `sudo apt clean` first.
-- `sudo bash scripts/check_system_compatibility.sh` reports RAM and disk.
-- `sudo bash scripts/diagnose_dependencies.sh` dumps build-dependency state.
-
----
-
 ### Web Interface & Service Issues
 
 #### Service Not Running/Starting
@@ -330,8 +266,8 @@ sudo systemctl cat ledmatrix-web | grep User
 
 6. **Manually enable AP mode:**
    ```bash
-   # Via API (the WiFi blueprint is mounted under /api/v3)
-   curl -X POST http://localhost:5000/api/v3/wifi/ap/enable
+   # Via API
+   curl -X POST http://localhost:5000/api/wifi/ap/enable
 
    # Via Python
    python3 -c "
@@ -482,19 +418,19 @@ sudo systemctl cat ledmatrix-web | grep User
 
 1. **Check plugin directory exists:**
    ```bash
-   ls -ld plugin-repos/plugin-id/
+   ls -ld plugins/plugin-id/
    ```
 
 2. **Verify manifest.json:**
    ```bash
-   cat plugin-repos/plugin-id/manifest.json
+   cat plugins/plugin-id/manifest.json
    # Verify all required fields present
    ```
 
 3. **Check dependencies installed:**
    ```bash
-   if [ -f plugin-repos/plugin-id/requirements.txt ]; then
-     pip3 install --break-system-packages -r plugin-repos/plugin-id/requirements.txt
+   if [ -f plugins/plugin-id/requirements.txt ]; then
+     pip3 install --break-system-packages -r plugins/plugin-id/requirements.txt
    fi
    ```
 
@@ -507,7 +443,7 @@ sudo systemctl cat ledmatrix-web | grep User
    ```bash
    python3 -c "
    import sys
-   sys.path.insert(0, 'plugin-repos/plugin-id')
+   sys.path.insert(0, 'plugins/plugin-id')
    from manager import PluginClass
    print('Plugin imports successfully')
    "
@@ -523,18 +459,12 @@ sudo systemctl cat ledmatrix-web | grep User
 **Solutions:**
 
 1. **Manual cache clearing:**
-
-   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
+   # Remove plugin-specific cache
+   rm -rf cache/plugin-id*
 
-   # Or remove files manually from the cache dir in use, e.g.:
-   sudo rm -rf /var/cache/ledmatrix/*
+   # Or remove all cache
+   rm -rf cache/*
 
    # Restart display
    sudo systemctl restart ledmatrix
@@ -542,8 +472,8 @@ sudo systemctl cat ledmatrix-web | grep User
 
 2. **Check cache permissions:**
    ```bash
-   ls -ld /var/cache/ledmatrix
-   sudo ./scripts/fix_perms/fix_cache_permissions.sh
+   ls -ld cache/
+   sudo chown -R ledpi:ledpi cache/
    ```
 
 ---
@@ -778,11 +708,11 @@ nmcli device status
 ```bash
 # Check file exists
 ls -l config/config.json
-ls -l plugin-repos/plugin-id/manifest.json
+ls -l plugins/plugin-id/manifest.json
 
 # Check directory structure
 ls -la web_interface/
-ls -la plugin-repos/
+ls -la plugins/
 
 # Check file permissions
 ls -l config/config_secrets.json
@@ -810,7 +740,7 @@ python3 -c "from src.wifi_manager import WiFiManager; print('OK')"
 # Test plugin import
 python3 -c "
 import sys
-sys.path.insert(0, 'plugin-repos/plugin-id')
+sys.path.insert(0, 'plugins/plugin-id')
 from manager import PluginClass
 print('Plugin imports OK')
 "
@@ -818,28 +748,39 @@ print('Plugin imports OK')
 
 ---
 
-## Reinstalling Service Files
+## Service File Template
 
-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:
+If your systemd service file is corrupted or missing, use this template:
 
-```bash
-# Reinstall the display service unit
-sudo ./scripts/install/install_service.sh
+```ini
+[Unit]
+Description=LEDMatrix Web Interface
+After=network.target
 
-# Reinstall the web interface service unit
-sudo ./scripts/install/install_web_service.sh
+[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
 ```
 
-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.
+Save to `/etc/systemd/system/ledmatrix-web.service` and run:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable ledmatrix-web
+sudo systemctl start ledmatrix-web
+```
 
 ---
 
@@ -873,7 +814,7 @@ echo ""
 
 echo "5. File Structure:"
 ls -la web_interface/ | head -10
-ls -la plugin-repos/ | head -10
+ls -la plugins/ | head -10
 echo ""
 
 echo "6. Python Imports:"
@@ -949,11 +890,12 @@ sudo systemctl restart ledmatrix-web
 # Reinstall WiFi monitor
 sudo ./scripts/install/install_wifi_monitor.sh
 
-# Recreate service files (substitutes __PROJECT_ROOT_DIR__ in systemd/ units)
-sudo ./scripts/install/install_service.sh
-sudo ./scripts/install/install_web_service.sh
+# Recreate service files from templates
+sudo cp templates/ledmatrix.service /etc/systemd/system/
+sudo cp templates/ledmatrix-web.service /etc/systemd/system/
 
-# Restart
+# Reload and restart
+sudo systemctl daemon-reload
 sudo systemctl restart ledmatrix ledmatrix-web
 ```
 

docs/WEB_INTERFACE_GUIDE.md

@@ -39,18 +39,12 @@ present:
 - **WiFi** — Network selection and AP-mode setup
 - **Schedule** — Power and dim schedules
 - **Display** — Matrix hardware configuration (rows, cols, hardware
-  mapping, GPIO slowdown, brightness, PWM) and Vegas Scroll Mode
-  settings
-- **Rotation** — drag-and-drop **Rotation Order** list and per-plugin
-  **Screen Durations**
+  mapping, GPIO slowdown, brightness, PWM)
 - **Config Editor** — Raw `config.json` editor with validation
-- **Backup & Restore** — back up and restore your configuration
 - **Fonts** — Upload and manage fonts
 - **Logs** — Real-time log streaming
 - **Cache** — Cached data inspection and cleanup
 - **Operation History** — Recent service operations
-- **Tools** — system diagnostics, git & updates, Python dependencies,
-  maintenance, power supply, network radio, services, and plugin health
 
 A second nav row holds plugin tabs:
 
@@ -117,12 +111,6 @@ Configure your LED matrix hardware:
 - Dynamic Duration — global cap for plugins that extend their display
   time based on content
 
-**Vegas Scroll Mode:** the Display tab also has a full Vegas Scroll
-Mode section — enable toggle, scroll speed, separator width, dynamic
-duration, and related settings — so you can configure Vegas mode
-entirely from the web UI without hand-editing JSON. See
-[ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for what the options do.
-
 Changes require **Restart Display Service** from the Overview tab.
 
 ### Plugin Manager Tab
@@ -171,10 +159,9 @@ Manage fonts for your display:
 - See font previews
 - Check font sizes and styles
 
-**Font Overrides:**
-- Overrides are set per display *element* (e.g. a specific score or
-  clock text element), not per plugin
-- Override default font choices for individual elements
+**Plugin Font Overrides:**
+- Set custom fonts for specific plugins
+- Override default font choices
 - Preview font changes
 
 **Delete Fonts:**
@@ -196,11 +183,9 @@ View real-time system logs:
 - Filter by plugin or component
 
 **Actions:**
-- **Refresh**: Reload the log view
 - **Clear**: Clear the current view
 - **Download**: Download logs for offline analysis
-- **Auto-scroll** checkbox: toggle automatic scrolling to the latest
-  entries
+- **Pause**: Pause auto-scrolling
 
 ---
 
@@ -263,8 +248,7 @@ The web interface uses Server-Sent Events (SSE) for real-time updates:
 **Performance:**
 - Minimal bandwidth usage
 - Server-side rendering for fast load times
-- The UI is built on Alpine.js and HTMX, so JavaScript must be enabled
-  in the browser
+- Progressive enhancement - works without JavaScript
 
 ---
 
@@ -283,6 +267,17 @@ The interface is fully responsive and works on mobile devices:
 
 ---
 
+## Keyboard Shortcuts
+
+Use keyboard shortcuts for faster navigation:
+
+- **Tab**: Navigate between form fields
+- **Enter**: Submit forms
+- **Esc**: Close modals
+- **Ctrl+F**: Search in logs
+
+---
+
 ## API Access
 
 The web interface is built on a REST API that you can access programmatically:
@@ -293,7 +288,7 @@ http://your-pi-ip:5000/api/v3
 ```
 
 The API blueprint mounts at `/api/v3` (see
-`web_interface/app.py:199`). All endpoints below are relative to that
+`web_interface/app.py:144`). All endpoints below are relative to that
 base.
 
 **Common Endpoints:**

first_time_install.sh

@@ -152,8 +152,6 @@ ASSUME_YES=${LEDMATRIX_ASSUME_YES:-0}
 SKIP_SOUND=${LEDMATRIX_SKIP_SOUND:-0}
 SKIP_PERF=${LEDMATRIX_SKIP_PERF:-0}
 SKIP_REBOOT_PROMPT=${LEDMATRIX_SKIP_REBOOT_PROMPT:-0}
-SKIP_SWAP=${LEDMATRIX_SKIP_SWAP:-0}
-BUILD_JOBS_OVERRIDE=${LEDMATRIX_BUILD_JOBS:-}
 
 usage() {
     cat <<USAGE
@@ -165,21 +163,11 @@ Options:
       --skip-sound          Skip sound module configuration
       --skip-perf           Skip performance tweaks (isolcpus/audio)
       --no-reboot-prompt    Do not prompt for reboot at the end
-      --skip-swap           Never add temporary swap for the C++ build
-      --build-jobs N        Compile the C++ library with N parallel jobs
-                            (default: scaled to available RAM)
   -h, --help                Show this help message and exit
 
 Environment variables (same effect as flags):
   LEDMATRIX_ASSUME_YES=1, RPI_RGB_FORCE_REBUILD=1, LEDMATRIX_SKIP_SOUND=1,
-  LEDMATRIX_SKIP_PERF=1, LEDMATRIX_SKIP_REBOOT_PROMPT=1,
-  LEDMATRIX_SKIP_SWAP=1, LEDMATRIX_BUILD_JOBS=N
-
-Low-memory devices:
-  On a Pi with under 2GB of RAM the C++ build is limited to fewer parallel
-  jobs and a temporary swapfile is added for the duration of the build, then
-  removed. Without this the compiler is killed by the kernel out-of-memory
-  killer on 512MB and 1GB models.
+  LEDMATRIX_SKIP_PERF=1, LEDMATRIX_SKIP_REBOOT_PROMPT=1
 USAGE
 }
 
@@ -190,38 +178,12 @@ while [ $# -gt 0 ]; do
         --skip-sound) SKIP_SOUND=1 ;;
         --skip-perf) SKIP_PERF=1 ;;
         --no-reboot-prompt) SKIP_REBOOT_PROMPT=1 ;;
-        --skip-swap) SKIP_SWAP=1 ;;
-        --build-jobs)
-            shift
-            if [ $# -eq 0 ]; then echo "--build-jobs requires a number"; usage; exit 1; fi
-            BUILD_JOBS_OVERRIDE="$1"
-            ;;
         -h|--help) usage; exit 0 ;;
         *) echo "Unknown option: $1"; usage; exit 1 ;;
     esac
     shift
 done
 
-# Low-memory build helpers (job sizing, temporary swap, OOM detection).
-# Sourced rather than inlined so the sizing logic can be unit-tested; if the
-# file is missing we fall back to the historical behaviour rather than failing
-# the install.
-LOWMEM_LIB="$PROJECT_ROOT_DIR/scripts/install/lib_lowmem.sh"
-LOWMEM_AVAILABLE=0
-if [ -f "$LOWMEM_LIB" ]; then
-    # shellcheck source=scripts/install/lib_lowmem.sh
-    . "$LOWMEM_LIB"
-    LOWMEM_AVAILABLE=1
-else
-    echo "⚠ $LOWMEM_LIB not found; skipping low-memory build protections."
-    lm_remove_build_swap() { return 0; }
-fi
-
-# Remove the temporary build swapfile no matter how the script ends. Step 6
-# tears it down itself; this is the backstop for the error path, since
-# on_error ends in `exit` and EXIT traps still run.
-trap 'lm_remove_build_swap' EXIT
-
 # Helpers
 retry() {
     local attempt=1
@@ -301,144 +263,15 @@ check_disk_space() {
     fi
 }
 
-# Decide how much memory Step 6's C++ build may use, and say so up front.
-#
-# Sets TOTAL_RAM_MB, TOTAL_SWAP_MB, BUILD_JOBS and LOW_RAM for later steps.
-check_memory() {
-    command -v nproc >/dev/null 2>&1 && CPU_CORES=$(nproc) || CPU_CORES=1
-
-    # Validated up front rather than trusted: a non-numeric value would other-
-    # wise survive as far as an arithmetic test in Step 6 and fail there with a
-    # generic error. This must precede the fallback return below, which also
-    # honours the override.
-    if [ -n "$BUILD_JOBS_OVERRIDE" ]; then
-        if ! echo "$BUILD_JOBS_OVERRIDE" | grep -qE '^[1-9][0-9]*$'; then
-            echo "✗ Invalid build job count: '$BUILD_JOBS_OVERRIDE' (expected a positive integer)"
-            exit 1
-        fi
-    fi
-
-    if [ "$LOWMEM_AVAILABLE" != "1" ]; then
-        TOTAL_RAM_MB=0
-        TOTAL_SWAP_MB=0
-        LOW_RAM=0
-        BUILD_JOBS=${BUILD_JOBS_OVERRIDE:-$CPU_CORES}
-        return 0
-    fi
-
-    TOTAL_RAM_MB=$(lm_total_ram_mb)
-    TOTAL_SWAP_MB=$(lm_total_swap_mb)
-
-    # Test hook: exercise the low-memory path on a machine that has plenty.
-    if [ -n "${LEDMATRIX_FORCE_LOW_RAM:-}" ] && [ "${LEDMATRIX_FORCE_LOW_RAM}" != "0" ]; then
-        TOTAL_RAM_MB="${LEDMATRIX_FORCE_LOW_RAM}"
-        echo "⚠ LEDMATRIX_FORCE_LOW_RAM set: pretending this device has ${TOTAL_RAM_MB}MB of RAM"
-    fi
-
-    LOW_RAM=0
-    if [ "$TOTAL_RAM_MB" -gt 0 ] && [ "$TOTAL_RAM_MB" -lt 2048 ]; then
-        LOW_RAM=1
-    fi
-
-    if [ -n "$BUILD_JOBS_OVERRIDE" ]; then
-        BUILD_JOBS="$BUILD_JOBS_OVERRIDE"
-    else
-        BUILD_JOBS=$(lm_build_jobs "$TOTAL_RAM_MB" "$CPU_CORES")
-    fi
-
-    echo "System memory: ${TOTAL_RAM_MB}MB RAM, ${TOTAL_SWAP_MB}MB swap, ${CPU_CORES} core(s)"
-    if [ "$LOW_RAM" = "1" ]; then
-        echo "⚠ Low-memory device detected."
-        echo "  The rpi-rgb-led-matrix C++ build in Step 6 will use ${BUILD_JOBS} parallel job(s)"
-        echo "  instead of all cores, and a temporary swapfile will be added for the build"
-        echo "  and removed afterwards. Without this the compiler is killed by the kernel"
-        echo "  out-of-memory killer. Expect Step 6 to take 15-25 minutes."
-        if [ "$SKIP_SWAP" = "1" ]; then
-            echo "  Temporary swap is disabled (--skip-swap); the build may still run out of memory."
-        fi
-    else
-        echo "✓ Memory sufficient for the rpi-rgb-led-matrix build (${BUILD_JOBS} parallel job(s))"
-    fi
-}
-
-# Compile and install the rgbmatrix Python package.
-#
-# CMAKE_BUILD_PARALLEL_LEVEL is the setting that actually caps the compile:
-# upstream's pyproject.toml declares no [tool.scikit-build] options, so
-# scikit-build-core drives Ninja through `cmake --build`, which reads this
-# variable. Ninja's own default is nproc+2, i.e. six concurrent cc1plus
-# processes on a 4-core Pi. MAKEFLAGS is ignored by Ninja and is set only to
-# cover the Makefile-generator fallback if ninja-build is somehow absent.
-#
-# BUILD_TMPDIR redirects pip's build tree off tmpfs where applicable — see
-# where it is computed in Step 6.
-run_rgbmatrix_build() {
-    local jobs="$1" out="$2"
-    local pid elapsed=0
-
-    TMPDIR="${BUILD_TMPDIR:-${TMPDIR:-/tmp}}" \
-    CMAKE_BUILD_PARALLEL_LEVEL="$jobs" \
-    MAKEFLAGS="-j${jobs}" \
-        python3 -m pip install --break-system-packages . > "$out" 2>&1 &
-    pid=$!
-
-    # The build's output is captured to a file, so without a heartbeat a serial
-    # compile on a 1GB Pi looks like a 20-minute hang and invites a Ctrl-C.
-    #
-    # Polled at a short interval but reported every 30s: polling at the report
-    # interval instead would add most of that interval to the wall time of
-    # every build, including fast ones on a Pi 4/5.
-    while kill -0 "$pid" 2>/dev/null; do
-        sleep 2
-        elapsed=$((elapsed + 2))
-        if [ "$((elapsed % 30))" -eq 0 ] && kill -0 "$pid" 2>/dev/null; then
-            printf '  ... still compiling (%dm%02ds elapsed)\n' "$((elapsed / 60))" "$((elapsed % 60))"
-        fi
-    done
-
-    wait "$pid"
-}
-
-# Explain a failed rgbmatrix build. The kernel OOM killer writes nothing to the
-# build's own output, which is why this used to be reported as a missing
-# build-tools problem and sent users chasing packages they already had.
-print_rgbmatrix_build_failure() {
-    local out="$1"
-
-    if [ "$LOWMEM_AVAILABLE" = "1" ] && lm_build_failed_on_oom "$out"; then
-        echo "✗ The rpi-rgb-led-matrix build was killed: the system ran out of memory."
-        echo "  This is NOT a missing build-tools problem — the C++ compiler ran out of RAM."
-        echo "  RAM: ${TOTAL_RAM_MB}MB   Swap: $(lm_total_swap_mb)MB   Parallel jobs used: ${BUILD_JOBS}"
-        if [ -n "${LM_SWAP_SKIP_REASON:-}" ]; then
-            echo "  No temporary swap was added: ${LM_SWAP_SKIP_REASON}"
-        fi
-        echo ""
-        echo "  Try one of these, then re-run this script (it resumes at Step 6):"
-        echo "    1. Force a single compile job:"
-        echo "       sudo ./first_time_install.sh --build-jobs 1"
-        echo "    2. Add permanent swap, if the temporary swapfile could not be created:"
-        echo "       sudo apt install -y dphys-swapfile"
-        echo "       sudo sed -i 's/^#\\?CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile"
-        echo "       sudo sed -i 's/^#\\?CONF_MAXSWAP=.*/CONF_MAXSWAP=2048/' /etc/dphys-swapfile"
-        echo "       sudo dphys-swapfile swapoff && sudo dphys-swapfile setup && sudo dphys-swapfile swapon"
-        echo "    3. Free up disk space so a larger swapfile fits: sudo apt clean"
-    else
-        echo "✗ Failed to install rpi-rgb-led-matrix Python package"
-        echo "  Ensure build tools are installed:"
-        echo "  sudo apt install -y python-dev-is-python3 cmake build-essential"
-    fi
-}
-
 echo ""
 echo "This script will perform the following steps:"
-echo "1. Check prerequisites (network, disk, memory) and install system dependencies"
+echo "1. Install system dependencies"
 echo "2. Fix cache permissions"
 echo "3. Fix assets directory permissions"
 echo "3.1. Fix plugin directory permissions"
 echo "4. Ensure configuration files exist"
 echo "5. Install Python project dependencies (requirements.txt)"
 echo "6. Build and install rpi-rgb-led-matrix and test import"
-echo "   (compiles C++; low-memory Pis get temporary swap and a serial build)"
 echo "7. Install web interface dependencies"
 echo "7.5. Install main LED Matrix service"
 echo "8. Install web interface service"
@@ -482,16 +315,9 @@ echo "----------------------------------------"
 # Pre-flight checks before APT operations
 check_network
 check_disk_space
-check_memory
 
-# Update package list. The one-shot installer refreshes the lists moments
-# before invoking this script and exports LEDMATRIX_APT_UPDATED=1, so skip the
-# duplicate refresh on that path.
-if [ "${LEDMATRIX_APT_UPDATED:-0}" = "1" ]; then
-    echo "Package lists already refreshed by the one-shot installer; skipping apt update."
-else
-    apt_update
-fi
+# Update package list
+apt_update
 
 # Install required system packages
 echo "Installing Python packages and dependencies..."
@@ -821,6 +647,10 @@ if [ ! -f "$PROJECT_ROOT_DIR/config/config_secrets.json" ]; then
         echo "⚠ Template config/config_secrets.template.json not found; creating a minimal secrets file"
         cat > "$PROJECT_ROOT_DIR/config/config_secrets.json" <<'EOF'
 {
+    "youtube": {
+        "api_key": "YOUR_YOUTUBE_API_KEY",
+        "channel_id": "YOUR_YOUTUBE_CHANNEL_ID"
+    },
     "github": {
         "api_token": "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
     }
@@ -1072,66 +902,29 @@ else
             fi
         fi
 
-        # Add temporary swap on low-memory devices so the compiler survives.
-        CURRENT_STEP="Prepare the low-memory build environment"
-        if [ "$LOWMEM_AVAILABLE" = "1" ] && [ "$SKIP_SWAP" != "1" ]; then
-            lm_ensure_build_swap "$(lm_swap_needed_mb "$TOTAL_RAM_MB" "$TOTAL_SWAP_MB")"
-        elif [ "$SKIP_SWAP" = "1" ]; then
-            LM_SWAP_SKIP_REASON="disabled with --skip-swap"
-        fi
-
-        # pip builds in $TMPDIR. Debian 13 mounts /tmp as tmpfs, so the default
-        # would hold the entire C++ build tree in RAM — competing with the very
-        # compiler we are trying to keep under the memory limit.
-        BUILD_TMPDIR=""
-        if [ "$LOWMEM_AVAILABLE" = "1" ]; then
-            _disk_tmp=$(lm_disk_backed_tmpdir)
-            if [ -n "$_disk_tmp" ]; then
-                BUILD_TMPDIR="$_disk_tmp/ledmatrix-build"
-                # If this fails (a nearly-full disk being the likely cause on
-                # exactly the devices this targets), fall back to the default
-                # rather than pointing the build at a path that does not exist.
-                if mkdir -p "$BUILD_TMPDIR" 2>/dev/null; then
-                    echo "Building in $BUILD_TMPDIR (TMPDIR is memory-backed; keeping the build tree on disk)"
-                else
-                    echo "⚠ Could not create $BUILD_TMPDIR; falling back to the default TMPDIR"
-                    BUILD_TMPDIR=""
-                fi
-            fi
-        fi
-
-        CURRENT_STEP="Build and install rpi-rgb-led-matrix"
         pushd "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" >/dev/null
         echo "Installing rpi-rgb-led-matrix Python package (scikit-build-core + cmake)..."
         echo "  Build deps required: python-dev-is-python3 cmake"
-        echo "  Compiling C++ with ${BUILD_JOBS} parallel job(s)..."
-        if [ "$BUILD_JOBS" -le 1 ]; then
-            echo "  Deliberately serial to stay within this device's memory — expect 15-25 minutes."
-        else
-            echo "  This may take 2-5 minutes on a Pi 4/5..."
-        fi
+        echo "  This compiles C++ — may take 2-5 minutes on Pi 4/5..."
         BUILD_OUTPUT=$(mktemp)
         BUILD_SUCCESS=false
-        if run_rgbmatrix_build "$BUILD_JOBS" "$BUILD_OUTPUT"; then
+        if python3 -m pip install --break-system-packages . > "$BUILD_OUTPUT" 2>&1; then
             BUILD_SUCCESS=true
         fi
         cat "$BUILD_OUTPUT" >> "$LOG_FILE"
         if [ "$BUILD_SUCCESS" != true ]; then
-            print_rgbmatrix_build_failure "$BUILD_OUTPUT"
+            echo "✗ Failed to install rpi-rgb-led-matrix Python package"
+            echo "  Ensure build tools are installed:"
+            echo "  sudo apt install -y python-dev-is-python3 cmake build-essential"
             echo ""
             echo "-- Last 50 lines of build output --"
             tail -n 50 "$BUILD_OUTPUT"
             rm -f "$BUILD_OUTPUT"
-            if [ -n "$BUILD_TMPDIR" ]; then rm -rf "$BUILD_TMPDIR"; fi
             popd >/dev/null
-            lm_remove_build_swap
             exit 1
         fi
         rm -f "$BUILD_OUTPUT"
-        if [ -n "$BUILD_TMPDIR" ]; then rm -rf "$BUILD_TMPDIR"; fi
         popd >/dev/null
-        # Hand the memory back well before Step 14's reboot.
-        lm_remove_build_swap
     else
         echo "✗ rpi-rgb-led-matrix-master directory not found at $PROJECT_ROOT_DIR"
         echo "Failed to initialize submodule or clone repository"
@@ -1189,7 +982,14 @@ else
         # real time and in order relative to this script's own echo statements
         python3 -u "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py"
     else
-        echo "Web dependencies already installed from web_interface/requirements.txt in Step 5"
+        echo "Using pip to install dependencies..."
+        if [ -f "$PROJECT_ROOT_DIR/requirements_web_v2.txt" ]; then
+            # --ignore-installed: see the Step 5 web_interface/requirements.txt
+            # install above — same apt/pip RECORD-file conflict applies here.
+            python3 -m pip install --break-system-packages --prefer-binary --ignore-installed -r requirements_web_v2.txt
+        else
+            echo "⚠ requirements_web_v2.txt not found; skipping web dependency install"
+        fi
     fi
 
     # Create marker file to indicate dependencies are installed

requirements-test.txt

@@ -1,7 +1,9 @@
-# Test/dev-only dependencies (not needed on a running display).
+# Test-only dependencies for the plugin safety harness and pytest suite.
 # Install alongside requirements.txt:  pip install -r requirements.txt -r requirements-test.txt
-pytest>=9.0.3,<10.0.0
-pytest-cov>=4.1.0,<5.0.0
-pytest-mock>=3.11.0,<4.0.0
+#
+# pytest, pytest-cov, pytest-mock, and jsonschema are already pinned (with
+# major-version caps) in requirements.txt, so they are intentionally NOT
+# repeated here — re-pinning pytest to <9 collided with requirements.txt's
+# pytest>=9.0.3,<10 and made the two files impossible to install together.
+# Only declare what requirements.txt doesn't already provide.
 freezegun>=1.2,<2        # deterministic time for golden-image tests
-mypy>=1.5.0,<2.0.0       # static type checking (also pinned in .pre-commit-config.yaml)

requirements.txt

@@ -11,22 +11,27 @@ pytz>=2024.2,<2025.0  # Updated for latest timezone data
 
 # HTTP requests
 requests>=2.33.0,<3.0.0
-urllib3>=1.26.0,<3.0.0  # requests transitive, but imported directly (urllib3.util.retry.Retry)
 
 # Google API integration
 
 # Font rendering
 freetype-py>=2.5.1,<3.0.0
 
-# Spotify integration (used by web_interface/blueprints/api_v3.py OAuth endpoints)
+# Spotify integration
 spotipy>=2.25.2,<3.0.0
 
 # Flask web framework
 Flask>=3.1.3,<4.0.0
 
-# WebSocket support: intentionally NOT declared here. Plugins that need
-# it (e.g. ledmatrix-music's Socket.IO client) declare it in their own
-# requirements.txt, which the plugin store installs.
+# Text processing
+
+# Calendar integration
+
+# WebSocket support
+python-socketio>=5.14.0,<6.0.0
+python-engineio>=4.9.0,<5.0.0
+websockets>=12.0,<14.0
+websocket-client>=1.8.0,<2.0.0
 
 # JSON Schema validation
 jsonschema>=4.20.0,<5.0.0
@@ -34,8 +39,11 @@ jsonschema>=4.20.0,<5.0.0
 # Requirement specifier parsing (plugin dependency satisfaction checks)
 packaging>=23.0,<27.0
 
-# Testing dependencies live in requirements-test.txt:
-#   pip install -r requirements.txt -r requirements-test.txt
+# Testing dependencies
+pytest>=9.0.3,<10.0.0
+pytest-cov>=4.1.0,<5.0.0
+pytest-mock>=3.11.0,<4.0.0
+mypy>=1.5.0,<2.0.0
 
 # ───────────────────────────────────────────────────────────────────────
 # Optional dependencies — the code imports these inside try/except
@@ -51,9 +59,7 @@ packaging>=23.0,<27.0
 # psutil            — per-plugin resource monitoring in
 #                     src/plugin_system/resource_monitor.py. The monitor
 #                     silently no-ops when missing (PSUTIL_AVAILABLE = False).
-#                     Note: web_interface/requirements.txt requires this
-#                     range as a hard dependency — keep the two in sync.
-#   pip install 'psutil>=6.0.0,<7.0.0'
+#   pip install 'psutil>=5.9.0,<6.0.0'
 #
 # Flask-Limiter     — request rate limiting in web_interface/app.py
 #                     (accidental-abuse protection, not security). The

scripts/add_defaults_to_schemas.py

@@ -201,7 +201,7 @@ def process_schema_file(schema_path: Path) -> bool:
 def main():
     """Main entry point."""
     project_root = Path(__file__).parent.parent
-    plugins_dir = project_root / 'plugin-repos'
+    plugins_dir = project_root / 'plugins'
     
     if not plugins_dir.exists():
         print(f"Error: Plugins directory not found: {plugins_dir}")

scripts/analyze_plugin_schemas.py

@@ -193,7 +193,7 @@ def analyze_schema(schema_path: Path) -> Dict[str, Any]:
 def main():
     """Main analysis function."""
     project_root = Path(__file__).parent.parent
-    plugins_dir = project_root / "plugin-repos"
+    plugins_dir = project_root / "plugins"
     
     if not plugins_dir.exists():
         print(f"Plugins directory not found: {plugins_dir}")

scripts/check_release_version.py

@@ -1,122 +0,0 @@
-#!/usr/bin/env python3
-"""Assert that a release tag, the CHANGELOG, and `src.__version__` all agree.
-
-Run it *before* creating a tag to check yourself:
-
-    python scripts/check_release_version.py v3.2.0
-
-Wiring it into CI (on pushed `v*` tags and published releases) is a follow-up
-PR, so for now it is a manual pre-flight: run it before creating the tag and a
-mismatch shows up here rather than as a silent wrong answer on user devices.
-
-Why this exists: `v3.1.0` was tagged 2026-05-31 while `src/__init__.py` still
-said `"1.0.0"`; the bump to `"3.1.0"` did not land until 2026-07-12. Devices
-installed from that release report `1.0.0`, which is below the `(2, 0, 0)` floor
-in `PluginLoader._warn_if_incompatible`, so they are silently exempt from every
-plugin compatibility warning. Plugin `ledmatrix_min_version` floors are only as
-trustworthy as this agreement. See `docs/SPORTS_UNIFICATION.md`, phase B4.
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-sys.path.insert(0, str(REPO_ROOT))
-
-# [0-9] rather than \d, and [ \t] rather than \s: \d also matches non-ASCII
-# decimal digits (which int() parses), and \s matches newlines, so "##\n3.2.0"
-# would otherwise read as a version heading. Keep these in step with
-# test/test_version_consistency.py.
-SEMVER = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
-HEADING = re.compile(
-    r"^##[ \t]+(?P<version>[0-9]+\.[0-9]+\.[0-9]+)[ \t]*$", re.MULTILINE)
-
-
-def normalize(tag: str) -> str:
-    """`v3.2.0` and `3.2.0` are the same release; tags here carry the `v`."""
-    return tag[1:] if tag.startswith("v") else tag
-
-
-def newest_changelog_version(changelog: Path) -> str | None:
-    """Newest version heading, or None when there is none.
-
-    Raises OSError if the file cannot be read; main() turns that into a clear
-    message rather than a traceback, because this runs as a release gate and a
-    traceback there reads as "the tooling is broken", not "your CHANGELOG is
-    missing".
-    """
-    headings = HEADING.findall(changelog.read_text(encoding="utf-8"))
-    return headings[0] if headings else None
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "tag",
-        help="Release tag to check, with or without the leading 'v' (e.g. v3.2.0)",
-    )
-    args = parser.parse_args()
-
-    from src import __version__ as core_version
-
-    tag_version = normalize(args.tag)
-    changelog_path = REPO_ROOT / "CHANGELOG.md"
-
-    problems: list[str] = []
-
-    try:
-        changelog_version = newest_changelog_version(changelog_path)
-    except OSError as e:
-        print(
-            f"Release version check FAILED for tag {args.tag}:\n"
-            f"  - could not read {changelog_path}: {e}\n"
-            f"    Restore the file (git checkout -- CHANGELOG.md) and re-run.",
-            file=sys.stderr,
-        )
-        return 1
-
-    if not SEMVER.match(tag_version):
-        problems.append(
-            f"tag {args.tag!r} is not vX.Y.Z. Older tags (v2.5) predate this "
-            "check; new releases must be full semver so floors can parse them."
-        )
-
-    if not SEMVER.match(core_version):
-        problems.append(f"src.__version__ is {core_version!r}, which is not X.Y.Z")
-
-    if tag_version != core_version:
-        problems.append(
-            f"tag says {tag_version} but src.__version__ says {core_version}. "
-            "Bump src/__init__.py to match the tag before releasing — devices "
-            "report __version__, not the tag, and plugin floors compare "
-            "against it."
-        )
-
-    if changelog_version is None:
-        problems.append("CHANGELOG.md has no '## X.Y.Z' version heading")
-    elif changelog_version != core_version:
-        problems.append(
-            f"CHANGELOG.md's newest heading is {changelog_version} but "
-            f"src.__version__ is {core_version}. Plugin authors read the "
-            "CHANGELOG to pick a ledmatrix_min_version floor."
-        )
-
-    if problems:
-        print(f"Release version check FAILED for tag {args.tag}:", file=sys.stderr)
-        for problem in problems:
-            print(f"  - {problem}", file=sys.stderr)
-        return 1
-
-    print(
-        f"OK: tag {args.tag}, src.__version__ {core_version}, and the CHANGELOG "
-        "all agree."
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/debug/check_imports.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""
+Check what imports are actually in the app.py file on the Pi
+"""
+
+from pathlib import Path
+
+# Read the app.py file and check the import lines
+app_py_path = Path.home() / 'LEDMatrix' / 'web_interface' / 'app.py'
+
+print(f"🔍 Checking imports in: {app_py_path}")
+print(f"📁 File exists: {app_py_path.exists()}")
+
+if app_py_path.exists():
+    with open(app_py_path, 'r') as f:
+        lines = f.readlines()
+
+    print("\n🔍 Import lines in app.py:")
+    for i, line in enumerate(lines, 1):
+        if 'from' in line and 'blueprints' in line and 'import' in line:
+            print(f"  Line {i}: {line.strip()}")
+
+    print("\n🔍 Blueprint registration lines:")
+    for i, line in enumerate(lines, 1):
+        if 'register_blueprint' in line:
+            print(f"  Line {i}: {line.strip()}")
+else:
+    print("❌ app.py file not found!")

scripts/debug/debug_web_manual.py

@@ -13,8 +13,8 @@ def main():
     print("🔍 LED Matrix Web Interface Debug Tool")
     print("=" * 50)
 
-    # Change to project root (two levels up from scripts/debug/)
-    project_root = Path(__file__).parent.parent.parent.resolve()
+    # Change to project root (where this script is located)
+    project_root = Path(__file__).parent.resolve()
     os.chdir(project_root)
     print(f"📁 Working directory: {os.getcwd()}")
 

scripts/debug/direct_fix_imports.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""
+Direct fix for import issues - manually edit the app.py file
+"""
+
+import os
+from pathlib import Path
+
+def fix_imports():
+    app_py_path = Path.home() / 'LEDMatrix' / 'web_interface' / 'app.py'
+
+    print(f"🔧 Directly fixing imports in: {app_py_path}")
+
+    # Read the file
+    with open(app_py_path, 'r') as f:
+        lines = f.readlines()
+
+    # Find and fix the import lines
+    fixed = False
+    for i, line in enumerate(lines, 1):
+        if 'from blueprints.pages_v3 import' in line:
+            lines[i-1] = "from web_interface.blueprints.pages_v3 import pages_v3\n"
+            print(f"✅ Fixed line {i}: from blueprints.pages_v3 import → from web_interface.blueprints.pages_v3 import")
+            fixed = True
+        elif 'from blueprints.api_v3 import' in line:
+            lines[i-1] = "from web_interface.blueprints.api_v3 import api_v3\n"
+            print(f"✅ Fixed line {i}: from blueprints.api_v3 import → from web_interface.blueprints.api_v3 import")
+            fixed = True
+
+    if not fixed:
+        print("❌ No import lines found to fix")
+        return False
+
+    # Write the fixed file back
+    with open(app_py_path, 'w') as f:
+        f.writelines(lines)
+
+    print("✅ File updated successfully")
+    return True
+
+def verify_fix():
+    print("\n🔍 Verifying the fix...")
+    os.system("python3 check_imports.py")
+
+if __name__ == "__main__":
+    if fix_imports():
+        print("\n🧹 Clearing Python cache...")
+        os.system("find ~/LEDMatrix -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true")
+        os.system("find ~/LEDMatrix -name '*.pyc' -delete 2>/dev/null || true")
+
+        print("\n✅ Imports fixed and cache cleared!")
+        verify_fix()
+
+        print("\n🚀 Now try running the web interface:")
+        print("cd ~/LEDMatrix")
+        print("python3 web_interface/start.py")
+    else:
+        print("\n❌ Fix failed")

scripts/dev/vegas_audit.py

@@ -1,384 +0,0 @@
-#!/usr/bin/env python3
-"""
-Vegas Mode Density Audit
-
-Reports how much of the Vegas ticker is actually showing something. Loads the
-real enabled plugins, pulls each one's content through the real
-``PluginAdapter``, composes the strip through the real ``ScrollHelper``, then
-measures the result.
-
-The headline number is the **dead-frame ratio**: the fraction of viewport
-positions across a full cycle that are effectively blank. Because the panel
-only ever shows ``display_width`` columns at a time, a blank stretch wider than
-the viewport is a stretch where the display looks switched off — so this ratio
-tracks perceived dead time rather than just counting unlit pixels.
-
-Runs entirely off-hardware, so it is safe to run alongside a live display.
-
-Usage:
-    # Audit every enabled plugin at the display size from config.json
-    python scripts/dev/vegas_audit.py
-
-    # Specific plugins, dump each segment as a PNG for eyeballing
-    python scripts/dev/vegas_audit.py -p of-the-day,youtube-stats --dump-dir /tmp/vg
-
-    # Machine-readable, for before/after comparison
-    python scripts/dev/vegas_audit.py --json > after.json
-"""
-
-import argparse
-import json
-import logging
-import os
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, List
-
-PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT))
-
-# Must precede any src import that may reach for hardware.
-os.environ.setdefault('EMULATOR', 'true')
-
-from PIL import Image  # noqa: E402
-
-from src.common.scroll_helper import ScrollHelper  # noqa: E402
-from src.plugin_system.testing.loading import (  # noqa: E402
-    build_full_config,
-    find_plugin_dir,
-    load_manifest,
-)
-from src.vegas_mode.config import VegasModeConfig  # noqa: E402
-from src.vegas_mode.geometry import (  # noqa: E402
-    DEFAULT_INK_THRESHOLD,
-    column_has_ink,
-    content_bounds,
-    dead_window_stats,
-    window_coverage_stats,
-)
-from src.vegas_mode.plugin_adapter import PluginAdapter  # noqa: E402
-
-# Sampling stride for the dead-window scan. A full cycle can be 30,000px wide;
-# 4px granularity keeps the scan instant while staying well under the ~10px a
-# single scroll step ever covers, so no dead stretch is missed.
-DEAD_SCAN_STEP = 4
-
-
-def load_main_config(path: Path) -> Dict[str, Any]:
-    with open(path, 'r') as fh:
-        return json.load(fh)
-
-
-def display_size_from_config(config: Dict[str, Any]) -> tuple:
-    """Derive the logical ticker size the way DisplayManager does."""
-    hw = config.get('display', {}).get('hardware', {})
-    cols = int(hw.get('cols', 64))
-    chain = int(hw.get('chain_length', 1))
-    rows = int(hw.get('rows', 32))
-    parallel = int(hw.get('parallel', 1))
-    return cols * chain, rows * parallel
-
-
-def enabled_plugin_ids(config: Dict[str, Any]) -> List[str]:
-    """Plugin IDs that are enabled in config, excluding non-plugin sections."""
-    ids = []
-    for key, value in config.items():
-        if isinstance(value, dict) and value.get('enabled') is True:
-            ids.append(key)
-    return ids
-
-
-def instantiate(plugin_id: str, display_manager, cache_manager, plugin_manager):
-    """Load one plugin offline. Returns the instance or None."""
-    from src.plugin_system.plugin_loader import PluginLoader
-
-    search_dirs = [
-        str(PROJECT_ROOT / 'plugin-repos'),
-        str(PROJECT_ROOT / 'plugins'),
-    ]
-    plugin_dir = find_plugin_dir(plugin_id, search_dirs)
-    if not plugin_dir:
-        return None
-
-    try:
-        manifest = load_manifest(Path(plugin_dir))
-        cfg = build_full_config(Path(plugin_dir))
-        instance, _ = PluginLoader().load_plugin(
-            plugin_id=plugin_id,
-            manifest=manifest,
-            plugin_dir=Path(plugin_dir),
-            config=cfg,
-            display_manager=display_manager,
-            cache_manager=cache_manager,
-            plugin_manager=plugin_manager,
-            install_deps=False,
-        )
-        return instance
-    except Exception as exc:  # noqa: BLE001 - audit tool must survive any plugin
-        print(f"  ! {plugin_id}: load failed ({type(exc).__name__}: {exc})",
-              file=sys.stderr)
-        return None
-
-
-def join_rows(images: List[Image.Image], gap: int) -> Image.Image:
-    """Concatenate one plugin's rows, matching RenderPipeline._join_plugin_rows."""
-    if len(images) == 1:
-        return images[0]
-    gap = max(0, gap)
-    width = sum(img.width for img in images) + gap * (len(images) - 1)
-    height = max(img.height for img in images)
-    block = Image.new('RGB', (width, height), (0, 0, 0))
-    x = 0
-    for img in images:
-        block.paste(img, (x, 0))
-        x += img.width + gap
-    return block
-
-
-def measure_segment(images: List[Image.Image], display_width: int,
-                    scroll_speed: float, threshold: int) -> Dict[str, Any]:
-    """Geometry of one plugin's contribution to the ticker."""
-    total_width = sum(img.width for img in images)
-    combined = Image.new('RGB', (max(1, total_width), images[0].height))
-    x = 0
-    for img in images:
-        combined.paste(img, (x, 0))
-        x += img.width
-
-    ink = column_has_ink(combined, threshold)
-    bounds = content_bounds(combined, threshold)
-    ink_cols = int(ink.sum())
-
-    return {
-        'images': len(images),
-        'width_px': total_width,
-        'ink_cols': ink_cols,
-        'ink_pct': round(100.0 * ink_cols / total_width, 1) if total_width else 0.0,
-        'lead_black_px': bounds[0] if bounds else total_width,
-        'trail_black_px': (total_width - 1 - bounds[1]) if bounds else 0,
-        'seconds_on_screen': round(total_width / scroll_speed, 1) if scroll_speed else 0.0,
-        'widths': [img.width for img in images],
-    }
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description='Audit Vegas mode content density')
-    parser.add_argument('--config', default=str(PROJECT_ROOT / 'config' / 'config.json'),
-                        help='Path to main config.json')
-    parser.add_argument('-p', '--plugins', default=None,
-                        help='Comma-separated plugin IDs (default: all enabled)')
-    parser.add_argument('--width', type=int, default=None,
-                        help='Override display width (default: from config hardware)')
-    parser.add_argument('--height', type=int, default=None,
-                        help='Override display height (default: from config hardware)')
-    parser.add_argument('--dump-dir', default=None,
-                        help='Write each segment and the composed strip as PNGs here')
-    parser.add_argument('--threshold', type=int, default=DEFAULT_INK_THRESHOLD,
-                        help=f'Ink threshold (default: {DEFAULT_INK_THRESHOLD})')
-    parser.add_argument('--per-cycle', type=int, default=None,
-                        help='Plugins composed per cycle '
-                             '(default: buffer_ahead + 1, matching production)')
-    parser.add_argument('--json', action='store_true',
-                        help='Emit JSON instead of a text report')
-    args = parser.parse_args()
-
-    config = load_main_config(Path(args.config))
-    vegas = VegasModeConfig.from_config(config)
-
-    cfg_w, cfg_h = display_size_from_config(config)
-    width = args.width or cfg_w
-    height = args.height or cfg_h
-    speed = vegas.scroll_speed
-
-    if args.plugins:
-        plugin_ids = [p.strip() for p in args.plugins.split(',') if p.strip()]
-    else:
-        plugin_ids = vegas.get_ordered_plugins(enabled_plugin_ids(config))
-
-    dump_dir = Path(args.dump_dir) if args.dump_dir else None
-    if dump_dir:
-        dump_dir.mkdir(parents=True, exist_ok=True)
-
-    from src.plugin_system.testing import (
-        MockCacheManager, MockPluginManager, VisualTestDisplayManager,
-    )
-
-    display_manager = VisualTestDisplayManager(width=width, height=height)
-    cache_manager = MockCacheManager()
-    plugin_manager = MockPluginManager()
-    # Pass the loaded config, exactly as VegasModeCoordinator does. Omitting it
-    # makes PluginAdapter fall back to VegasModeConfig() defaults, so the audit
-    # would silently report trimming and width-budget behaviour that differs
-    # from the user's config.json — the same drift the lead_gap and grouping
-    # arguments below exist to avoid.
-    adapter = PluginAdapter(display_manager, vegas)
-
-    if not args.json:
-        print(f"Vegas audit — display {width}x{height}, scroll {speed:g}px/s, "
-              f"separator {vegas.separator_width}px")
-        print(f"One display width = {width / speed:.1f}s of screen time\n")
-
-    results: List[Dict[str, Any]] = []
-    segments: List[Image.Image] = []
-
-    for plugin_id in plugin_ids:
-        started = time.time()
-        instance = instantiate(plugin_id, display_manager, cache_manager, plugin_manager)
-        if instance is None:
-            results.append({'plugin': plugin_id, 'status': 'load_failed'})
-            continue
-
-        plugin_manager.plugins[plugin_id] = instance
-        adapter.invalidate_cache(plugin_id)
-
-        try:
-            images = adapter.get_content(instance, plugin_id)
-        except Exception as exc:  # noqa: BLE001
-            results.append({'plugin': plugin_id, 'status': 'fetch_error',
-                            'error': f'{type(exc).__name__}: {exc}'})
-            continue
-
-        fetch_ms = round((time.time() - started) * 1000)
-
-        if not images:
-            results.append({'plugin': plugin_id, 'status': 'no_content',
-                            'fetch_ms': fetch_ms})
-            if not args.json:
-                print(f"  {plugin_id:28s} NO CONTENT            ({fetch_ms}ms)")
-            continue
-
-        entry = {'plugin': plugin_id, 'status': 'ok', 'fetch_ms': fetch_ms}
-        entry.update(measure_segment(images, width, speed, args.threshold))
-        results.append(entry)
-        segments.extend(images)
-
-        if dump_dir:
-            for idx, img in enumerate(images):
-                img.save(dump_dir / f"{plugin_id}__{idx:02d}.png")
-
-        if not args.json:
-            print(f"  {plugin_id:28s} {entry['width_px']:>6d}px  "
-                  f"{entry['images']:>2d} img  ink {entry['ink_pct']:>5.1f}%  "
-                  f"lead {entry['lead_black_px']:>4d}  tail {entry['trail_black_px']:>4d}  "
-                  f"{entry['seconds_on_screen']:>6.1f}s  ({fetch_ms}ms)")
-
-    summary: Dict[str, Any] = {
-        'display_width': width,
-        'display_height': height,
-        'scroll_speed': speed,
-        'separator_width': vegas.separator_width,
-        'plugins_audited': len(plugin_ids),
-        'plugins_with_content': sum(1 for r in results if r.get('status') == 'ok'),
-    }
-
-    # Production composes only the plugins sitting in the active buffer, so
-    # measuring one giant strip of every plugin would hide the per-cycle costs
-    # (most importantly the leading gap, which is charged once per cycle).
-    # Group the segments the way the running service does.
-    per_cycle = max(1, args.per_cycle or vegas.plugins_per_cycle)
-
-    cycles: List[Dict[str, Any]] = []
-    with_content = [r for r in results if r.get('status') == 'ok']
-
-    if segments:
-        logger = logging.getLogger('vegas_audit')
-        seg_index = 0
-        for start in range(0, len(with_content), per_cycle):
-            group = with_content[start:start + per_cycle]
-
-            # Mirror RenderPipeline: each plugin's rows are joined by
-            # intra_plugin_gap into one block, and separator_width is applied
-            # only between blocks. Measuring a flat list here would report gaps
-            # the service does not emit.
-            blocks: List[Image.Image] = []
-            for entry in group:
-                count = entry['images']
-                rows = segments[seg_index:seg_index + count]
-                seg_index += count
-                if rows:
-                    blocks.append(join_rows(rows, vegas.intra_plugin_gap))
-            if not blocks:
-                continue
-
-            # ScrollHelper logs unconditionally, so it needs a real logger.
-            helper = ScrollHelper(width, height, logger)
-            helper.create_scrolling_image(
-                content_items=blocks,
-                item_gap=vegas.separator_width,
-                element_gap=0,
-                # Must match RenderPipeline. Omitting this made the audit
-                # measure a full-display-width leading gap the service no
-                # longer emits, overstating dead space by 512px per cycle.
-                lead_gap=vegas.lead_in_width,
-            )
-            composed = helper.cached_image
-            if composed is None:
-                continue
-
-            dead = dead_window_stats(composed, width, args.threshold, step=DEAD_SCAN_STEP)
-            cover = window_coverage_stats(
-                composed, width, args.threshold, step=DEAD_SCAN_STEP)
-
-            if dump_dir:
-                composed.save(dump_dir / f"_cycle{len(cycles):02d}.png")
-
-            cycles.append({
-                'plugins': [e['plugin'] for e in group],
-                'width_px': composed.width,
-                'seconds': round(composed.width / speed, 1) if speed else 0.0,
-                'dead_pct': round(100 * dead.dead_ratio, 1),
-                'longest_dead_seconds': round(
-                    dead.longest_dead_run * DEAD_SCAN_STEP / speed, 1) if speed else 0.0,
-                'mean_ink_pct': round(100 * cover.mean_ink_ratio, 1),
-                'sparse_pct': round(100 * cover.sparse_ratio, 1),
-                'longest_sparse_seconds': round(
-                    cover.longest_sparse_run * DEAD_SCAN_STEP / speed, 1) if speed else 0.0,
-            })
-
-    if cycles:
-        total_px = sum(c['width_px'] for c in cycles)
-        # Weight each cycle by its width so a long cycle counts proportionally.
-        summary.update({
-            'cycles': len(cycles),
-            'total_px': total_px,
-            'full_rotation_seconds': round(total_px / speed, 1) if speed else 0.0,
-            'dead_pct': round(
-                sum(c['dead_pct'] * c['width_px'] for c in cycles) / total_px, 1),
-            'mean_ink_pct': round(
-                sum(c['mean_ink_pct'] * c['width_px'] for c in cycles) / total_px, 1),
-            'sparse_pct': round(
-                sum(c['sparse_pct'] * c['width_px'] for c in cycles) / total_px, 1),
-            'worst_dead_seconds': max(c['longest_dead_seconds'] for c in cycles),
-            'worst_sparse_seconds': max(c['longest_sparse_seconds'] for c in cycles),
-        })
-
-    if args.json:
-        print(json.dumps({'summary': summary, 'cycles': cycles, 'plugins': results},
-                         indent=2))
-    else:
-        print(f"\n  Cycles ({per_cycle} plugins each, as production composes them):")
-        for idx, cyc in enumerate(cycles):
-            print(f"    [{idx}] {cyc['width_px']:>6d}px {cyc['seconds']:>6.1f}s  "
-                  f"ink {cyc['mean_ink_pct']:>5.1f}%  blank {cyc['dead_pct']:>5.1f}%  "
-                  f"worst blank {cyc['longest_dead_seconds']:>5.1f}s  "
-                  f"| {', '.join(cyc['plugins'])}")
-
-        print(f"\n  {'-' * 66}")
-        print(f"  full rotation        {summary.get('full_rotation_seconds', 0):>7.1f}s "
-              f"over {summary.get('cycles', 0)} cycles")
-        print(f"  mean ink coverage    {summary.get('mean_ink_pct', 0):>7.1f}%  "
-              f"(higher is better; target >25%)")
-        print(f"  fully blank          {summary.get('dead_pct', 0):>7.1f}%  (target <2%)")
-        print(f"  reads as empty       {summary.get('sparse_pct', 0):>7.1f}%  (target <15%)")
-        print(f"  worst blank stretch  {summary.get('worst_dead_seconds', 0):>7.1f}s  "
-              f"(target <1.5s)")
-        print(f"  plugins w/ content   {summary.get('plugins_with_content', 0):>7d}"
-              f" of {summary['plugins_audited']}")
-
-    return 0
-
-
-if __name__ == '__main__':
-    raise SystemExit(main())

scripts/diagnose_dependencies.sh

@@ -156,13 +156,9 @@ echo ""
 echo "6. Check disk space - building packages requires temporary space"
 echo "   df -h"
 echo ""
-echo "7. For slow builds or out-of-memory kills, increase swap space."
-echo "   first_time_install.sh already adds temporary swap on low-memory devices;"
-echo "   this makes it permanent. Set CONF_MAXSWAP too - it defaults to 2048 and"
-echo "   silently clamps CONF_SWAPSIZE, so raising CONF_SWAPSIZE alone does nothing."
+echo "7. For slow builds, increase swap space:"
 echo "   sudo dphys-swapfile swapoff"
-echo "   sudo sed -i 's/^#\\?CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile"
-echo "   sudo sed -i 's/^#\\?CONF_MAXSWAP=.*/CONF_MAXSWAP=2048/' /etc/dphys-swapfile"
+echo "   sudo nano /etc/dphys-swapfile  # Set CONF_SWAPSIZE=2048"
 echo "   sudo dphys-swapfile setup"
 echo "   sudo dphys-swapfile swapon"
 echo ""

scripts/download_nba_logos.py

@@ -7,8 +7,8 @@ import os
 import logging
 from typing import Tuple
 
-# Add the project root to Python path so we can import the logo downloader
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+# Add the src directory to Python path so we can import the logo downloader
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
 
 # Set up logging
 logging.basicConfig(
@@ -28,7 +28,7 @@ def download_nba_logos(force_download: bool = False) -> Tuple[int, int]:
         Tuple of (downloaded_count, failed_count)
     """
     try:
-        from src.logo_downloader import download_all_logos_for_league
+        from logo_downloader import download_all_logos_for_league
 
         logger.info("🏀 Starting NBA logo download...")
         logger.info(f"Target directory: assets/sports/nba_logos/")

scripts/fix_perms/README.md

@@ -31,6 +31,9 @@ owned by the `ledmatrix` service user or by `root`.
   systemd journal access, and the sudoers entries the web interface
   needs to control the display service.
 
+- **`fix_nhl_cache.sh`** — Targeted fix for NHL plugin cache issues
+  (clears the NHL cache and restarts the display service).
+
 - **`safe_plugin_rm.sh`** — Validates that a plugin removal path is
   inside an allowed base directory before deleting it. Used by the web
   interface (via sudo) when a user clicks **Uninstall** on a plugin —

scripts/fix_perms/fix_nhl_cache.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+"""
+Script to fix NHL cache issues on Raspberry Pi.
+This will clear the NHL cache and restart the display service.
+"""
+
+echo "=========================================="
+echo "Fixing NHL Cache Issues"
+echo "=========================================="
+
+# Clear NHL cache
+echo "Clearing NHL cache..."
+python3 clear_nhl_cache.py
+
+# Restart the display service to force fresh data fetch
+echo "Restarting display service..."
+sudo systemctl restart ledmatrix.service
+
+echo "NHL cache cleared and service restarted!"
+echo "NHL managers should now fetch fresh data from ESPN API."
+echo "Check the logs to see if NHL games are now being displayed."

scripts/generate_report.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+"""
+Security Report Generator
+
+Aggregates JSON output from all CI security audit jobs into a single
+Markdown report suitable for PR comments and artifact storage.
+
+Expected artifact layout (from actions/download-artifact@v4):
+    <artifact-dir>/
+        sast-results/
+            bandit-results.json
+            semgrep-results.json
+        dependency-audit-results/
+            pip-audit-results.json
+            safety-results.json
+        secrets-scan-results/
+            gitleaks-results.json
+        security-proofs-results/
+            security-proofs-results.json
+        plugin-audit-results/
+            plugin-audit-results.json
+
+Usage:
+    python scripts/generate_report.py --artifact-dir audit-artifacts/ --output report.md
+    python scripts/generate_report.py --artifact-dir audit-artifacts/ --output report.md --verbose
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from datetime import datetime, timezone
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# Gitleaks matches exactly equal to one of these (not a substring match -- a
+# real secret that merely contains one of these words as part of its actual
+# value must still be reported) are known template placeholders.
+_GITLEAKS_SUPPRESS_EXACT_VALUES = {
+    "YOUR_YOUTUBE_API_KEY",
+    "YOUR_YOUTUBE_CHANNEL_ID",
+    "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN",
+}
+
+# Findings in these files are suppressed regardless of value -- they are
+# template/example files that are expected to only ever contain placeholders.
+_GITLEAKS_SUPPRESS_PATHS = [
+    "config_secrets.template.json",
+    "config.template.json",
+]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _load(path: Path) -> tuple[dict | list | None, str | None]:
+    """Load a JSON artifact file.
+
+    Returns (data, error): error is None on success (data is whatever was
+    parsed, which may legitimately be an empty list/dict for a clean scan);
+    otherwise error is a human-readable reason the artifact is unavailable,
+    distinguishing "missing/malformed artifact" from "valid empty result" so
+    callers don't silently treat a broken CI job as a clean pass.
+    """
+    if not path.exists():
+        return None, f"artifact not found: {path}"
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), None
+    except (json.JSONDecodeError, OSError) as exc:
+        return None, f"could not read/parse {path}: {exc}"
+
+
+def _md_sanitize_cell(value: object) -> str:
+    """Escape/normalize a value so scanner-controlled content (a matched
+    secret, a bandit issue_text, a file path) can't alter the Markdown
+    table's structure: pipes would add bogus columns, newlines would break
+    out of the row (or forge a fake header/separator line)."""
+    text = str(value)
+    text = text.replace("\\", "\\\\").replace("|", "\\|")
+    text = text.replace("\r\n", " ").replace("\n", " ").replace("\r", " ")
+    return text
+
+
+def _md_table_row(*cells: str) -> str:
+    return "| " + " | ".join(_md_sanitize_cell(c) for c in cells) + " |"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Per-tool summarizers
+# Returns: (markdown_lines: list[str], critical_count: int, available: bool)
+# `available=False` means the artifact was missing or malformed -- distinct
+# from a valid scan that simply found nothing -- so the caller can report
+# INCOMPLETE instead of silently counting it as a clean pass.
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _summarize_bandit(artifact_dir: Path) -> tuple[list[str], int, bool]:
+    data, error = _load(artifact_dir / "sast-results" / "bandit-results.json")
+    if error:
+        return [f"_bandit results unavailable: {error}_"], 0, False
+
+    results = data.get("results", [])
+    high = [r for r in results if r.get("issue_severity") == "HIGH"]
+    medium = [r for r in results if r.get("issue_severity") == "MEDIUM"]
+    low = [r for r in results if r.get("issue_severity") == "LOW"]
+
+    lines = [
+        f"**Bandit**: {len(high)} HIGH · {len(medium)} MEDIUM · {len(low)} LOW"
+    ]
+
+    if high:
+        lines += [
+            "",
+            "| Severity | File | Line | Issue |",
+            "| --- | --- | --- | --- |",
+        ]
+        for r in high[:10]:
+            fname = Path(r.get("filename", "")).name
+            lines.append(_md_table_row(
+                "HIGH", f"`{fname}`",
+                str(r.get("line_number", "?")),
+                r.get("issue_text", "")
+            ))
+        if len(high) > 10:
+            lines.append(f"_… and {len(high) - 10} more HIGH findings_")
+
+    return lines, len(high), True
+
+
+def _summarize_pip_audit(artifact_dir: Path) -> tuple[list[str], int, bool]:
+    data, error = _load(artifact_dir / "dependency-audit-results" / "pip-audit-results.json")
+    if error:
+        return [f"_pip-audit results unavailable: {error}_"], 0, False
+
+    # pip-audit JSON format: {"dependencies": [{"name": ..., "vulns": [...]}]}
+    vulns: list[dict] = []
+    for dep in data.get("dependencies", []):
+        for v in dep.get("vulns", []):
+            vulns.append({"package": dep.get("name", "?"), **v})
+
+    lines = [f"**pip-audit**: {len(vulns)} vulnerabilities found"]
+
+    if vulns:
+        lines += ["", "| Package | ID | Fix |", "| --- | --- | --- |"]
+        for v in vulns[:10]:
+            fix = v.get("fix_versions", ["none"])
+            fix_str = ", ".join(fix) if fix else "none"
+            lines.append(_md_table_row(
+                v.get("package", "?"),
+                v.get("id", "?"),
+                fix_str,
+            ))
+
+    # Treat known vulnerabilities as warnings, not critical (they may be unavoidable)
+    return lines, 0, True
+
+
+def _summarize_gitleaks(artifact_dir: Path) -> tuple[list[str], int, bool]:
+    data, error = _load(artifact_dir / "secrets-scan-results" / "gitleaks-results.json")
+    if error:
+        return [f"_gitleaks results unavailable: {error}_"], 0, False
+
+    if not isinstance(data, list):
+        data = []
+
+    real_findings = []
+    suppressed = 0
+    for finding in data:
+        secret_val = str(finding.get("Secret", "") or finding.get("Match", ""))
+        file_name = Path(finding.get("File", "")).name
+        if (secret_val in _GITLEAKS_SUPPRESS_EXACT_VALUES
+                or file_name in _GITLEAKS_SUPPRESS_PATHS):
+            suppressed += 1
+        else:
+            real_findings.append(finding)
+
+    lines = [
+        f"**Gitleaks**: {len(real_findings)} finding(s) "
+        f"({suppressed} suppressed as template placeholders)"
+    ]
+
+    if real_findings:
+        lines += ["", "| Rule | File | Line | Description |", "| --- | --- | --- | --- |"]
+        for f in real_findings[:10]:
+            fname = Path(f.get("File", "")).name
+            lines.append(_md_table_row(
+                f.get("RuleID", "?"),
+                f"`{fname}`",
+                str(f.get("StartLine", "?")),
+                f.get("Description", ""),
+            ))
+
+    critical = len(real_findings)  # any real secret is critical
+    return lines, critical, True
+
+
+def _summarize_security_proofs(artifact_dir: Path) -> tuple[list[str], int, bool]:
+    data, error = _load(artifact_dir / "security-proofs-results" / "security-proofs-results.json")
+    if error:
+        return [f"_security proofs results unavailable: {error}_"], 0, False
+
+    if not isinstance(data, list):
+        data = []
+
+    critical = [r for r in data if r.get("severity") == "CRITICAL"]
+    warnings = [r for r in data if r.get("severity") == "WARNING"]
+    passed = [r for r in data if r.get("severity") == "PASS"]
+    skipped = [r for r in data if r.get("severity") == "SKIP"]
+
+    lines = [
+        f"**Security Proofs**: "
+        f"{len(passed)} PASS · {len(warnings)} WARN · "
+        f"{len(critical)} CRITICAL · {len(skipped)} SKIP",
+        "",
+    ]
+
+    _icon = {"PASS": "✅", "INFO": "ℹ️", "WARNING": "⚠️",  # nosec B105 - severity labels, not credentials
+             "CRITICAL": "🚨", "SKIP": "⏭️"}
+    for r in data:
+        icon = _icon.get(r.get("severity", ""), "❓")
+        lines.append(
+            f"- {icon} **{r.get('test_id', '?')}**: {r.get('message', '')}"
+        )
+        if r.get("details") and r.get("severity") in ("CRITICAL", "WARNING"):
+            lines.append(f"  - _{r['details']}_")
+
+    return lines, len(critical), True
+
+
+def _summarize_plugin_audit(artifact_dir: Path) -> tuple[list[str], int, bool]:
+    data, error = _load(artifact_dir / "plugin-audit-results" / "plugin-audit-results.json")
+    if error:
+        return [f"_plugin audit results unavailable: {error}_"], 0, False
+
+    summary = data.get("summary", {})
+    findings = data.get("findings", [])
+    critical_findings = [f for f in findings if f.get("severity") == "CRITICAL"]
+    warning_findings = [f for f in findings if f.get("severity") == "WARNING"]
+
+    lines = [
+        f"**Plugin Audit**: {data.get('plugins_scanned', '?')} plugins scanned — "
+        f"{summary.get('critical', 0)} CRITICAL · {summary.get('warnings', 0)} WARNINGS"
+    ]
+
+    if critical_findings:
+        lines += ["", "| Plugin | File | Line | Rule | Message |",
+                  "| --- | --- | --- | --- | --- |"]
+        for f in critical_findings[:10]:
+            fname = Path(f.get("file", "")).name
+            lines.append(_md_table_row(
+                f.get("plugin_id", "?"),
+                f"`{fname}`",
+                str(f.get("line", "?")),
+                f.get("rule", "?"),
+                f.get("message", ""),
+            ))
+
+    if warning_findings and not critical_findings:
+        lines.append(f"\n_{len(warning_findings)} warning(s) found — see artifact for details_")
+
+    return lines, summary.get("critical", 0), True
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────────────────────────────
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate consolidated security audit report",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--artifact-dir", required=True,
+                        help="Directory containing downloaded CI artifacts")
+    parser.add_argument("--output", "-o", required=True,
+                        help="Output Markdown file path")
+    parser.add_argument("--verbose", "-v", action="store_true")
+    args = parser.parse_args()
+
+    artifact_dir = Path(args.artifact_dir)
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    bandit_lines, bandit_crit, bandit_ok = _summarize_bandit(artifact_dir)
+    pip_audit_lines, pip_audit_crit, pip_audit_ok = _summarize_pip_audit(artifact_dir)
+    gitleaks_lines, gitleaks_crit, gitleaks_ok = _summarize_gitleaks(artifact_dir)
+    proofs_lines, proofs_crit, proofs_ok = _summarize_security_proofs(artifact_dir)
+    plugins_lines, plugins_crit, plugins_ok = _summarize_plugin_audit(artifact_dir)
+
+    unavailable_tools = [
+        name for name, ok in [
+            ("bandit", bandit_ok), ("pip-audit", pip_audit_ok),
+            ("gitleaks", gitleaks_ok), ("security-proofs", proofs_ok),
+            ("plugin-audit", plugins_ok),
+        ] if not ok
+    ]
+
+    total_critical = bandit_crit + pip_audit_crit + gitleaks_crit + proofs_crit + plugins_crit
+    if unavailable_tools:
+        # A missing/malformed artifact means that tool's checks never
+        # actually ran -- this must not be reported as a clean PASS just
+        # because the *artifacts that did load* found nothing.
+        overall = "INCOMPLETE ⚠️"
+    elif total_critical > 0:
+        overall = "ACTION REQUIRED 🚨"
+    else:
+        overall = "PASSED ✅"
+
+    def section(title: str, lines: list[str]) -> str:
+        return f"### {title}\n\n" + "\n".join(lines) + "\n"
+
+    incomplete_note = (
+        f"\n_⚠️ Incomplete: results unavailable for {', '.join(unavailable_tools)} "
+        f"— see the corresponding section(s) below for details_\n"
+        if unavailable_tools else ""
+    )
+
+    report = f"""## 🔒 Security Audit — {overall}
+
+_Generated: {timestamp}_
+{incomplete_note}
+| Critical | High/Warn | Overall |
+| :---: | :---: | :---: |
+| {'🚨 ' + str(total_critical) if total_critical else '✅ 0'} | ⚠️ see below | {overall} |
+
+---
+
+{section('SAST — Bandit', bandit_lines)}
+{section('Dependencies — pip-audit', pip_audit_lines)}
+{section('Secrets — Gitleaks', gitleaks_lines)}
+{section('LEDMatrix Security Proofs', proofs_lines)}
+{section('Plugin Security Audit', plugins_lines)}
+---
+
+_Total critical findings: **{total_critical}**_
+"""
+
+    output_path = Path(args.output)
+    output_path.write_text(report, encoding="utf-8")
+
+    if args.verbose:
+        print(f"  Report written to: {output_path}")
+        print(f"  Status: {overall}")
+        print(f"  Critical findings: {total_critical}")
+        print(f"    bandit={bandit_crit}  pip-audit={pip_audit_crit}  "
+              f"gitleaks={gitleaks_crit}  proofs={proofs_crit}  plugins={plugins_crit}")
+        if unavailable_tools:
+            print(f"  Unavailable: {', '.join(unavailable_tools)}")
+
+    if unavailable_tools:
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/install/lib_lowmem.sh

@@ -1,283 +0,0 @@
-#!/bin/bash
-#
-# Low-memory build helpers for the LED Matrix installer.
-#
-# Sourced by first_time_install.sh. These live in a separate, sourceable file
-# so the pure sizing/detection functions can be unit-tested
-# (test/test_install_lowmem.py); first_time_install.sh itself is not sourceable
-# because it self-elevates and runs top to bottom.
-#
-# Why this exists: the rgbmatrix build compiles ~45 C++ translation units, two
-# of them Cython-generated (a single cc1plus on those peaks around 400-800MB at
-# -O3). Upstream's pyproject.toml sets no [tool.scikit-build] options, so
-# scikit-build-core uses Ninja at its default of nproc+2 jobs -- six concurrent
-# compiles on a 4-core Pi. On a 512MB-1GB Pi the OOM killer reaps cc1plus and
-# pip reports only "Failed building wheel for rgbmatrix".
-#
-# The caller runs under `set -Eeuo pipefail` with an ERR trap, and these are
-# invoked from the middle of numbered steps, so nothing here may call exit and
-# the swap helpers must always return 0.
-
-# Overridable so tests can point at fixture files instead of /proc.
-LM_MEMINFO="${LM_MEMINFO:-/proc/meminfo}"
-LM_SWAPS="${LM_SWAPS:-/proc/swaps}"
-
-# Temporary swapfile created for the build and removed afterwards. Deliberately
-# never added to /etc/fstab: a malformed fstab can leave a novice with an
-# unbootable Pi, and this swap only needs to outlive the compile.
-LM_SWAPFILE="${LM_SWAPFILE:-/var/swap.ledmatrix-install}"
-
-# Bring RAM + real swap up to this much before compiling, capped per swapfile.
-LM_SWAP_TARGET_MB="${LM_SWAP_TARGET_MB:-3072}"
-LM_SWAP_MAX_MB="${LM_SWAP_MAX_MB:-2048}"
-
-# Worst-case cc1plus footprint on the Cython translation unit, used to size
-# build parallelism against available RAM.
-LM_MB_PER_JOB="${LM_MB_PER_JOB:-768}"
-
-# Set to 1 once swap is live, so lm_remove_build_swap (wired up as an EXIT
-# trap) knows whether there is anything to undo.
-LM_TEMP_SWAP_ACTIVE=0
-
-# Human-readable reason no swapfile was created, quoted back in the failure
-# message so a user who still OOMs is told why the safety net was absent.
-LM_SWAP_SKIP_REASON=""
-
-# ---------------------------------------------------------------------------
-# Pure helpers (no side effects; unit-tested)
-# ---------------------------------------------------------------------------
-
-# Total physical RAM in MB, or 0 if it cannot be determined.
-lm_total_ram_mb() {
-    # Defaults are re-resolved here as well as at source time so the function
-    # stays safe under the installer's `set -u`.
-    awk '/^MemTotal:/ {printf "%d\n", $2 / 1024; found = 1; exit} END {if (!found) print 0}' \
-        "${LM_MEMINFO:-/proc/meminfo}" 2>/dev/null || echo 0
-}
-
-# Total swap in MB, EXCLUDING zram devices.
-#
-# zram swap is compressed RAM: it consumes the very resource that is already
-# exhausted and does nothing for a build OOM. Counting it would let a
-# zram-enabled image decide it has enough swap and then fail exactly as before.
-lm_total_swap_mb() {
-    awk 'NR > 1 && $1 !~ /^\/dev\/zram/ {total += $3} END {printf "%d\n", total / 1024}' \
-        "${LM_SWAPS:-/proc/swaps}" 2>/dev/null || echo 0
-}
-
-# lm_build_jobs <ram_mb> <cores> -> max(1, min(cores, ram_mb / LM_MB_PER_JOB))
-#
-# Computed from RAM alone and never RAM+swap: handing out extra jobs because
-# swap exists just guarantees SD-card thrash, which is far slower than
-# compiling serially.
-lm_build_jobs() {
-    local ram_mb="${1:-0}" cores="${2:-1}" jobs
-    local per_job="${LM_MB_PER_JOB:-768}"
-    if [ "$cores" -lt 1 ]; then
-        cores=1
-    fi
-    jobs=$(( ram_mb / per_job ))
-    if [ "$jobs" -lt 1 ]; then
-        jobs=1
-    fi
-    if [ "$jobs" -gt "$cores" ]; then
-        jobs="$cores"
-    fi
-    echo "$jobs"
-}
-
-# lm_swap_needed_mb <ram_mb> <existing_swap_mb> -> swapfile size in MB, or 0.
-#
-# Brings RAM + real swap up to LM_SWAP_TARGET_MB, capped at LM_SWAP_MAX_MB and
-# rounded up to a 256MB multiple. Machines with enough memory get 0 and are
-# left completely untouched.
-lm_swap_needed_mb() {
-    local ram_mb="${1:-0}" swap_mb="${2:-0}" needed
-    local target="${LM_SWAP_TARGET_MB:-3072}" max="${LM_SWAP_MAX_MB:-2048}"
-    needed=$(( target - ram_mb - swap_mb ))
-    if [ "$needed" -le 0 ]; then
-        echo 0
-        return 0
-    fi
-    if [ "$needed" -gt "$max" ]; then
-        needed="$max"
-    fi
-    echo $(( ( (needed + 255) / 256 ) * 256 ))
-}
-
-# lm_build_failed_on_oom <build_output_file> -> 0 if the build was OOM-killed.
-#
-# Two independent evidence sources, because neither alone is reliable: the
-# compiler sometimes reports its own allocation failure, but when the kernel
-# OOM killer fires it writes nothing to the build's stdout. That silence is
-# exactly why the old handler misdiagnosed this as missing build tools.
-lm_build_failed_on_oom() {
-    local build_output="${1:-}" kernel_log=""
-
-    if [ -n "$build_output" ] && [ -f "$build_output" ]; then
-        if grep -qiE 'cc1plus: out of memory|virtual memory exhausted|Cannot allocate memory|MemoryError|fatal error: Killed signal terminated program|signal 9' \
-            "$build_output"; then
-            return 0
-        fi
-    fi
-
-    # LM_KERNEL_LOG_FILE lets tests supply a fixture instead of the real kernel
-    # ring buffer, which on a shared CI machine may hold unrelated OOM events.
-    if [ -n "${LM_KERNEL_LOG_FILE:-}" ]; then
-        if [ -f "$LM_KERNEL_LOG_FILE" ]; then
-            kernel_log=$(cat "$LM_KERNEL_LOG_FILE" 2>/dev/null || true)
-        fi
-    elif command -v dmesg >/dev/null 2>&1; then
-        kernel_log=$(dmesg -T 2>/dev/null || dmesg 2>/dev/null || true)
-    fi
-    if [ -z "$kernel_log" ] && [ -z "${LM_KERNEL_LOG_FILE:-}" ] && command -v journalctl >/dev/null 2>&1; then
-        kernel_log=$(journalctl -k --since "30 min ago" --no-pager 2>/dev/null || true)
-    fi
-
-    if [ -n "$kernel_log" ]; then
-        if printf '%s\n' "$kernel_log" | tail -n 300 | \
-            grep -qiE 'Out of memory: Kill|oom_kill|oom-kill|Killed process'; then
-            return 0
-        fi
-    fi
-
-    return 1
-}
-
-# lm_disk_backed_tmpdir [candidate] -> a disk-backed temp dir, or nothing.
-#
-# pip builds in $TMPDIR. Debian 13 mounts /tmp as tmpfs, so the default puts the
-# whole C++ build tree in RAM, competing with the compiler we are already trying
-# to keep under the limit. Prints a replacement only when the current TMPDIR is
-# memory-backed and the candidate is not; otherwise prints nothing and the
-# caller keeps its default.
-lm_disk_backed_tmpdir() {
-    local candidate="${1:-/var/tmp}"
-    local current="${TMPDIR:-/tmp}"
-    local current_fs="" candidate_fs=""
-
-    current_fs=$(lm_fstype_of "$current")
-    case "$current_fs" in
-        tmpfs|ramfs) ;;
-        *) return 0 ;;
-    esac
-
-    candidate_fs=$(lm_fstype_of "$candidate")
-    case "$candidate_fs" in
-        tmpfs|ramfs|"") return 0 ;;
-    esac
-
-    echo "$candidate"
-}
-
-# Filesystem type backing a path, or empty if it cannot be determined.
-lm_fstype_of() {
-    local path="${1:-/}"
-    if command -v findmnt >/dev/null 2>&1; then
-        findmnt -no FSTYPE --target "$path" 2>/dev/null | head -n 1
-        return 0
-    fi
-    if command -v stat >/dev/null 2>&1; then
-        stat -f -c %T "$path" 2>/dev/null | head -n 1
-        return 0
-    fi
-    return 0
-}
-
-# ---------------------------------------------------------------------------
-# Swap management (requires root; not unit-tested)
-# ---------------------------------------------------------------------------
-
-# lm_ensure_build_swap <needed_mb>
-#
-# Always returns 0. On any refusal it sets LM_SWAP_SKIP_REASON and leaves the
-# system untouched -- swap is a safety net for the build, never a precondition.
-lm_ensure_build_swap() {
-    local needed_mb="${1:-0}"
-    local swap_dir free_mb budget
-
-    LM_SWAP_SKIP_REASON=""
-
-    if [ "$needed_mb" -le 0 ]; then
-        LM_SWAP_SKIP_REASON="not needed (RAM and existing swap are sufficient)"
-        return 0
-    fi
-
-    if ! command -v mkswap >/dev/null 2>&1 || ! command -v swapon >/dev/null 2>&1; then
-        LM_SWAP_SKIP_REASON="mkswap/swapon are not available on this system"
-        echo "⚠ Cannot add build swap: $LM_SWAP_SKIP_REASON"
-        return 0
-    fi
-
-    # Clear a stale swapfile left by a run that was killed before its cleanup
-    # ran, so this is safe to call repeatedly.
-    if [ -e "$LM_SWAPFILE" ]; then
-        echo "Removing a leftover swapfile from a previous run: $LM_SWAPFILE"
-        swapoff "$LM_SWAPFILE" >/dev/null 2>&1 || true
-        rm -f "$LM_SWAPFILE" || true
-    fi
-
-    # Keep a working margin for the build tree itself; never eat the last GB.
-    swap_dir=$(dirname "$LM_SWAPFILE")
-    free_mb=$(df -m "$swap_dir" 2>/dev/null | awk 'NR==2{print $4}')
-    free_mb=${free_mb:-0}
-    budget=$(( free_mb - 1024 ))
-    if [ "$budget" -lt 256 ]; then
-        LM_SWAP_SKIP_REASON="only ${free_mb}MB free on ${swap_dir}, need about $(( needed_mb + 1024 ))MB"
-        echo "⚠ Skipping the build swapfile: $LM_SWAP_SKIP_REASON"
-        return 0
-    fi
-    if [ "$needed_mb" -gt "$budget" ]; then
-        echo "⚠ Trimming the build swapfile from ${needed_mb}MB to leave 1GB free on ${swap_dir}"
-        needed_mb=$(( ( budget / 256 ) * 256 ))
-    fi
-
-    echo "Adding a temporary ${needed_mb}MB swapfile for the build: $LM_SWAPFILE"
-    echo "  This is removed automatically once the build finishes."
-
-    # fallocate can produce a sparse file that mkswap rejects, and is not
-    # supported on every filesystem; dd always yields a usable file.
-    if ! fallocate -l "${needed_mb}M" "$LM_SWAPFILE" 2>/dev/null; then
-        if ! dd if=/dev/zero of="$LM_SWAPFILE" bs=1M count="$needed_mb" status=none 2>/dev/null; then
-            LM_SWAP_SKIP_REASON="could not allocate ${needed_mb}MB at $LM_SWAPFILE"
-            echo "⚠ $LM_SWAP_SKIP_REASON"
-            rm -f "$LM_SWAPFILE" || true
-            return 0
-        fi
-    fi
-
-    chmod 600 "$LM_SWAPFILE" || true
-
-    if ! mkswap "$LM_SWAPFILE" >/dev/null 2>&1; then
-        LM_SWAP_SKIP_REASON="mkswap failed on $LM_SWAPFILE"
-        echo "⚠ $LM_SWAP_SKIP_REASON"
-        rm -f "$LM_SWAPFILE" || true
-        return 0
-    fi
-
-    if ! swapon "$LM_SWAPFILE" >/dev/null 2>&1; then
-        LM_SWAP_SKIP_REASON="swapon failed on $LM_SWAPFILE"
-        echo "⚠ $LM_SWAP_SKIP_REASON"
-        rm -f "$LM_SWAPFILE" || true
-        return 0
-    fi
-
-    LM_TEMP_SWAP_ACTIVE=1
-    echo "✓ Temporary build swap active (${needed_mb}MB; total swap is now $(lm_total_swap_mb)MB)"
-    return 0
-}
-
-# Remove the temporary swapfile. Safe to call unconditionally and repeatedly.
-#
-# Wired up as an EXIT trap, so it must never return non-zero -- a failing trap
-# would surface as a spurious installer error.
-lm_remove_build_swap() {
-    if [ "${LM_TEMP_SWAP_ACTIVE:-0}" != "1" ]; then
-        return 0
-    fi
-    LM_TEMP_SWAP_ACTIVE=0
-    echo "Removing the temporary build swapfile: $LM_SWAPFILE"
-    swapoff "$LM_SWAPFILE" >/dev/null 2>&1 || true
-    rm -f "$LM_SWAPFILE" || true
-    return 0
-}

scripts/install/one-shot-install.sh

@@ -145,34 +145,6 @@ check_disk_space() {
     fi
 }
 
-# Report available memory so the user knows what to expect before the wait.
-#
-# Informational only — first_time_install.sh does the real work of capping
-# build parallelism and adding temporary swap. Never fatal: a low-RAM Pi is
-# supported, it is just slower.
-check_memory() {
-    CURRENT_STEP="Memory check"
-    if [ ! -r /proc/meminfo ]; then
-        print_warning "Cannot read /proc/meminfo, skipping memory check"
-        return 0
-    fi
-
-    TOTAL_RAM_MB=$(awk '/^MemTotal:/ {printf "%d\n", $2 / 1024; exit}' /proc/meminfo 2>/dev/null || echo 0)
-    TOTAL_RAM_MB=${TOTAL_RAM_MB:-0}
-
-    if [ "$TOTAL_RAM_MB" -eq 0 ]; then
-        print_warning "Could not determine system memory, continuing"
-    elif [ "$TOTAL_RAM_MB" -lt 2048 ]; then
-        print_warning "Low memory: ${TOTAL_RAM_MB}MB RAM"
-        echo "  The rpi-rgb-led-matrix C++ build needs more memory than this Pi has."
-        echo "  The installer will compile with fewer parallel jobs and add a temporary"
-        echo "  swapfile for the build, removing it afterwards. That step will take"
-        echo "  15-25 minutes rather than the usual 2-5."
-    else
-        print_success "Memory sufficient: ${TOTAL_RAM_MB}MB RAM"
-    fi
-}
-
 # Ensure sudo access
 check_sudo() {
     CURRENT_STEP="Sudo access check"
@@ -232,7 +204,7 @@ main() {
     print_step "LED Matrix One-Shot Installation"
     
     echo "This script will:"
-    echo "  1. Check prerequisites (network, disk space, memory, sudo)"
+    echo "  1. Check prerequisites (network, disk space, sudo)"
     echo "  2. Install system dependencies (git, python3, build tools)"
     echo "  3. Clone the LEDMatrix repository"
     echo "  4. Run the first-time installation script"
@@ -241,7 +213,6 @@ main() {
     # Check prerequisites
     check_network
     check_disk_space
-    check_memory
     check_sudo
     # Note: /tmp permissions are checked and fixed inline before running first_time_install.sh
     # (only if actually wrong, not preemptively)
@@ -257,14 +228,12 @@ main() {
         exit 1
     fi
     
-    # Update package list first. first_time_install.sh is told the lists are
-    # already fresh so it does not repeat this a minute later.
+    # Update package list first
     if [ "$EUID" -eq 0 ]; then
         retry apt-get update -qq
     else
         retry sudo apt-get update -qq
     fi
-    export LEDMATRIX_APT_UPDATED=1
     
     # Install git and curl (needed for cloning and the script itself)
     if ! command -v git >/dev/null 2>&1 || ! command -v curl >/dev/null 2>&1; then
@@ -403,12 +372,7 @@ main() {
         # Pass both -y flag AND environment variable for non-interactive mode
         # This ensures it works even if the script re-executes itself with sudo
         # Also ensure stdin is properly handled for non-interactive mode
-        # LEDMATRIX_APT_UPDATED is passed explicitly rather than relying on
-        # -E: a sudoers env_reset/env_keep policy can strip exported variables,
-        # which would silently reinstate the duplicate apt update.
-        sudo -E env TMPDIR=/tmp LEDMATRIX_ASSUME_YES=1 \
-            LEDMATRIX_APT_UPDATED="${LEDMATRIX_APT_UPDATED:-0}" \
-            bash ./first_time_install.sh -y </dev/null
+        sudo -E env TMPDIR=/tmp LEDMATRIX_ASSUME_YES=1 bash ./first_time_install.sh -y </dev/null
     fi
     INSTALL_EXIT_CODE=$?
     trap 'on_error $LINENO' ERR  # Re-enable ERR trap

scripts/install_dependencies_apt.py

@@ -44,12 +44,17 @@ def install_via_apt(package_name: str) -> Tuple[bool, str]:
     apt_package_map = {
         'flask': 'python3-flask',
         'PIL': 'python3-pil',
-        'freetype-py': 'python3-freetype',
+        'freetype': 'python3-freetype',
         'psutil': 'python3-psutil',
         'werkzeug': 'python3-werkzeug',
         'numpy': 'python3-numpy',
         'requests': 'python3-requests',
-        'pytz': 'python3-tz'
+        'python-dateutil': 'python3-dateutil',
+        'pytz': 'python3-tz',
+        'geopy': 'python3-geopy',
+        'unidecode': 'python3-unidecode',
+        'websockets': 'python3-websockets',
+        'websocket-client': 'python3-websocket-client'
     }
 
     apt_package = apt_package_map.get(package_name, f'python3-{package_name}')
@@ -76,8 +81,8 @@ def install_via_pip(package_name: str) -> Tuple[bool, str]:
     pip RECORD file, so an uninstall attempt fails with "uninstall-no-record-file"
     and aborts the whole install. With --ignore-installed, pip lays the new
     version down in /usr/local where it shadows the apt copy instead of removing
-    it. This matters when a pip dependency needs to upgrade an apt-managed
-    package (e.g. a package that pulls a newer requests).
+    it. This matters when a pip dependency (google-api-python-client pulls a
+    newer requests) needs to upgrade an apt-managed package.
 
     Returns (success, output).
     """
@@ -96,7 +101,8 @@ def install_via_pip(package_name: str) -> Tuple[bool, str]:
 
 # Distribution (pip/apt) names whose importable module name differs.
 IMPORT_NAME_MAP = {
-    'freetype-py': 'freetype',
+    'python-dateutil': 'dateutil',
+    'websocket-client': 'websocket',
 }
 
 
@@ -141,12 +147,17 @@ def main():
     required_packages = [
         'flask',
         'PIL',
-        'freetype-py',
+        'freetype',
         'psutil',
         'werkzeug',
         'numpy',
         'requests',
-        'pytz'
+        'python-dateutil',
+        'pytz',
+        'geopy',
+        'unidecode',
+        'websockets',
+        'websocket-client'
     ]
 
     failed_packages = []
@@ -166,12 +177,15 @@ def main():
                 failure_details[package] = pip_output or apt_output
 
     # Install packages that don't have apt equivalents
-    # Packages without apt equivalents. Plugin-specific dependencies
-    # (timezonefinder, google-api stack, icalevents, socketio, ...) are
-    # no longer installed here — store plugins declare their own
-    # requirements.txt, which the plugin store installs.
     special_packages = [
+        'timezonefinder>=6.5.0,<7.0.0',
+        'google-auth-oauthlib>=1.2.0,<2.0.0',
+        'google-auth-httplib2>=0.2.0,<1.0.0',
+        'google-api-python-client>=2.147.0,<3.0.0',
         'spotipy',
+        'icalevents',
+        'python-socketio>=5.11.0,<6.0.0',
+        'python-engineio>=4.9.0,<5.0.0'
     ]
 
     for package in special_packages:

scripts/remove_plugin_backups.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# Script to safely remove plugin backup directories
+# These were created during the plugin-to-submodule conversion
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PLUGINS_DIR="$PROJECT_ROOT/plugins"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Verify submodules are working
+verify_submodules() {
+    log_info "Verifying submodules are working..."
+    local issues=0
+    
+    for submod in football-scoreboard hockey-scoreboard ledmatrix-flights \
+                  ledmatrix-leaderboard ledmatrix-stocks ledmatrix-weather \
+                  mqtt-notifications; do
+        if [ ! -d "$PLUGINS_DIR/$submod" ]; then
+            log_error "Submodule directory missing: $submod"
+            issues=$((issues + 1))
+        elif [ ! -f "$PLUGINS_DIR/$submod/.git" ]; then
+            log_error "Submodule .git file missing: $submod"
+            issues=$((issues + 1))
+        elif [ ! -f "$PLUGINS_DIR/$submod/manifest.json" ]; then
+            log_warn "Submodule manifest missing: $submod (may be OK)"
+        fi
+    done
+    
+    if [ $issues -eq 0 ]; then
+        log_info "All submodules verified ✓"
+        return 0
+    else
+        log_error "Found $issues issues with submodules"
+        return 1
+    fi
+}
+
+# Remove backup directories
+remove_backups() {
+    log_info "Removing backup directories..."
+    
+    local removed=0
+    local total_size=0
+    
+    for backup in "$PLUGINS_DIR"/*.backup*; do
+        if [ -d "$backup" ]; then
+            local name=$(basename "$backup")
+            local size=$(du -sb "$backup" 2>/dev/null | awk '{print $1}')
+            total_size=$((total_size + size))
+            
+            log_info "Removing: $name"
+            rm -rf "$backup"
+            removed=$((removed + 1))
+        fi
+    done
+    
+    if [ $removed -gt 0 ]; then
+        log_info "Removed $removed backup directory(ies)"
+        log_info "Freed approximately $(numfmt --to=iec-i --suffix=B $total_size 2>/dev/null || echo "$total_size bytes")"
+    else
+        log_info "No backup directories found"
+    fi
+}
+
+# Main
+main() {
+    cd "$PROJECT_ROOT"
+    
+    echo "=== Plugin Backup Removal Script ==="
+    echo
+    
+    # Verify submodules first
+    if ! verify_submodules; then
+        log_error "Submodule verification failed. Not removing backups."
+        log_warn "Please fix submodule issues before removing backups."
+        exit 1
+    fi
+    
+    echo
+    log_warn "This will permanently delete backup directories:"
+    ls -1d "$PLUGINS_DIR"/*.backup* 2>/dev/null | sed 's|.*/|  - |' || echo "  (none found)"
+    echo
+    
+    read -p "Continue? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        log_info "Aborted"
+        exit 0
+    fi
+    
+    remove_backups
+    
+    log_info "Done!"
+}
+
+main "$@"
+

scripts/utils/clear_cache.py

@@ -8,10 +8,10 @@ import os
 import sys
 import argparse
 
-# Add the project root to the path so we can import our modules
-sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+# Add the src directory to the path so we can import our modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
 
-from src.cache_manager import CacheManager
+from cache_manager import CacheManager
 
 def list_cache_keys(cache_manager):
     """List all available cache keys."""

src/__init__.py

@@ -4,5 +4,5 @@ LEDMatrix Display System
 Core source package for the LED Matrix Display project.
 """
 
-__version__ = "3.2.0"
+__version__ = "3.1.0"
 

src/base_classes/baseball.py

@@ -151,12 +151,7 @@ class Baseball(SportsCore):
 
             # Only log detailed information for favorite teams
             if is_favorite_game:
-                # Use the validated competition-level `status` here too. MiLB
-                # events carry no event-level one, so this debug line raised a
-                # KeyError and dropped the very games it was meant to help
-                # diagnose -- and only for favourites, which is the worst way
-                # for it to fail.
-                self.logger.debug(f"Full status data: {status}")
+                self.logger.debug(f"Full status data: {game_event['status']}")
                 self.logger.debug(f"Status type: {game_status}, State: {status_state}")
                 self.logger.debug(f"Status detail: {status['type'].get('detail', '')}")
                 self.logger.debug(
@@ -169,13 +164,7 @@ class Baseball(SportsCore):
             # Get game state information
             if status_state == "in":
                 # For live games, get detailed state
-                # Use the competition-level `status` already validated by
-                # _extract_game_details_common. Real ESPN events duplicate
-                # status at the event top level, but MiLB events (synthesized
-                # from the MLB Stats API into an ESPN-like shape) populate
-                # only the competition-level one, so the top-level lookup
-                # raised a bare KeyError and dropped the event.
-                inning = status.get(
+                inning = game_event["status"].get(
                     "period", 1
                 )  # Get inning from status period
 
@@ -198,7 +187,7 @@ class Baseball(SportsCore):
                 if "end" in status_detail or "end" in status_short:
                     inning_half = "top"
                     inning = (
-                        status.get("period", 1) + 1
+                        game_event["status"].get("period", 1) + 1
                     )  # Use period and increment for next inning
                     if is_favorite_game:
                         self.logger.debug(

src/base_classes/data_sources.py

@@ -44,16 +44,9 @@ class DataSource(ABC):
         """Fetch standings for a sport/league."""
     
     def get_headers(self) -> Dict[str, str]:
-        """Get headers for API requests.
-
-        The agent carries the project URL deliberately. Around 2026-08-04 ESPN
-        began returning 403 for bare custom tokens like 'LEDMatrix/1.0' — and
-        for browser-style strings — while accepting an agent that identifies
-        the client and links to it. An Accept header alone does not rescue the
-        bare form when the request goes out through requests.
-        """
+        """Get headers for API requests."""
         return {
-            'User-Agent': 'LEDMatrix/1.0 (+https://github.com/ChuckBuilds/LEDMatrix)',
+            'User-Agent': 'LEDMatrix/1.0',
             'Accept': 'application/json'
         }
 

src/base_classes/hockey.py

@@ -38,17 +38,10 @@ class Hockey(SportsCore):
             status = competition["status"]
             powerplay = False
             penalties = ""
-            # A competitor may legitimately arrive without a "statistics"
-            # array (pre-game feeds, and some in-progress ones). Reading it
-            # unguarded raised KeyError inside the generator and dropped the
-            # WHOLE event, discarding valid scores and status. Default to an
-            # empty list so the saves/shots figures fall back to 0 instead.
-            home_stats = home_team.get("statistics", [])
-            away_stats = away_team.get("statistics", [])
             home_team_saves = next(
                 (
                     int(c["displayValue"])
-                    for c in home_stats
+                    for c in home_team["statistics"]
                     if c.get("name") == "saves"
                 ),
                 0,
@@ -56,7 +49,7 @@ class Hockey(SportsCore):
             home_team_saves_per = next(
                 (
                     float(c["displayValue"])
-                    for c in home_stats
+                    for c in home_team["statistics"]
                     if c.get("name") == "savePct"
                 ),
                 0.0,
@@ -64,7 +57,7 @@ class Hockey(SportsCore):
             away_team_saves = next(
                 (
                     int(c["displayValue"])
-                    for c in away_stats
+                    for c in away_team["statistics"]
                     if c.get("name") == "saves"
                 ),
                 0,
@@ -72,7 +65,7 @@ class Hockey(SportsCore):
             away_team_saves_per = next(
                 (
                     float(c["displayValue"])
-                    for c in away_stats
+                    for c in away_team["statistics"]
                     if c.get("name") == "savePct"
                 ),
                 0.0,

src/base_classes/sports/__init__.py

@@ -1,17 +0,0 @@
-"""Sports scoreboard base classes.
-
-Formerly the single module ``src/base_classes/sports.py``; now a package so
-capabilities can be composed instead of accumulating in one class. See
-docs/SPORTS_UNIFICATION.md for the architecture. The import path is
-unchanged: ``from src.base_classes.sports import SportsCore`` still works.
-"""
-
-from .core import SportsCore
-from .modes import SportsLive, SportsRecent, SportsUpcoming
-
-__all__ = [
-    "SportsCore",
-    "SportsUpcoming",
-    "SportsRecent",
-    "SportsLive",
-]

src/base_classes/sports/capabilities/__init__.py

@@ -1,32 +0,0 @@
-"""Opt-in capabilities for the sports scoreboards.
-
-Each module here is a feature that only *some* sports want. They are composed
-by inheritance (mixins) or selected by name (strategies) — never enabled by an
-``if self.<feature>_enabled:`` branch inside the base classes.
-
-The distinction matters: hockey has no celebrations, so ``HockeyLive`` does not
-inherit :class:`~.celebrations.CelebrationMixin` and the celebration code is not
-in hockey's MRO at all. A bug in it cannot reach a plugin that never opted in.
-
-See ``docs/SPORTS_UNIFICATION.md`` for the full rationale.
-"""
-
-from .celebrations import CelebrationMixin
-from .rotation import (
-    RotationStrategy,
-    SimpleRotation,
-    SmoothWeightedRotation,
-    WeightedCycleRotation,
-    get_rotation_strategy,
-    register_rotation_strategy,
-)
-
-__all__ = [
-    "CelebrationMixin",
-    "RotationStrategy",
-    "SimpleRotation",
-    "SmoothWeightedRotation",
-    "WeightedCycleRotation",
-    "get_rotation_strategy",
-    "register_rotation_strategy",
-]

src/base_classes/sports/capabilities/celebrations.py

@@ -1,418 +0,0 @@
-"""Score / win celebration takeover — an opt-in capability.
-
-Four of the nine scoreboards celebrate (afl, nrl, soccer, football); the other
-five do not. This is a **mixin** rather than a flag inside ``SportsLive`` so the
-five that do not opt in have none of this code in their MRO: a bug here cannot
-reach hockey, and hockey's config never grows keys it ignores.
-
-Usage — mix in *before* the mode class so its ``display`` runs first::
-
-    class SoccerLive(CelebrationMixin, SportsLive):
-        def score_phrase(self, points, team_abbr):
-            return secrets.choice(("GOOOOAAALLL!", f"{team_abbr} SCORES!"))
-
-The two lineages spelled this differently (``_check_for_goal`` /
-``celebrate_opponent_goals`` in the soccer lineage, ``_check_for_score`` /
-``celebrate_opponent_scores`` in football) but the bodies were identical apart
-from three things, each of which is a seam here rather than a branch:
-
-* **wording** — :meth:`score_phrase`, the hook football uses to say "TOUCHDOWN"
-  from the points delta and soccer uses to say "GOOOOAAALLL";
-* **follow-up suppression** — :attr:`COALESCE_SCORING_SEQUENCE`, on for football
-  where a touchdown lands as +6 then +1 a few seconds later, off elsewhere where
-  two quick goals are two real events;
-* **team identity** — matching goes through ``_favorite_key``, so nrl can match
-  on team id (its abbreviations are ambiguous) without core knowing why.
-
-The config keys are read under both spellings, so a plugin adopting the mixin
-keeps working with the ``*_goals`` keys already in its published schema.
-"""
-
-from __future__ import annotations
-
-import re
-import time
-from typing import Any, Dict, List, Optional
-
-from PIL import Image, ImageDraw
-
-
-class CelebrationMixin:
-    """Full-screen takeover when a tracked team scores or wins."""
-
-    #: Collapse increments that land while a celebration is already on screen
-    #: into that one celebration. True for sports where a single scoring play
-    #: arrives as more than one score update (football: touchdown +6, then the
-    #: extra point +1). False where consecutive increments are distinct events —
-    #: suppressing there would swallow a real goal.
-    COALESCE_SCORING_SEQUENCE = False
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        mode_config = getattr(self, "mode_config", {}) or {}
-        self.celebration_enabled = mode_config.get("celebration_enabled", True)
-        # Coerced and floored at init: this value is compared numerically on the
-        # display path, where a string from a hand-edited config would raise
-        # TypeError outside any try block, and a zero or negative value would
-        # arm a celebration that can never render.
-        raw_duration = mode_config.get("celebration_duration", 8)
-        try:
-            self.celebration_duration = max(1.0, float(raw_duration))
-        except (TypeError, ValueError):
-            self.logger.warning(
-                "[Celebrations] Unusable celebration_duration %r; using 8s. "
-                "Set a positive number of seconds.",
-                raw_duration,
-            )
-            self.celebration_duration = 8.0
-        # Both spellings: the soccer lineage ships `celebrate_opponent_goals`,
-        # football ships `celebrate_opponent_scores`. Whichever the plugin's
-        # schema declares is the one its users have set.
-        self.celebrate_opponent_scores = mode_config.get(
-            "celebrate_opponent_scores",
-            mode_config.get("celebrate_opponent_goals", False),
-        )
-        # Per-game score baselines: {game_id: {"away": int, "home": int}}
-        self._score_baselines: Dict[str, Dict[str, int]] = {}
-        # The active celebration (a game *snapshot*, so a win survives the game
-        # leaving live_games) or None. See _start_celebration for the shape.
-        self.active_celebration: Optional[Dict[str, Any]] = None
-
-    # ------------------------------------------------------------------
-    # Override points
-    # ------------------------------------------------------------------
-
-    def score_phrase(self, points: int, team_abbr: str) -> str:
-        """The wording for a score celebration.
-
-        ``points`` is the score delta that triggered it, which sports with
-        variable-value scores use to name the play. The default is deliberately
-        sport-neutral; every celebrating plugin overrides it.
-        """
-        return f"{team_abbr} SCORES!"
-
-    def win_phrase(self, team_abbr: str) -> str:
-        """The wording for a win celebration."""
-        return f"{team_abbr} WINS!"
-
-    def _is_favorite(self, key: Optional[str]) -> bool:
-        """Whether ``key`` (whatever ``_favorite_key`` returns) is a favorite."""
-        return bool(self.favorite_teams) and key in self.favorite_teams
-
-    # ------------------------------------------------------------------
-    # Detection
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _score_to_int(score) -> Optional[int]:
-        """Coerce an ESPN score value (str / int / dict) to an int, or None."""
-        try:
-            if score is None:
-                return None
-            if isinstance(score, str):
-                s = score.strip()
-                if not s:
-                    return None
-                try:
-                    return int(float(s))
-                except ValueError:
-                    numbers = re.findall(r"\d+", s)
-                    return int(numbers[0]) if numbers else None
-            if isinstance(score, dict):
-                return int(float(score.get("value", score.get("displayValue", 0))))
-            return int(float(score))
-        except (ValueError, TypeError):
-            return None
-
-    def _should_celebrate_for(self, game: Dict, side: str) -> bool:
-        """Whether a score by ``side`` in ``game`` should trigger a celebration."""
-        if self._is_favorite(self._favorite_key(game, side)):
-            return True
-        if not self.favorite_teams:
-            # No favorites configured: the user opted to show this game, so
-            # celebrate any score in it.
-            return True
-        # Favorites exist but this team isn't one -> it's the opponent.
-        return self.celebrate_opponent_scores
-
-    def prune_score_baselines(self, live_games: List[Dict]) -> None:
-        """Drop baselines for games no longer live.
-
-        Only :meth:`_check_for_win` removes entries, and it only fires for games
-        seen to go final. A game that vanishes from the live list any other way
-        — postponed, dropped by the feed, or simply still live when the board
-        restarts — leaves its baseline behind forever, so on a board that runs
-        all season the dict grows without bound.
-
-        Call this from ``update()`` with the current live set, alongside the
-        equivalent pruning in :meth:`SmoothWeightedRotation.next_game`.
-        """
-        live_ids = {g.get("id") for g in live_games}
-        self._score_baselines = {
-            gid: baseline
-            for gid, baseline in self._score_baselines.items()
-            if gid in live_ids
-        }
-
-    def has_active_celebration(self) -> bool:
-        """True while a celebration is within its display window."""
-        celebration = self.active_celebration
-        return bool(celebration) and (
-            time.time() - celebration["started_at"] < self.celebration_duration
-        )
-
-    def _check_for_score(self, game: Dict) -> None:
-        """Compare a live game's score against its baseline and arm a
-        celebration when a celebratable team's score increases."""
-        if not self.celebration_enabled:
-            return
-        game_id = game.get("id")
-        if not game_id:
-            return
-        away = self._score_to_int(game.get("away_score"))
-        home = self._score_to_int(game.get("home_score"))
-        if away is None or home is None:
-            return
-
-        baseline = self._score_baselines.get(game_id)
-        # Always refresh the baseline: a first sighting must never celebrate (a
-        # game already in progress at boot would false-fire), and a decrement
-        # (VAR, a correction) just re-bases silently.
-        self._score_baselines[game_id] = {"away": away, "home": home}
-        if baseline is None:
-            return
-
-        away_delta = away - baseline["away"]
-        home_delta = home - baseline["home"]
-        if away_delta <= 0 and home_delta <= 0:
-            return
-
-        # One takeover per scoring sequence, where the sport has such a thing.
-        # The baseline is already advanced above, so nothing re-fires later.
-        if self.COALESCE_SCORING_SEQUENCE and self.has_active_celebration():
-            return
-
-        scored_side = None
-        points = 0
-        if away_delta > 0 and self._should_celebrate_for(game, "away"):
-            scored_side, points = "away", away_delta
-        if scored_side is None and home_delta > 0 and self._should_celebrate_for(
-            game, "home"
-        ):
-            scored_side, points = "home", home_delta
-        if scored_side is None:
-            return
-
-        self._start_celebration(
-            game,
-            "score",
-            scored_side=scored_side,
-            team_abbr=game.get(f"{scored_side}_abbr", ""),
-            away_score=away,
-            home_score=home,
-            points=points,
-        )
-
-    def _check_for_win(self, game: Dict) -> None:
-        """When a game we were tracking live goes final, arm a win celebration
-        if a favorite won. Fires at most once per game."""
-        if not self.celebration_enabled:
-            return
-        game_id = game.get("id")
-        if not game_id:
-            return
-        # Only celebrate wins for games we actually watched go live: one seen
-        # for the first time already-final (the board started after full time)
-        # has no baseline and must not fire.
-        if game_id not in self._score_baselines:
-            return
-        # Consume the baseline so this can only fire once.
-        self._score_baselines.pop(game_id, None)
-
-        away = self._score_to_int(game.get("away_score"))
-        home = self._score_to_int(game.get("home_score"))
-        if away is None or home is None:
-            return
-
-        if away > home:
-            winner_side = "away"
-        elif home > away:
-            winner_side = "home"
-        else:
-            return  # draw -> no win celebration
-
-        # Wins are gated strictly on favorites: every game ends, so the
-        # "no favorites -> celebrate all" score fallback would be far too noisy.
-        if not self._is_favorite(self._favorite_key(game, winner_side)):
-            return
-
-        self._start_celebration(
-            game,
-            "win",
-            scored_side=winner_side,
-            team_abbr=game.get(f"{winner_side}_abbr", ""),
-            away_score=away,
-            home_score=home,
-        )
-
-    def _start_celebration(
-        self,
-        game: Dict,
-        kind: str,
-        scored_side: str,
-        team_abbr: str,
-        away_score: int,
-        home_score: int,
-        points: int = 0,
-    ) -> None:
-        """Arm a celebration. ``scored_side`` ('away'/'home') is the side whose
-        score digit gets highlighted."""
-        phrase = (
-            self.win_phrase(team_abbr)
-            if kind == "win"
-            else self.score_phrase(points, team_abbr)
-        )
-
-        self.active_celebration = {
-            "kind": kind,
-            "game": dict(game),  # snapshot: survives the game leaving live_games
-            "scored_side": scored_side,
-            "team_abbr": team_abbr,
-            "away_score": away_score,
-            "home_score": home_score,
-            "started_at": time.time(),
-            "phrase": phrase,
-        }
-        # Pin focus to the involved game so the post-celebration scorebug
-        # resumes on it.
-        self.current_game = dict(game)
-        self.logger.info(
-            f"[Celebrations] {kind} armed: {phrase} "
-            f"[{game.get('away_abbr')} {away_score}-{home_score} {game.get('home_abbr')}]"
-        )
-
-    # ------------------------------------------------------------------
-    # Rendering
-    # ------------------------------------------------------------------
-
-    def _fit_font(self, draw, text: str, max_width: int, fonts: List):
-        """The first font whose rendered ``text`` fits ``max_width``, falling
-        back to the last (smallest) font."""
-        for font in fonts:
-            if draw.textlength(text, font=font) <= max_width - 2:
-                return font
-        return fonts[-1]
-
-    def _draw_celebration_layout(
-        self, celebration: Dict, force_clear: bool = False
-    ) -> None:
-        """Render the full-screen score/win takeover."""
-        if force_clear:
-            self.display_manager.clear()
-
-        display_width = (
-            self.display_manager.matrix.width
-            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
-            else self.display_width
-        )
-        display_height = (
-            self.display_manager.matrix.height
-            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
-            else self.display_height
-        )
-
-        elapsed = time.time() - celebration["started_at"]
-        game = celebration["game"]
-
-        # Background: a brief color flash for the first ~1.2s, then black.
-        bg = (0, 0, 0, 255)
-        if elapsed < 1.2 and int(elapsed / 0.2) % 2 == 0:
-            bg = (12, 12, 48, 255)
-        main_img = Image.new("RGBA", (display_width, display_height), bg)
-        overlay = Image.new("RGBA", (display_width, display_height), (0, 0, 0, 0))
-        draw = ImageDraw.Draw(overlay)
-
-        # Logos at the edges (best-effort: a logo failure must not blank the
-        # celebration).
-        try:
-            center_y = display_height // 2
-            home_logo = self._load_and_resize_logo(
-                game.get("home_id"), game.get("home_abbr"),
-                game.get("home_logo_path"), game.get("home_logo_url"),
-            )
-            away_logo = self._load_and_resize_logo(
-                game.get("away_id"), game.get("away_abbr"),
-                game.get("away_logo_path"), game.get("away_logo_url"),
-            )
-            if home_logo:
-                main_img.paste(
-                    home_logo,
-                    (display_width - home_logo.width + 2, center_y - home_logo.height // 2),
-                    home_logo,
-                )
-            if away_logo:
-                main_img.paste(
-                    away_logo, (-2, center_y - away_logo.height // 2), away_logo
-                )
-        except Exception as e:
-            self.logger.debug(f"[Celebrations] Logo load failed: {e}")
-
-        # Phrase across the top, shrunk to fit the panel width.
-        phrase = celebration["phrase"]
-        phrase_font = self._fit_font(
-            draw, phrase, display_width, [self.fonts["time"], self.fonts["status"]]
-        )
-        phrase_width = draw.textlength(phrase, font=phrase_font)
-        self._draw_text_with_outline(
-            draw, phrase, ((display_width - phrase_width) // 2, 1), phrase_font
-        )
-
-        # Score centered low, with the scoring/winning side's digit pulsing in a
-        # highlight color so the change reads at a glance.
-        away_text = str(celebration["away_score"])
-        home_text = str(celebration["home_score"])
-        score_font = self.fonts["score"]
-        segments = [
-            (away_text, celebration["scored_side"] == "away"),
-            ("-", False),
-            (home_text, celebration["scored_side"] == "home"),
-        ]
-        total_width = sum(draw.textlength(seg, font=score_font) for seg, _ in segments)
-        highlight = (255, 255, 0) if int(elapsed * 4) % 2 == 0 else (255, 170, 0)
-        x = (display_width - total_width) // 2
-        y = display_height - 14
-        for seg, is_highlight in segments:
-            color = highlight if is_highlight else (255, 255, 255)
-            self._draw_text_with_outline(draw, seg, (int(x), y), score_font, fill=color)
-            x += draw.textlength(seg, font=score_font)
-
-        main_img = Image.alpha_composite(main_img, overlay).convert("RGB")
-        self.display_manager.image = main_img
-        self.display_manager.update_display()
-
-    def display(self, force_clear: bool = False) -> bool:
-        """Render an active celebration as a full-screen takeover; otherwise
-        defer to the normal live scorebug."""
-        if not self.is_enabled:
-            return False
-        celebration = self.active_celebration
-        if celebration:
-            if self.has_active_celebration():
-                try:
-                    self._draw_celebration_layout(celebration, force_clear)
-                    return True
-                except Exception as e:
-                    self.logger.error(
-                        f"[Celebrations] Error drawing celebration: {e}", exc_info=True
-                    )
-                    # Disarm rather than retry: the same render would fail on
-                    # every frame for the rest of the window, logging a
-                    # traceback each time and leaving the scorebug off screen.
-                    self.active_celebration = None
-                    self.last_game_switch = time.time()
-            else:
-                self.active_celebration = None
-                # Reset the dwell so the scorebug resumes on the scoring/winning
-                # game for a full duration before rotation can move on.
-                self.last_game_switch = time.time()
-        return super().display(force_clear)

src/base_classes/sports/capabilities/rotation.py

@@ -1,246 +0,0 @@
-"""Live-rotation strategies — which live game to show next.
-
-The nine plugin copies grew three spellings of this, and the survey behind
-``docs/SPORTS_UNIFICATION.md`` found they are all the *same* Smooth Weighted
-Round-Robin algorithm in two shapes:
-
-* an **incremental picker** that holds weight state across calls and answers
-  "what next?" one game at a time (afl / nrl / soccer's ``_swrr_advance``), and
-* a **precomputed cycle** that returns a full list of game ids up front
-  (football / baseball / basketball's ``_build_weighted_schedule`` and hockey's
-  ``_build_rotation_schedule``, which differ only in loop shape).
-
-They agree *within* a cycle — SWRR is deterministic — and differ only at cycle
-boundaries, where the incremental form has no seam and the precomputed form
-restarts. That is a real behavioral difference, so core ships both rather than
-declaring a winner, and a plugin picks one by name:
-
-    self.rotation = get_rotation_strategy("swrr", weight_for=self._live_weight)
-
-Core never learns which sport is asking. A plugin with a genuinely novel
-ordering registers its own strategy instead of core growing a branch::
-
-    register_rotation_strategy("my-order", MyRotation)
-"""
-
-from __future__ import annotations
-
-from typing import Callable, Dict, List, Optional, Type
-
-
-def _game_id(game: Dict) -> Optional[str]:
-    """The rotation key for a game, or None if it has no usable id."""
-    return game.get("id")
-
-
-class RotationStrategy:
-    """Base class for live-rotation ordering.
-
-    Subclasses implement :meth:`schedule`; :meth:`next_game` has a working
-    default derived from it. Strategies whose natural shape is incremental
-    override :meth:`next_game` instead and derive :meth:`schedule`.
-
-    :param weight_for: callable mapping a game dict to a positive integer
-        weight — how many turns it gets per turn of a weight-1 game. Supplied by
-        the host so the *favorites* policy stays with the plugin and this module
-        stays free of any notion of what a favorite is. Defaults to equal
-        weights, which makes every strategy a plain round robin.
-    """
-
-    #: Name this strategy is registered under. Set by :func:`register_rotation_strategy`.
-    name: str = ""
-
-    #: Ceiling on a per-game weight. A cycle is ``sum(weights)`` long and each
-    #: step scans every game, so an unbounded weight — a misread config field,
-    #: say — would spin the display thread for an unbounded time. On a Pi that
-    #: stalls rendering outright, so the bound is clamped like the floor is.
-    MAX_WEIGHT = 16
-
-    def __init__(self, weight_for: Optional[Callable[[Dict], int]] = None):
-        self._weight_for = weight_for or (lambda game: 1)
-
-    def weights(self, games: List[Dict]) -> Dict[str, int]:
-        """``{game_id: weight}`` for games that have an id, in ``games`` order.
-
-        A weight below 1 is clamped up: a zero or negative weight would starve
-        a game out of the rotation entirely, which no caller means to express
-        and which would make ``total_weight`` collapse. It is clamped down at
-        :attr:`MAX_WEIGHT` for the reason documented there.
-        """
-        weights: Dict[str, int] = {}
-        for game in games:
-            gid = _game_id(game)
-            if gid is None:
-                continue
-            try:
-                weight = int(self._weight_for(game))
-            except (TypeError, ValueError):
-                weight = 1
-            weights[gid] = min(self.MAX_WEIGHT, max(1, weight))
-        return weights
-
-    def schedule(self, games: List[Dict]) -> List[str]:
-        """Game ids in display order for one cycle. Ids may repeat."""
-        raise NotImplementedError
-
-    def next_game(self, games: List[Dict]) -> Optional[Dict]:
-        """The next game to display, or None when there is nothing to show."""
-        order = self.schedule(games)
-        if not order:
-            return None
-        by_id = {gid: g for g in games if (gid := _game_id(g)) is not None}
-        return by_id.get(order[0])
-
-    def reset(self) -> None:
-        """Drop any accumulated state. Stateless strategies need do nothing."""
-
-
-class SimpleRotation(RotationStrategy):
-    """Plain round robin: every live game once per cycle, weights ignored.
-
-    The fallback for a plugin that wants strictly even rotation regardless of
-    favorites.
-    """
-
-    def schedule(self, games: List[Dict]) -> List[str]:
-        return [gid for g in games if (gid := _game_id(g)) is not None]
-
-
-class WeightedCycleRotation(RotationStrategy):
-    """Precomputed SWRR cycle — the football / baseball / basketball / hockey shape.
-
-    Returns a full cycle of ``sum(weights)`` ids with repeats spaced evenly
-    rather than clumped, highest weight scheduled first. When no game carries a
-    boost the cycle degenerates to a single pass in ``games`` order, which is
-    exactly the plain round robin it replaced.
-    """
-
-    def schedule(self, games: List[Dict]) -> List[str]:
-        weights = self.weights(games)
-        if not weights:
-            return []
-        total_weight = sum(weights.values())
-        if total_weight <= len(weights):
-            # No boost in effect — plain order, one pass. (Also the guard that
-            # keeps the loop below from being O(total_weight) for nothing.)
-            return list(weights)
-
-        current = {gid: 0 for gid in weights}
-        order: List[str] = []
-        for _ in range(total_weight):
-            for gid, weight in weights.items():
-                current[gid] += weight
-            picked = max(current, key=lambda gid: current[gid])
-            current[picked] -= total_weight
-            order.append(picked)
-        return order
-
-
-class SmoothWeightedRotation(RotationStrategy):
-    """Incremental SWRR — the afl / nrl / soccer shape.
-
-    Weight state persists across calls, so there is no fixed-length cycle and
-    therefore no clustering seam at a cycle boundary. A game seen for the first
-    time starts at weight 0 and receives its full weight on the next call, so a
-    favorite's game that has just gone live naturally wins the first pick after
-    it appears — "queued first on refresh" without a special-cased branch.
-
-    State for games no longer live is dropped on each call, so a long-running
-    board does not accumulate entries for finished games.
-    """
-
-    def __init__(self, weight_for: Optional[Callable[[Dict], int]] = None):
-        super().__init__(weight_for)
-        self._current: Dict[str, int] = {}
-
-    def reset(self) -> None:
-        self._current = {}
-
-    def next_game(self, games: List[Dict]) -> Optional[Dict]:
-        if not games:
-            return None
-        weights = self.weights(games)
-        if not weights:
-            return None
-
-        # Keep state only for games still live.
-        self._current = {
-            gid: value for gid, value in self._current.items() if gid in weights
-        }
-        for gid, weight in weights.items():
-            self._current[gid] = self._current.get(gid, 0) + weight
-
-        total_weight = sum(weights.values())
-        # Iterate in `games` order so ties break toward the feed's ordering,
-        # which is what the plugin copies did and what makes the no-boost case
-        # identical to a plain round robin.
-        ids_in_order = [gid for g in games if (gid := _game_id(g)) in weights]
-        best = max(ids_in_order, key=lambda gid: self._current[gid])
-        self._current[best] -= total_weight
-        return next(g for g in games if _game_id(g) == best)
-
-    def schedule(self, games: List[Dict]) -> List[str]:
-        """One cycle's worth of picks, without disturbing live state.
-
-        Derived by running the picker forward on a copy, so the returned order
-        is exactly what repeated :meth:`next_game` calls would produce from the
-        current state — callers can use it to preview or log the rotation
-        without perturbing it.
-        """
-        weights = self.weights(games)
-        if not weights:
-            return []
-        # type(self), not this class: a subclass that overrides next_game must
-        # be previewed through its own ordering, or the returned order is not
-        # the one repeated next_game calls would produce — which is exactly
-        # what this method promises.
-        preview = type(self)(self._weight_for)
-        preview._current = dict(self._current)
-        order: List[str] = []
-        for _ in range(sum(weights.values())):
-            picked = preview.next_game(games)
-            if picked is None:
-                break
-            order.append(_game_id(picked))
-        return order
-
-
-_REGISTRY: Dict[str, Type[RotationStrategy]] = {}
-
-
-def register_rotation_strategy(name: str, factory: Type[RotationStrategy]) -> None:
-    """Register a rotation strategy under ``name``.
-
-    When a plugin needs an ordering that core does not ship, it registers its
-    own here instead of core growing a sport-specific branch. Re-registering a
-    name replaces it, so a plugin may also override a built-in for itself.
-    """
-    if not name:
-        raise ValueError("rotation strategy name must be a non-empty string")
-    # Fail at registration, not at the first schedule() call several frames
-    # later, where the cause is no longer on the stack.
-    if not (isinstance(factory, type) and issubclass(factory, RotationStrategy)):
-        raise TypeError(
-            f"rotation strategy {name!r} must be a RotationStrategy subclass, "
-            f"got {factory!r}"
-        )
-    factory.name = name
-    _REGISTRY[name] = factory
-
-
-def get_rotation_strategy(
-    name: str, weight_for: Optional[Callable[[Dict], int]] = None
-) -> RotationStrategy:
-    """Build the strategy registered under ``name``.
-
-    Falls back to ``"simple"`` for an unknown name rather than raising: the name
-    arrives from user config, and a typo should cost the boost, not the
-    scoreboard.
-    """
-    factory = _REGISTRY.get(name) or _REGISTRY["simple"]
-    return factory(weight_for=weight_for)
-
-
-register_rotation_strategy("simple", SimpleRotation)
-register_rotation_strategy("weighted", WeightedCycleRotation)
-register_rotation_strategy("swrr", SmoothWeightedRotation)

src/cache_manager.py

@@ -39,10 +39,14 @@ from src.cache.cache_strategy import CacheStrategy
 from src.cache.cache_metrics import CacheMetrics
 from src.logging_config import get_logger
 
-# Canonical implementation lives in src.cache.disk_cache; re-exported here
-# because this module's docstring documents it and external code may import
-# it from either path.
-from src.cache.disk_cache import DateTimeEncoder
+class DateTimeEncoder(json.JSONEncoder):
+    """JSON encoder that serialises ``datetime`` objects as ISO-8601 strings."""
+
+    def default(self, obj):
+        """Return ISO-8601 string for datetime; delegate all other types to the base encoder."""
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        return super().default(obj)
 
 class CacheManager:
     """Manages caching of API responses to reduce API calls."""

src/common/README.md

@@ -99,6 +99,11 @@ Helpers for ensuring directory permissions and ownership are correct
 when running as a service (used by `CacheManager` to set up its
 persistent cache directory).
 
+## CLI Helpers (`cli.py`)
+
+Shared CLI argument parsing helpers used by `scripts/dev/*` and other
+command-line entry points.
+
 ## Best Practices
 
 1. **Use centralized logging**: Import from `src.logging_config` instead of creating loggers directly

src/common/api_helper.py

@@ -56,9 +56,7 @@ class APIHelper:
         
         # Default headers
         self.session.headers.update({
-            # Identifies the client and links to it: ESPN began 403ing bare
-            # custom tokens (and browser strings) around 2026-08-04.
-            'User-Agent': 'LEDMatrix/1.0 (+https://github.com/ChuckBuilds/LEDMatrix)',
+            'User-Agent': 'LEDMatrix-Common/1.0',
             'Accept': 'application/json',
             'Accept-Language': 'en-US,en;q=0.9',
             'Accept-Encoding': 'gzip, deflate, br',

src/common/cli.py

@@ -0,0 +1,111 @@
+"""
+LEDMatrix Common CLI
+
+Command-line interface for LEDMatrix Common utilities.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="LEDMatrix Common Utilities",
+        prog="ledmatrix-common"
+    )
+    
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+    
+    # Test command
+    test_parser = subparsers.add_parser('test', help='Test common utilities')
+    test_parser.add_argument('--display-width', type=int, default=128, help='Display width')
+    test_parser.add_argument('--display-height', type=int, default=64, help='Display height')
+    
+    # Validate command
+    validate_parser = subparsers.add_parser('validate', help='Validate configuration')
+    validate_parser.add_argument('config_file', help='Configuration file to validate')
+    
+    args = parser.parse_args()
+    
+    if args.command == 'test':
+        test_utilities(args.display_width, args.display_height)
+    elif args.command == 'validate':
+        validate_config(args.config_file)
+    else:
+        parser.print_help()
+
+
+def test_utilities(display_width: int, display_height: int):
+    """Test common utilities."""
+    print(f"Testing LEDMatrix Common utilities with {display_width}x{display_height} display")
+    
+    try:
+        from ledmatrix_common import LogoHelper, TextHelper, DisplayHelper, GameHelper, ConfigHelper
+        
+        # Test LogoHelper
+        print("Testing LogoHelper...")
+        logo_helper = LogoHelper(display_width, display_height)
+        print(f"Logo cache stats: {logo_helper.get_cache_stats()}")
+        
+        # Test TextHelper
+        print("Testing TextHelper...")
+        text_helper = TextHelper()
+        fonts = text_helper.load_fonts()
+        print(f"Loaded {len(fonts)} fonts")
+        
+        # Test DisplayHelper
+        print("Testing DisplayHelper...")
+        display_helper = DisplayHelper(display_width, display_height)
+        img = display_helper.create_base_image()
+        print(f"Created {img.size} base image")
+        
+        # Test GameHelper
+        print("Testing GameHelper...")
+        GameHelper()
+        print("GameHelper initialized")
+
+        # Test ConfigHelper
+        print("Testing ConfigHelper...")
+        ConfigHelper()
+        print("ConfigHelper initialized")
+        
+        print("All tests passed!")
+        
+    except ImportError as e:
+        print(f"Import error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Test error: {e}")
+        sys.exit(1)
+
+
+def validate_config(config_file: str):
+    """Validate configuration file."""
+    config_path = Path(config_file)
+    
+    if not config_path.exists():
+        print(f"Configuration file not found: {config_file}")
+        sys.exit(1)
+    
+    try:
+        from ledmatrix_common import ConfigHelper
+        
+        config_helper = ConfigHelper()
+        config = config_helper.load_config(config_path)
+        
+        if config:
+            print(f"Configuration loaded successfully from {config_file}")
+            print(f"Found {len(config)} top-level keys")
+        else:
+            print(f"Failed to load configuration from {config_file}")
+            sys.exit(1)
+            
+    except Exception as e:
+        print(f"Validation error: {e}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

src/common/logo_helper.py

@@ -188,13 +188,6 @@ class LogoHelper:
         """
         Normalize team abbreviation for consistent filename usage.
         
-        NOTE: this deliberately differs from
-        LogoDownloader.normalize_abbreviation (src/logo_downloader.py),
-        which replaces filesystem-unsafe characters (/ \\ : * ? " < > |)
-        but does not strip spaces. Plugins call the LogoDownloader
-        version; changing either implementation changes which logo
-        filenames resolve on existing installs.
-
         Args:
             team_abbr: Raw team abbreviation
             

src/common/scroll_helper.py

@@ -112,8 +112,7 @@ class ScrollHelper:
         
     def create_scrolling_image(self, content_items: list, 
                              item_gap: int = 32,
-                             element_gap: int = 16,
-                             lead_gap: Optional[int] = None) -> Image.Image:
+                             element_gap: int = 16) -> Image.Image:
         """
         Create a wide image containing all content items for scrolling.
         
@@ -121,19 +120,10 @@ class ScrollHelper:
             content_items: List of PIL Images to include in scroll
             item_gap: Gap between different items
             element_gap: Gap between elements within an item
-            lead_gap: Blank columns before the first item. Defaults to a full
-                display width, which makes a standalone ticker scroll in from
-                off-screen. Callers that loop many plugins back-to-back (Vegas
-                mode) pass a smaller value, since a full display width of black
-                reads as the panel being switched off at the start of every
-                cycle.
             
         Returns:
             PIL Image containing all content arranged horizontally
         """
-        if lead_gap is None:
-            lead_gap = self.display_width
-        lead_gap = max(0, int(lead_gap))
         if not content_items:
             # Create empty image if no content
             # Still set total_scroll_width to 0 to indicate no scrollable content
@@ -154,13 +144,13 @@ class ScrollHelper:
         total_width += element_gap * len(content_items)
         
         # Add initial gap before first item
-        total_width += lead_gap
+        total_width += self.display_width
         
         # Create the full scrolling image
         full_image = Image.new('RGB', (total_width, self.display_height), (0, 0, 0))
         
         # Position items
-        current_x = lead_gap  # Start with initial gap
+        current_x = self.display_width  # Start with initial gap
         
         for i, img in enumerate(content_items):
             # Paste the item image
@@ -349,72 +339,13 @@ class ScrollHelper:
         if not self.cached_image or self.cached_array is None:
             return None
         
+        # Use integer pixel positioning for high FPS scrolling (like stock ticker)
         start_x_int = int(self.scroll_position)
         end_x_int = start_x_int + self.display_width
         
-        # Integer positioning quantises motion to whole pixels, so the number of
-        # distinct frames per second equals the scroll speed in px/s, no matter
-        # how fast the loop renders. At 50px/s and 78fps that made 36% of frames
-        # identical: the extra frames cost work and bought nothing. Blending
-        # between the two neighbouring positions gives motion at the frame rate
-        # instead of the step rate.
-        if self.sub_pixel_scrolling:
-            fractional = self.scroll_position - start_x_int
-            if fractional > 0.0:
-                return self._blend_visible_portion(start_x_int, fractional)
-
+        # Fast integer pixel path (no interpolation - high frame rate provides smoothness)
         return self._get_visible_portion_integer(start_x_int, end_x_int)
     
-    def _blend_visible_portion(self, start_x: int, fractional: float) -> Image.Image:
-        """
-        Linear blend between the frames at ``start_x`` and ``start_x + 1``.
-
-        Implemented with numpy rather than scipy.ndimage.shift: scipy is not
-        installed on the target devices (HAS_SCIPY is False there), which is why
-        the pre-existing sub-pixel path was dead code — get_visible_portion never
-        consulted the flag, and the scipy fallback would not have interpolated
-        anyway.
-
-        Args:
-            start_x: Left column of the earlier of the two frames
-            fractional: How far between the two, in [0, 1)
-
-        Returns:
-            The blended frame
-        """
-        width = self.display_width
-        strip_width = self.cached_array.shape[1]
-
-        if start_x + width + 1 <= strip_width:
-            # Slice the backing array directly. Going via
-            # _get_visible_portion_integer would build two PIL images only for
-            # them to be converted straight back to arrays, which measured 15x
-            # the cost of the integer path.
-            near = self.cached_array[:, start_x:start_x + width]
-            far = self.cached_array[:, start_x + 1:start_x + 1 + width]
-        else:
-            # Close enough to the end that one of the slices wraps; let the
-            # integer path handle that and pay the conversion. Continuous mode
-            # extends the strip before reaching here, so this is the rare case.
-            near = np.asarray(
-                self._get_visible_portion_integer(start_x, start_x + width))
-            far = np.asarray(
-                self._get_visible_portion_integer(start_x + 1, start_x + 1 + width))
-
-        # Fixed-point rather than float32: integer multiply-add on uint16 is
-        # markedly faster than float maths on the Pi's ARM cores, and 8 bits of
-        # weight is finer than the panel can show.
-        weight = int(fractional * 256.0)
-        blended = (
-            (near.astype(np.uint16) * (256 - weight)
-             + far.astype(np.uint16) * weight) >> 8
-        ).astype(np.uint8)
-
-        return Image.frombytes(
-            'RGB', (width, self.display_height),
-            np.ascontiguousarray(blended).tobytes()
-        )
-    
     def _get_visible_portion_integer(self, start_x: int, end_x: int) -> Image.Image:
         """Fast integer pixel extraction (no interpolation).
 
@@ -707,128 +638,6 @@ class ScrollHelper:
         """
         return self.scroll_complete
     
-    def append_content(self, content_items: list,
-                       item_gap: int = 32,
-                       element_gap: int = 0) -> bool:
-        """
-        Append items to the right of the existing strip, preserving scroll state.
-
-        Lets a caller keep one continuous strip instead of replacing it. Vegas
-        mode uses this so the next group of plugins scrolls in from the right
-        rather than the strip being swapped out underneath the viewer — a swap
-        shows as a flash and a hard cut to already-full-screen content.
-
-        ``scroll_position`` and ``total_distance_scrolled`` are untouched, so
-        motion continues uninterrupted; only the strip gets longer. Because
-        completion is measured against ``total_scroll_width``, extending the
-        strip also defers completion, which is the intent.
-
-        Args:
-            content_items: Images to append, in order
-            item_gap: Gap between appended items, and between the existing
-                content and the first appended item
-            element_gap: Extra gap after each item, mirroring
-                create_scrolling_image
-
-        Returns:
-            True if content was appended
-        """
-        if not content_items:
-            return False
-
-        if self.cached_image is None or self.cached_array is None:
-            # Nothing to extend yet — this is just the first build.
-            self.create_scrolling_image(
-                content_items, item_gap=item_gap, element_gap=element_gap, lead_gap=0)
-            return True
-
-        gap = max(0, item_gap)
-        addition_width = (
-            sum(img.width for img in content_items)
-            + gap * len(content_items)          # one leading gap per item
-            + element_gap * len(content_items)
-        )
-
-        addition = Image.new('RGB', (addition_width, self.display_height), (0, 0, 0))
-        x = 0
-        for img in content_items:
-            x += gap                            # separate from whatever precedes
-            addition.paste(img, (x, 0))
-            x += img.width + element_gap
-
-        # numpy concatenate then one conversion back, rather than allocating a
-        # full-width PIL image and pasting twice: the strip can be tens of
-        # thousands of columns wide and this runs on the render path.
-        self.cached_array = np.concatenate(
-            (self.cached_array, np.array(addition)), axis=1)
-        self.cached_image = Image.fromarray(self.cached_array)
-        self.total_scroll_width = self.cached_image.width
-        self.scroll_complete = False
-
-        self.logger.info(
-            "Appended %d item(s) (%dpx) to scroll strip: now %dpx, position %.0f",
-            len(content_items), addition_width, self.total_scroll_width,
-            self.scroll_position
-        )
-        return True
-
-    def drop_scrolled_prefix(self, keep_before: int = 0) -> int:
-        """
-        Discard columns that have already scrolled past, to bound memory.
-
-        A continuously extended strip would otherwise grow without limit. All
-        the positional state is shifted by the amount removed so the visible
-        frame and the completion arithmetic are unchanged:
-        ``total_distance_scrolled`` and ``total_scroll_width`` both shrink by the
-        same amount, preserving their difference.
-
-        Args:
-            keep_before: Columns to retain behind the current position, as a
-                safety margin against a caller reading slightly behind it
-
-        Returns:
-            Number of columns actually removed
-        """
-        if self.cached_image is None or self.cached_array is None:
-            return 0
-
-        # While the viewport wraps, get_visible_portion fills its right-hand side
-        # from the *head* of the strip, so trimming the head would change what
-        # is on screen. Continuous mode extends before ever reaching that state;
-        # refusing here keeps "trimming is invisible" true unconditionally.
-        if self.scroll_position + self.display_width > self.cached_image.width:
-            return 0
-
-        cut = int(self.scroll_position) - max(0, keep_before)
-        if cut <= 0:
-            return 0
-        # Never trim so far that the remaining strip is narrower than the
-        # viewport, or get_visible_portion has nothing to slice.
-        cut = min(cut, max(0, self.cached_image.width - self.display_width))
-        if cut <= 0:
-            return 0
-
-        # .copy() so the original buffer is released rather than kept alive by
-        # a numpy view.
-        self.cached_array = self.cached_array[:, cut:].copy()
-        self.cached_image = Image.fromarray(self.cached_array)
-        self.total_scroll_width = self.cached_image.width
-        self.scroll_position -= cut
-        self.total_distance_scrolled = max(0.0, self.total_distance_scrolled - cut)
-
-        self.logger.debug(
-            "Dropped %dpx of scrolled strip: now %dpx, position %.0f",
-            cut, self.total_scroll_width, self.scroll_position
-        )
-        return cut
-
-    def remaining_unscrolled(self) -> int:
-        """Columns of strip still to the right of the viewport."""
-        if self.cached_image is None:
-            return 0
-        return max(0, self.total_scroll_width - int(self.scroll_position)
-                   - self.display_width)
-
     def reset_scroll(self) -> None:
         """
         Reset scroll position to beginning.

src/common/sports_scroll.py

@@ -1,485 +0,0 @@
-"""Shared scroll-display scaffolding for the sports scoreboards.
-
-Ten plugins ship a `scroll_display.py`. A method-level comparison of the eight
-that share a shape (f1 and ufc are genuine forks) found a sharp split, and this
-module is drawn along it rather than around all of it:
-
-* The **orchestration layer is converged** — ``get_all_vegas_content_items`` is
-  byte-identical in all eight, and ``clear_all``, ``get_scroll_info``,
-  ``get_dynamic_duration``, ``is_complete`` and ``display_frame`` are 96-100%
-  similar. That is what lives here.
-* The **content layer has genuinely diverged** — ``prepare_scroll_content`` has
-  eight distinct bodies across eight plugins (145 lines, 53% similarity at
-  worst) and ``_load_separator_icons`` seven (6% at worst). Those build each
-  sport's game cards and icon strip; they are *not* drift to be merged but
-  per-sport rendering. They stay override points here, permanently.
-
-Promoting the content layer would be exactly the mistake
-``docs/SPORTS_UNIFICATION.md`` warns against — merging on the intuition that
-same-named methods are the same method. Same name, different job.
-
-The one behavior this module adds over the plugin copies is native support for
-``global_config['target_fps']``: the bundled copies hardcode ~100 FPS via
-``scroll_delay=0.01`` and never consult the global smooth-scrolling target. A
-plugin inheriting from here gets it for free.
-
-Usage::
-
-    class HockeyScrollDisplay(SportsScrollDisplay):
-        SCROLL_LEAGUE_KEYS = ("nhl", "ncaa_mens", "ncaam_hockey")
-
-        def prepare_scroll_content(self, games, game_type, leagues, rankings=None):
-            ...                      # build this sport's cards
-
-    class HockeyScrollDisplayManager(SportsScrollDisplayManager):
-        display_class = HockeyScrollDisplay
-"""
-
-from __future__ import annotations
-
-import logging
-import time
-from typing import Any, Dict, List, Optional
-
-from PIL import Image
-
-from src.common.scroll_helper import ScrollHelper
-
-logger = logging.getLogger(__name__)
-
-#: Defaults every copy agreed on. A subclass overrides
-#: :meth:`SportsScrollDisplay.scroll_settings_defaults` to change them —
-#: the soccer lineage uses a 24px gap and min/max duration keys instead.
-DEFAULT_SCROLL_SETTINGS: Dict[str, Any] = {
-    "scroll_speed": 50.0,
-    "scroll_delay": 0.01,
-    "gap_between_games": 48,
-    "show_league_separators": True,
-    "dynamic_duration": True,
-}
-
-#: Bounds on the px/second -> px/frame conversion, applied before the helper
-#: sees the value. FPS is *not* clamped here — ScrollHelper.set_target_fps
-#: already does that, and a second copy of the range would drift from it.
-MIN_PIXELS_PER_FRAME = 0.1
-MAX_PIXELS_PER_FRAME = 5.0
-
-#: Pacing to assume when scroll_delay is 0, i.e. the plugin has not set one.
-ASSUMED_FPS_WHEN_UNPACED = 100.0
-
-
-class SportsScrollDisplay:
-    """One scrolling strip of game cards.
-
-    Subclasses supply the content (:meth:`prepare_scroll_content`) and,
-    optionally, the per-sport league ladder and separator icons. Everything
-    else — helper configuration, frame pumping, completion, state — is here.
-    """
-
-    #: Config keys to walk when looking for per-league ``scroll_settings``,
-    #: most-preferred first. A sport's own league names, which is the *only*
-    #: reason the eight copies of ``_get_scroll_settings`` differ. Empty means
-    #: the plugin has no per-league scroll settings.
-    SCROLL_LEAGUE_KEYS: tuple = ()
-
-    #: Config block holding scroll settings when the plugin keeps them in one
-    #: place rather than per league (the afl/nrl/soccer shape).
-    SCROLL_CONFIG_KEY: Optional[str] = None
-
-    def __init__(
-        self,
-        display_manager,
-        config: Dict[str, Any],
-        custom_logger: Optional[logging.Logger] = None,
-        global_config: Optional[Dict[str, Any]] = None,
-    ):
-        """
-        :param display_manager: the core display manager
-        :param config: the plugin's configuration
-        :param custom_logger: the plugin's logger, so scroll lines are attributed
-        :param global_config: the LEDMatrix global config — the source of
-            ``target_fps``. Optional so an older caller that does not pass it
-            keeps working at the config-derived pacing.
-        """
-        self.display_manager = display_manager
-        self.config = config
-        self.logger = custom_logger or logger
-        self.global_config = global_config or {}
-
-        if getattr(display_manager, "matrix", None) is not None:
-            self.display_width = display_manager.matrix.width
-            self.display_height = display_manager.matrix.height
-        else:
-            self.display_width = getattr(display_manager, "width", 128)
-            self.display_height = getattr(display_manager, "height", 32)
-
-        self.scroll_helper = ScrollHelper(
-            self.display_width, self.display_height, self.logger
-        )
-        self._configure_scroll_helper()
-
-        self._logo_cache: Dict[str, Image.Image] = {}
-        self._separator_icons: Dict[str, Image.Image] = {}
-        self._load_separator_icons()
-
-        self._current_games: List[Dict] = []
-        self._current_game_type: str = ""
-        self._current_leagues: List[str] = []
-        self._vegas_content_items: List[Image.Image] = []
-        self._is_scrolling = False
-        self._scroll_start_time: Optional[float] = None
-        self._last_log_time: float = 0
-        self._log_interval: float = 5.0
-        self._frame_count: int = 0
-        self._fps_sample_start: float = time.time()
-
-    # ------------------------------------------------------------------
-    # Override points
-    # ------------------------------------------------------------------
-
-    def prepare_scroll_content(
-        self,
-        games: List[Dict],
-        game_type: str,
-        leagues: List[str],
-        rankings_cache: Optional[Dict[str, int]] = None,
-    ) -> bool:
-        """Render ``games`` into one wide image and hand it to the scroll helper.
-
-        **Per-sport by nature, not by drift** — the eight plugin copies have
-        eight different bodies because each draws its own card. Implementations
-        build the strip, hand it over with
-        ``self.scroll_helper.set_scrolling_image(...)`` (or
-        ``create_scrolling_image(...)`` from a list of cards), and record
-        ``self._current_games`` / ``_current_game_type`` / ``_current_leagues``.
-
-        :returns: True when there is content to scroll.
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement prepare_scroll_content(); "
-            "it builds this sport's game cards and is not shared code."
-        )
-
-    def _load_separator_icons(self) -> None:
-        """Populate ``self._separator_icons``. Per-sport; no-op by default."""
-
-    def scroll_settings_defaults(self) -> Dict[str, Any]:
-        """The baseline scroll settings before any config is applied."""
-        defaults = dict(DEFAULT_SCROLL_SETTINGS)
-        defaults["game_card_width"] = self.display_width
-        return defaults
-
-    # ------------------------------------------------------------------
-    # Settings
-    # ------------------------------------------------------------------
-
-    def _get_scroll_settings(self, league: Optional[str] = None) -> Dict[str, Any]:
-        """Resolve scroll settings: defaults, then the most specific override.
-
-        Precedence: the named ``league``, then each entry of
-        :attr:`SCROLL_LEAGUE_KEYS` in order, then :attr:`SCROLL_CONFIG_KEY`.
-        The eight plugin copies implement exactly this and differ only in which
-        league names they walk — which is why the ladder is data here rather
-        than a body per sport.
-        """
-        settings = self.scroll_settings_defaults()
-
-        candidates: List[str] = []
-        if league:
-            candidates.append(league)
-        candidates.extend(self.SCROLL_LEAGUE_KEYS)
-        for key in candidates:
-            override = (self.config.get(key) or {}).get("scroll_settings")
-            if override:
-                return {**settings, **override}
-
-        if self.SCROLL_CONFIG_KEY:
-            override = self.config.get(self.SCROLL_CONFIG_KEY) or {}
-            if override:
-                return {**settings, **override}
-        return settings
-
-    def _resolve_target_fps(self) -> Optional[float]:
-        """The global smooth-scrolling FPS target, or None to keep config pacing.
-
-        Coerced before use: a malformed value in the global config must degrade
-        to the existing ``scroll_delay`` pacing, never raise on a display path.
-        """
-        raw = self.global_config.get("target_fps") or self.global_config.get(
-            "scroll_target_fps"
-        )
-        try:
-            return float(raw) if raw is not None else None
-        except (TypeError, ValueError):
-            self.logger.debug("Ignoring unusable target_fps: %r", raw)
-            return None
-
-    def _coerce_float(self, value: Any, default: float) -> float:
-        """A usable float from config, or ``default``.
-
-        ``dict.get(key, default)`` only helps when the key is *absent*; a key
-        present with ``null`` or a string returns that value verbatim and blows
-        up in the arithmetic below — inside ``__init__``, so the whole display
-        fails to construct.
-        """
-        if value is None:
-            return default
-        try:
-            return float(value)
-        except (TypeError, ValueError):
-            self.logger.warning(
-                "Ignoring unusable scroll setting %r; using %s", value, default
-            )
-            return default
-
-    def _configure_scroll_helper(self) -> None:
-        """Apply config to the scroll helper. Safe to call again after a change."""
-        settings = self._get_scroll_settings()
-
-        scroll_speed = self._coerce_float(settings.get("scroll_speed"), 50.0)
-        scroll_delay = self._coerce_float(settings.get("scroll_delay"), 0.01)
-        dynamic_duration = bool(settings.get("dynamic_duration", True))
-
-        self.scroll_helper.set_scroll_delay(scroll_delay)
-        self.scroll_helper.set_dynamic_duration_settings(
-            enabled=dynamic_duration,
-            min_duration=settings.get("min_duration", 30),
-            max_duration=settings.get("max_duration", 600),
-            buffer=0.2,  # ensure the strip clears the panel completely
-        )
-        # Frame-based scrolling: motion advances per rendered frame rather than
-        # per wall-clock second, which is what makes the pacing stable.
-        self.scroll_helper.set_frame_based_scrolling(True)
-
-        # Config states speed in px/second; frame-based mode wants px/frame.
-        if scroll_delay > 0:
-            pixels_per_frame = scroll_speed * scroll_delay
-        else:
-            pixels_per_frame = scroll_speed / ASSUMED_FPS_WHEN_UNPACED
-        pixels_per_frame = max(
-            MIN_PIXELS_PER_FRAME, min(MAX_PIXELS_PER_FRAME, pixels_per_frame)
-        )
-        self.scroll_helper.set_scroll_speed(pixels_per_frame)
-
-        effective_pps = (
-            pixels_per_frame / scroll_delay
-            if scroll_delay > 0
-            else pixels_per_frame * ASSUMED_FPS_WHEN_UNPACED
-        )
-        self.logger.info(
-            f"ScrollHelper configured: {pixels_per_frame:.2f} px/frame, "
-            f"delay={scroll_delay}s (effective {effective_pps:.1f} px/s from "
-            f"{scroll_speed} px/s config), dynamic_duration={dynamic_duration}"
-        )
-
-        # The reason this module exists upstream: the bundled copies hardcode
-        # ~100 FPS via scroll_delay and never consult the global target.
-        # No hasattr guard here, unlike the plugin copies: they probe because
-        # they may run against an older core, whereas this module ships in the
-        # same release as the ScrollHelper it calls. The helper clamps.
-        target_fps = self._resolve_target_fps()
-        if target_fps:
-            self.scroll_helper.set_target_fps(target_fps)
-            self.logger.info(f"Target FPS set to {target_fps}")
-
-    # ------------------------------------------------------------------
-    # Frame pumping
-    # ------------------------------------------------------------------
-
-    def display_scroll_frame(self) -> bool:
-        """Advance and render one frame.
-
-        :returns: True if a frame was drawn; False when there is no content or
-            the frame could not be rendered.
-        """
-        if not self.scroll_helper.cached_image:
-            return False
-
-        try:
-            # Inside the try, not before it: advancing the position and cropping
-            # the visible slice are as capable of raising as the display push,
-            # and the promise below is that no frame failure reaches the
-            # plugin's loop.
-            self.scroll_helper.update_scroll_position()
-            visible = self.scroll_helper.get_visible_portion()
-            if not visible:
-                return False
-
-            self.display_manager.image = visible
-            self.display_manager.update_display()
-            self._frame_count += 1
-            self.scroll_helper.log_frame_rate()
-            self._log_scroll_progress()
-        except Exception:
-            # A display failure must not propagate into the plugin's loop.
-            self.logger.exception("Error displaying scroll frame")
-            return False
-        return True
-
-    def _log_scroll_progress(self) -> None:
-        """Emit a throttled progress line."""
-        now = time.time()
-        if now - self._last_log_time < self._log_interval:
-            return
-        self._last_log_time = now
-        elapsed = now - self._fps_sample_start
-        fps = self._frame_count / elapsed if elapsed > 0 else 0.0
-        self.logger.debug(
-            f"Scrolling {len(self._current_games)} {self._current_game_type} "
-            f"game(s) at {fps:.1f} FPS"
-        )
-
-    def is_scroll_complete(self) -> bool:
-        """True when the strip has scrolled fully past the panel."""
-        return self.scroll_helper.is_scroll_complete()
-
-    def reset_scroll(self) -> None:
-        """Return the strip to its starting position, keeping the content."""
-        self.scroll_helper.reset_scroll()
-        self._frame_count = 0
-        self._fps_sample_start = time.time()
-        self.logger.debug("Scroll position reset")
-
-    def clear(self) -> None:
-        """Drop cached content and reset tracking state."""
-        self.scroll_helper.clear_cache()
-        self._current_games = []
-        self._current_game_type = ""
-        self._current_leagues = []
-        self._vegas_content_items = []
-        self._is_scrolling = False
-        self._scroll_start_time = None
-        self.logger.debug("Scroll display cleared")
-
-    # ------------------------------------------------------------------
-    # Introspection
-    # ------------------------------------------------------------------
-
-    def get_dynamic_duration(self) -> int:
-        """How long this content needs to scroll fully, in seconds."""
-        return self.scroll_helper.get_dynamic_duration()
-
-    def has_cached_content(self) -> bool:
-        """Whether content is prepared and ready to scroll."""
-        return bool(self.scroll_helper.cached_image)
-
-    def get_current_game_count(self) -> int:
-        return len(self._current_games)
-
-    def get_current_leagues(self) -> List[str]:
-        return list(self._current_leagues)
-
-    def get_scroll_info(self) -> Dict[str, Any]:
-        """Helper state plus this display's tracking state, for logging/debug."""
-        info = self.scroll_helper.get_scroll_info()
-        info.update(
-            {
-                "game_count": len(self._current_games),
-                "game_type": self._current_game_type,
-                "leagues": self._current_leagues,
-                "is_scrolling": self._is_scrolling,
-            }
-        )
-        return info
-
-
-class SportsScrollDisplayManager:
-    """One :class:`SportsScrollDisplay` per game type ('live'/'recent'/'upcoming').
-
-    Subclasses set :attr:`display_class`; everything else was near-identical
-    across the eight plugin copies.
-    """
-
-    #: The SportsScrollDisplay subclass to instantiate per game type.
-    display_class = SportsScrollDisplay
-
-    def __init__(
-        self,
-        display_manager,
-        config: Dict[str, Any],
-        custom_logger: Optional[logging.Logger] = None,
-        global_config: Optional[Dict[str, Any]] = None,
-    ):
-        self.display_manager = display_manager
-        self.config = config
-        self.logger = custom_logger or logger
-        self.global_config = global_config or {}
-        self._scroll_displays: Dict[str, SportsScrollDisplay] = {}
-        # "" rather than None, matching SportsScrollDisplay's own empty value —
-        # both are falsy, so `game_type or self._current_game_type` behaved
-        # either way, but two spellings of "nothing active" across two classes
-        # is a trap for anyone comparing state between them.
-        self._current_game_type: str = ""
-
-    def get_scroll_display(self, game_type: str) -> SportsScrollDisplay:
-        """The display for ``game_type``, created on first use."""
-        if game_type not in self._scroll_displays:
-            self._scroll_displays[game_type] = self.display_class(
-                self.display_manager,
-                self.config,
-                self.logger,
-                global_config=self.global_config,
-            )
-        return self._scroll_displays[game_type]
-
-    def prepare_and_display(
-        self,
-        games: List[Dict],
-        game_type: str,
-        leagues: List[str],
-        rankings_cache: Optional[Dict[str, int]] = None,
-    ) -> bool:
-        """Build content for ``game_type`` and make it the active strip."""
-        scroll_display = self.get_scroll_display(game_type)
-        try:
-            success = scroll_display.prepare_scroll_content(
-                games, game_type, leagues, rankings_cache
-            )
-        except Exception:
-            # prepare_scroll_content is subclass-implemented and builds cards
-            # straight from feed data, which is exactly where this PR's other
-            # crashes came from. One sport's bad payload must not take down the
-            # shared orchestration for the others.
-            self.logger.exception(
-                "Error preparing scroll content for game_type=%s", game_type
-            )
-            return False
-        if success:
-            self._current_game_type = game_type
-        return success
-
-    def display_frame(self, game_type: Optional[str] = None) -> bool:
-        """Advance the active strip (or a named one) by one frame."""
-        game_type = game_type or self._current_game_type
-        if not game_type:
-            return False
-        scroll_display = self._scroll_displays.get(game_type)
-        if scroll_display is None:
-            return False
-        return scroll_display.display_scroll_frame()
-
-    def is_complete(self, game_type: Optional[str] = None) -> bool:
-        """True when the strip has finished — including when there isn't one,
-        so a caller waiting on completion is never wedged."""
-        game_type = game_type or self._current_game_type
-        if not game_type:
-            return True
-        scroll_display = self._scroll_displays.get(game_type)
-        if scroll_display is None:
-            return True
-        return scroll_display.is_scroll_complete()
-
-    def clear_all(self) -> None:
-        """Clear every display and forget which one was active."""
-        for scroll_display in self._scroll_displays.values():
-            scroll_display.clear()
-        self._current_game_type = ""
-
-    def get_all_vegas_content_items(self) -> List[Image.Image]:
-        """Every display's Vegas items, for splicing into the marquee."""
-        items: List[Image.Image] = []
-        for scroll_display in self._scroll_displays.values():
-            vegas_items = getattr(scroll_display, "_vegas_content_items", None)
-            if vegas_items:
-                items.extend(vegas_items)
-        return items

src/config_manager.py

@@ -449,6 +449,10 @@ class ConfigManager:
         """Get display configuration."""
         return self.config.get('display', {})
 
+    def get_clock_config(self) -> Dict[str, Any]:
+        """Get clock configuration."""
+        return self.config.get('clock', {})
+
     def get_config(self) -> Dict[str, Any]:
         """Get the full configuration dictionary.
         

src/display_manager.py

@@ -186,14 +186,8 @@ class DisplayManager:
         self.config = config or {}
         self._force_fallback = force_fallback
         self._suppress_test_pattern = suppress_test_pattern
-        # Per-thread capture state. update_display() and clear() skip hardware
-        # writes while the *calling* thread is capturing content off-screen.
-        #
-        # Thread-local rather than a plain flag because Vegas mode prepares
-        # upcoming content on a background thread: a shared flag set there would
-        # suppress the render loop's own frame pushes for the duration, freezing
-        # the panel exactly when the point was to avoid a freeze.
-        self._capture_state = threading.local()
+        # When True, update_display() and clear() skip hardware writes (used during off-screen content capture)
+        self._capture_mode_active = False
         # Double-sided mode state (resolved in _setup_matrix). When disabled,
         # the logical image is blitted to the matrix unchanged.
         self._double_sided = None  # dict {copies, axis, logical_width, logical_height} or None
@@ -526,15 +520,6 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error drawing test pattern: {e}", exc_info=True)
 
-    @property
-    def _capture_mode_active(self) -> bool:
-        """True while the calling thread is capturing content off-screen."""
-        return getattr(self._capture_state, 'active', False)
-
-    @_capture_mode_active.setter
-    def _capture_mode_active(self, value: bool) -> None:
-        self._capture_state.active = bool(value)
-
     @contextmanager
     def capture_mode(self):
         """Suppress hardware output during off-screen content capture.
@@ -551,59 +536,6 @@ class DisplayManager:
         finally:
             self._capture_mode_active = False
 
-    @contextmanager
-    def render_size(self, width: int, height: Optional[int] = None):
-        """Temporarily present a smaller logical canvas to plugins.
-
-        Plugins lay out against ``display_manager.matrix.width`` (and the
-        ``width``/``height`` properties, which defer to it), so the only way to
-        get a *narrower layout* rather than a cropped one is to tell the plugin
-        the screen is narrower while it renders. Trimming after the fact cannot
-        fix a forecast spread across five columns or a progress bar drawn at
-        100% width — those need the plugin to make different layout decisions.
-
-        Vegas mode uses this so a plugin can occupy a fraction of a wide panel
-        and still look deliberately composed. Reuses the same _LogicalMatrix
-        indirection that double-sided mode relies on, so plugins see a
-        consistent size from every accessor.
-
-        Only meaningful inside :meth:`capture_mode` — this swaps the shared
-        image buffer, so the render loop must not be writing to it concurrently.
-
-        Args:
-            width: Logical width to report, clamped to at least 1 and to the
-                real panel width (a larger canvas would overflow the hardware).
-            height: Logical height, defaulting to the current height.
-        """
-        real_matrix = self.matrix
-        prev_image = getattr(self, 'image', None)
-        prev_draw = getattr(self, 'draw', None)
-
-        current_w = self.width
-        current_h = self.height
-        target_w = max(1, min(int(width), current_w))
-        target_h = max(1, min(int(height) if height else current_h, current_h))
-
-        if target_w == current_w and target_h == current_h:
-            # Nothing to do; avoid pointless wrapping and buffer churn.
-            yield
-            return
-
-        try:
-            if real_matrix is not None:
-                self.matrix = _LogicalMatrix(real_matrix, target_w, target_h)
-            # With no hardware, the width/height properties fall through to
-            # self.image, so swapping the buffer below is enough on its own.
-            self.image = Image.new('RGB', (target_w, target_h))
-            self.draw = ImageDraw.Draw(self.image)
-            yield
-        finally:
-            self.matrix = real_matrix
-            if prev_image is not None:
-                self.image = prev_image
-            if prev_draw is not None:
-                self.draw = prev_draw
-
     def _composite_double_sided(self):
         """Tile the logical screen across the full physical chain.
 

src/element_style.py

@@ -1,628 +0,0 @@
-"""
-Shared per-element style resolution for plugins (the x-style-elements system).
-
-Plugins expose user-customizable text styling — font, size, color, and x/y
-pixel offsets per named element — through their ``config_schema.json``. Two
-declaration forms exist in the plugin ecosystem:
-
-- The compact ``x-style-elements`` map on the ``customization`` object
-  (of-the-day is the reference). ``expand_style_elements()`` turns it into
-  the full per-element property blocks the web-UI config form renders.
-- The manual ``customization`` block: hand-written per-element objects with
-  ``font`` / ``font_size`` / ``text_color`` defaults (the scoreboards,
-  ledmatrix-music). No expansion needed — the defaults are read as-is.
-
-At render time a plugin builds an ``ElementStyleResolver`` from its config
-and the schema-file defaults, then asks for each element's resolved style::
-
-    from src.element_style import ElementStyleResolver, defaults_from_schema_file
-
-    resolver = ElementStyleResolver(config, defaults_from_schema_file(schema_path))
-    title = resolver.style('title_text', classic_font='PressStart2P-Regular.ttf',
-                           classic_size=8, classic_color=(255, 255, 255))
-    # title.font (PIL font / freetype.Face), title.color (RGB tuple),
-    # title.offset ((dx, dy)), title.user_forced, title.user_forced_color
-
-The central subtlety is what "the user set it" means. The web UI's save flow
-(``schema_manager.merge_with_defaults``) writes the FULL schema-default
-object into ``config.json`` on every save, whether or not the user touched
-the styling section — so a value merely being *present* in config is not an
-override. A value only counts as user-forced when it genuinely differs from
-the schema default for that element. When nothing is forced, ``style()``
-returns exactly the ``classic_*`` values the caller passes (the plugin's
-pre-customization styling), so an untouched config renders byte-identically
-to the classic code path. Note the classic values and the schema defaults
-may legitimately differ (e.g. football's status_text: schema declares 4x6,
-the classic loader fell back to PressStart) — the schema default is the
-override *reference*, the classic values are the *fallback*.
-
-``style()`` never raises: any malformed config value degrades to the classic
-style with a logged warning. Font faces are cached module-wide by
-(resolved path, size), and font files resolve independently of the caller's
-cwd (cwd ``assets/fonts/`` first for compatibility, then the core install
-root derived from this module's own location).
-"""
-
-import copy
-import json
-import logging
-import os
-from dataclasses import dataclass
-from typing import Any, Dict, Optional, Tuple, Union
-
-from PIL import ImageFont
-
-try:
-    import freetype
-except ImportError:  # pragma: no cover - freetype ships with the core
-    freetype = None
-
-logger = logging.getLogger(__name__)
-
-# Core install root (the directory that contains src/ and assets/fonts/),
-# derived from this file so fonts resolve regardless of the caller's cwd.
-_CORE_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-_FONTS_SUBDIR = os.path.join('assets', 'fonts')
-
-# Last-resort font when a requested file can't be found or loaded.
-_FALLBACK_FONT_NAME = 'PressStart2P-Regular.ttf'
-
-# (resolved absolute path, size) -> loaded font face. BDF faces are stateful
-# in principle, but the core's own FontManager shares faces the same way.
-_font_cache: Dict[Tuple[str, int], Any] = {}
-
-# Config keys a style element block carries, in schema/UI order.
-_STYLE_KEYS = ('font', 'font_size', 'text_color')
-
-
-@dataclass(frozen=True)
-class ElementStyle:
-    """A fully resolved style for one named element."""
-
-    font: Any                       # PIL ImageFont or freetype.Face
-    color: Tuple[int, int, int]     # resolved RGB
-    offset: Tuple[int, int]         # user layout (x, y) offset, default (0, 0)
-    font_name: str                  # resolved font filename
-    font_size: int                  # resolved pixel size
-    user_forced: bool               # font or size genuinely overridden
-    user_forced_color: bool         # color genuinely overridden
-
-
-# ---------------------------------------------------------------------------
-# Font loading (cwd-independent, cached)
-# ---------------------------------------------------------------------------
-
-def resolve_font_path(font_name: str) -> Optional[str]:
-    """Locate a font file by name, independent of the caller's cwd.
-
-    Tries, in order: an absolute path as given; ``assets/fonts/<name>``
-    relative to the cwd (the classic loaders' behavior, kept first so a
-    process running from a different checkout keeps its own fonts); then
-    ``assets/fonts/<name>`` under the core install root. Returns an
-    absolute path, or None when the file doesn't exist anywhere.
-    """
-    if not font_name or not isinstance(font_name, str):
-        return None
-    if os.path.isabs(font_name):
-        return font_name if os.path.isfile(font_name) else None
-    # A relative name must be a bare filename. font_name comes from plugin
-    # config, which the web UI writes; a value like "../../config/config.json"
-    # would otherwise escape assets/fonts/ once joined and let a config probe
-    # arbitrary paths for existence. os.path.basename collapses any such value
-    # to its last component, so a name that isn't already bare is rejected.
-    if os.path.basename(font_name) != font_name:
-        return None
-    candidates = (
-        os.path.join(os.getcwd(), _FONTS_SUBDIR, font_name),
-        os.path.join(_CORE_ROOT, _FONTS_SUBDIR, font_name),
-    )
-    for candidate in candidates:
-        if os.path.isfile(candidate):
-            return os.path.abspath(candidate)
-    return None
-
-
-def load_font(font_name: str, size: int) -> Any:
-    """Load a font by filename at a pixel size, with caching and fallback.
-
-    ``.bdf`` files load as ``freetype.Face`` (matching FontManager), other
-    files through ``PIL.ImageFont.truetype``. A missing or unloadable font
-    degrades to ``PressStart2P-Regular.ttf`` at the requested size, then to
-    PIL's built-in default — this function never raises.
-    """
-    try:
-        size = max(1, int(size))
-    except (TypeError, ValueError):
-        size = 8
-
-    path = resolve_font_path(font_name)
-    if path is None:
-        logger.warning("Font file not found: %s, using fallback", font_name)
-        return _load_fallback_font(size)
-
-    cache_key = (path, size)
-    cached = _font_cache.get(cache_key)
-    if cached is not None:
-        return cached
-
-    try:
-        if path.lower().endswith('.bdf'):
-            if freetype is None:
-                raise RuntimeError("freetype not available for BDF fonts")
-            face = freetype.Face(path)
-            # Character size in 1/64th points at 72dpi == pixel size.
-            face.set_char_size(size * 64, size * 64, 72, 72)
-            font: Any = face
-        else:
-            font = ImageFont.truetype(path, size)
-    except Exception as e:
-        logger.warning("Error loading font %s at %spx: %s, using fallback",
-                       path, size, e)
-        return _load_fallback_font(size)
-
-    _font_cache[cache_key] = font
-    return font
-
-
-def _load_fallback_font(size: int) -> Any:
-    """PressStart2P at the requested size, else PIL's built-in default."""
-    path = resolve_font_path(_FALLBACK_FONT_NAME)
-    if path is not None:
-        cache_key = (path, size)
-        cached = _font_cache.get(cache_key)
-        if cached is not None:
-            return cached
-        try:
-            font = ImageFont.truetype(path, size)
-            _font_cache[cache_key] = font
-            return font
-        except Exception as e:
-            logger.error("Error loading fallback font: %s", e)
-    return ImageFont.load_default()
-
-
-# ---------------------------------------------------------------------------
-# Schema parsing
-# ---------------------------------------------------------------------------
-
-def expand_style_elements(schema: Dict[str, Any]) -> Dict[str, Any]:
-    """Expand a ``customization.x-style-elements`` declaration into the full
-    per-element property blocks the web-UI config form renders.
-
-    Each declared element becomes an object with ``font`` / ``font_size`` /
-    ``text_color`` properties (only the sub-fields the declaration carries),
-    tagged ``x-style-managed: true``; elements declaring ``offsets: true``
-    additionally get an entry under ``customization.layout`` with
-    ``x_offset`` / ``y_offset`` integers defaulting to 0. Hand-written
-    element blocks with the same key are left untouched.
-
-    Returns the schema unchanged (same object) when there is nothing to
-    expand; otherwise returns an expanded deep copy. Never raises.
-    """
-    try:
-        customization = schema.get('properties', {}).get('customization')
-        if not isinstance(customization, dict):
-            return schema
-        declaration = customization.get('x-style-elements')
-        if not isinstance(declaration, dict) or not declaration:
-            return schema
-
-        expanded = copy.deepcopy(schema)
-        customization = expanded['properties']['customization']
-        customization.setdefault('type', 'object')
-        props = customization.setdefault('properties', {})
-        layout_props: Dict[str, Any] = {}
-
-        for element_key, spec in declaration.items():
-            if not isinstance(spec, dict):
-                continue
-            if element_key not in props:
-                props[element_key] = _element_block_from_spec(element_key, spec)
-            if spec.get('offsets'):
-                layout_props[element_key] = _offset_block_from_spec(
-                    element_key, spec)
-
-        if layout_props:
-            layout = props.setdefault('layout', {
-                'type': 'object',
-                'title': 'Layout Offsets',
-                'description': 'Pixel offsets applied to each element '
-                               '(positive x moves right, positive y moves down)',
-                'x-advanced': True,
-                'properties': {},
-                'additionalProperties': False,
-            })
-            layout.setdefault('properties', {})
-            for element_key, block in layout_props.items():
-                layout['properties'].setdefault(element_key, block)
-
-        return expanded
-    except Exception as e:
-        logger.warning("Error expanding x-style-elements: %s", e)
-        return schema
-
-
-def _element_block_from_spec(element_key: str,
-                             spec: Dict[str, Any]) -> Dict[str, Any]:
-    """Build one expanded per-element schema block from its declaration."""
-    properties: Dict[str, Any] = {}
-    order = []
-
-    font_spec = spec.get('font')
-    if isinstance(font_spec, dict):
-        font_prop: Dict[str, Any] = {
-            'type': 'string',
-            'title': 'Font Family',
-            'x-advanced': True,
-        }
-        if 'default' in font_spec:
-            font_prop['default'] = font_spec['default']
-        if isinstance(font_spec.get('enum'), list):
-            font_prop['enum'] = list(font_spec['enum'])
-        properties['font'] = font_prop
-        order.append('font')
-
-    size_spec = spec.get('size')
-    if isinstance(size_spec, dict):
-        size_prop: Dict[str, Any] = {
-            'type': 'integer',
-            'title': 'Font Size',
-            'description': 'Font size in pixels',
-            'x-advanced': True,
-        }
-        if 'default' in size_spec:
-            size_prop['default'] = size_spec['default']
-        if 'min' in size_spec:
-            size_prop['minimum'] = size_spec['min']
-        if 'max' in size_spec:
-            size_prop['maximum'] = size_spec['max']
-        properties['font_size'] = size_prop
-        order.append('font_size')
-
-    color_spec = spec.get('color')
-    if isinstance(color_spec, dict):
-        color_prop: Dict[str, Any] = {
-            'type': 'array',
-            'title': 'Text Color',
-            'items': {'type': 'integer', 'minimum': 0, 'maximum': 255},
-            'minItems': 3,
-            'maxItems': 3,
-            'x-widget': 'color-picker',
-        }
-        if 'default' in color_spec:
-            color_prop['default'] = list(color_spec['default'])
-        properties['text_color'] = color_prop
-        order.append('text_color')
-
-    return {
-        'type': 'object',
-        'title': spec.get('title', element_key),
-        'x-style-managed': True,
-        'x-propertyOrder': order,
-        'additionalProperties': False,
-        'properties': properties,
-    }
-
-
-def _offset_block_from_spec(element_key: str,
-                            spec: Dict[str, Any]) -> Dict[str, Any]:
-    """Build one layout.<element> offset block (x/y, default 0)."""
-    axis = {
-        'type': 'integer',
-        'default': 0,
-        'x-advanced': True,
-    }
-    return {
-        'type': 'object',
-        'title': spec.get('title', element_key),
-        'x-style-managed': True,
-        'additionalProperties': False,
-        'properties': {
-            'x_offset': dict(axis, title='X Offset'),
-            'y_offset': dict(axis, title='Y Offset'),
-        },
-    }
-
-
-def defaults_from_schema(schema: Dict[str, Any]) -> Dict[str, Any]:
-    """Extract per-element style defaults from a config schema dict.
-
-    Understands both declaration forms: the compact ``x-style-elements``
-    map, and hand-written per-element blocks under
-    ``customization.properties`` (their ``font`` / ``font_size`` /
-    ``text_color`` property defaults). Returns a config-shaped dict::
-
-        {"customization": {"<element>": {"font": ..., "font_size": ...,
-                                         "text_color": [...]}, ...}}
-
-    Elements with no declared defaults are omitted. Never raises.
-    """
-    elements: Dict[str, Dict[str, Any]] = {}
-    try:
-        customization = schema.get('properties', {}).get('customization')
-        if not isinstance(customization, dict):
-            return {'customization': elements}
-
-        declaration = customization.get('x-style-elements')
-        if isinstance(declaration, dict):
-            for element_key, spec in declaration.items():
-                if not isinstance(spec, dict):
-                    continue
-                defaults: Dict[str, Any] = {}
-                font_spec = spec.get('font')
-                if isinstance(font_spec, dict) and 'default' in font_spec:
-                    defaults['font'] = font_spec['default']
-                size_spec = spec.get('size')
-                if isinstance(size_spec, dict) and 'default' in size_spec:
-                    defaults['font_size'] = size_spec['default']
-                color_spec = spec.get('color')
-                if isinstance(color_spec, dict) and 'default' in color_spec:
-                    defaults['text_color'] = list(color_spec['default'])
-                if defaults:
-                    elements[element_key] = defaults
-
-        properties = customization.get('properties')
-        if isinstance(properties, dict):
-            for element_key, block in properties.items():
-                if element_key == 'layout' or element_key in elements:
-                    continue
-                if not isinstance(block, dict):
-                    continue
-                block_props = block.get('properties')
-                if not isinstance(block_props, dict):
-                    continue
-                defaults = {}
-                for style_key in _STYLE_KEYS:
-                    prop = block_props.get(style_key)
-                    if isinstance(prop, dict) and 'default' in prop:
-                        defaults[style_key] = prop['default']
-                if defaults:
-                    elements[element_key] = defaults
-    except Exception as e:
-        logger.warning("Error extracting style defaults from schema: %s", e)
-    return {'customization': elements}
-
-
-def defaults_from_schema_file(schema_path: Union[str, os.PathLike]) -> Dict[str, Any]:
-    """``defaults_from_schema`` for a schema file on disk. A missing or
-    malformed file yields empty defaults (with a logged warning) — every
-    configured value then counts as a user override, which is the safe
-    degradation. Never raises."""
-    try:
-        with open(schema_path, 'r', encoding='utf-8') as f:
-            schema = json.load(f)
-        if not isinstance(schema, dict):
-            raise ValueError("schema is not a JSON object")
-    except Exception as e:
-        logger.warning("Could not read style defaults from %s: %s",
-                       schema_path, e)
-        return {'customization': {}}
-    return defaults_from_schema(schema)
-
-
-# ---------------------------------------------------------------------------
-# Resolver
-# ---------------------------------------------------------------------------
-
-def _normalize_color(value: Any) -> Optional[Tuple[int, int, int]]:
-    """An (r, g, b) tuple of ints in 0..255, or None for anything else."""
-    if isinstance(value, (list, tuple)) and len(value) == 3:
-        try:
-            rgb = tuple(int(c) for c in value)
-        except (TypeError, ValueError):
-            return None
-        if all(0 <= c <= 255 for c in rgb):
-            return rgb  # type: ignore[return-value]
-    return None
-
-
-class ElementStyleResolver:
-    """Resolves per-element user styling against schema defaults.
-
-    Built from a plugin's live config dict and the defaults extracted from
-    its own ``config_schema.json`` (``defaults_from_schema_file``). The
-    config dict is held by reference as ``_config`` — consumers compare
-    identity (``resolver._config is not self.config``) to decide when a
-    resolver must be rebuilt after ``on_config_change`` swaps the dict.
-
-    A configured font/size/color counts as user-forced only when it differs
-    from the schema default (see module docstring); otherwise ``style()``
-    returns the caller's classic values verbatim, keeping untouched configs
-    byte-identical to pre-customization rendering.
-    """
-
-    def __init__(self, config: Optional[Dict[str, Any]],
-                 defaults: Optional[Dict[str, Any]] = None):
-        # Keep the exact object for identity-based invalidation, even if the
-        # caller hands us something odd; reads are guarded.
-        self._config = config
-        if isinstance(defaults, dict):
-            element_defaults = defaults.get('customization', {})
-        else:
-            element_defaults = {}
-        self._defaults: Dict[str, Any] = (
-            element_defaults if isinstance(element_defaults, dict) else {})
-        self._memo: Dict[Any, ElementStyle] = {}
-
-    # -- internal accessors -------------------------------------------------
-
-    def _customization(self) -> Dict[str, Any]:
-        config = self._config if isinstance(self._config, dict) else {}
-        customization = config.get('customization', {})
-        return customization if isinstance(customization, dict) else {}
-
-    def _element_config(self, element_key: str) -> Dict[str, Any]:
-        element = self._customization().get(element_key, {})
-        return element if isinstance(element, dict) else {}
-
-    def _element_defaults(self, element_key: str) -> Dict[str, Any]:
-        defaults = self._defaults.get(element_key, {})
-        return defaults if isinstance(defaults, dict) else {}
-
-    # -- public API ---------------------------------------------------------
-
-    def style(self, element_key: str,
-              classic_font: str = _FALLBACK_FONT_NAME,
-              classic_size: int = 8,
-              classic_color: Optional[Tuple[int, int, int]] = None) -> ElementStyle:
-        """Resolve one element's style. Never raises.
-
-        Args:
-            element_key: Key under ``config['customization']`` (e.g.
-                ``'title_text'``).
-            classic_font: Font filename the plugin's classic (pre-
-                customization) code used for this element.
-            classic_size: Classic pixel size.
-            classic_color: Classic RGB color, or None when the caller only
-                cares about the font (``.color`` then falls back to the
-                schema default color, else white).
-
-        Returns:
-            ElementStyle with the loaded font face, RGB color, (x, y)
-            offset, and the ``user_forced`` / ``user_forced_color`` flags.
-        """
-        try:
-            memo_key = (element_key, classic_font, classic_size,
-                        _normalize_color(classic_color) or classic_color)
-            memoized = self._memo.get(memo_key)
-            if memoized is not None:
-                return memoized
-        except Exception:
-            memo_key = None
-
-        try:
-            resolved = self._resolve(element_key, classic_font,
-                                     classic_size, classic_color)
-        except Exception as e:
-            logger.warning("Error resolving style for element '%s': %s — "
-                           "using classic style", element_key, e)
-            resolved = self._classic_style(classic_font, classic_size,
-                                           classic_color)
-        if memo_key is not None:
-            self._memo[memo_key] = resolved
-        return resolved
-
-    def offset(self, element_key: str) -> Tuple[int, int]:
-        """The user's ``customization.layout.<element>`` (x, y) pixel
-        offset, defaulting to (0, 0). Never raises."""
-        return (self.offset_value(element_key, 'x_offset', 0),
-                self.offset_value(element_key, 'y_offset', 0))
-
-    def offset_value(self, element_key: str, axis: str, default: int = 0) -> int:
-        """One ``customization.layout.<element>.<axis>`` value as an int.
-
-        ``axis`` is usually ``'x_offset'`` / ``'y_offset'`` but any key is
-        honored (e.g. the scoreboards' ``'away_x_offset'``). Numeric
-        strings are coerced; anything else degrades to ``default``. Never
-        raises.
-        """
-        try:
-            layout = self._customization().get('layout', {})
-            if not isinstance(layout, dict):
-                return int(default)
-            element = layout.get(element_key, {})
-            if not isinstance(element, dict):
-                return int(default)
-            value = element.get(axis, default)
-            if isinstance(value, bool):
-                return int(default)
-            if isinstance(value, (int, float)):
-                return int(value)
-            if isinstance(value, str):
-                try:
-                    return int(float(value))
-                except (TypeError, ValueError):
-                    logger.warning(
-                        "Invalid layout offset for %s.%s: %r, using %s",
-                        element_key, axis, value, default)
-                    return int(default)
-            return int(default)
-        except Exception as e:
-            logger.warning("Error reading layout offset %s.%s: %s",
-                           element_key, axis, e)
-            try:
-                return int(default)
-            except (TypeError, ValueError):
-                return 0
-
-    # -- resolution internals -----------------------------------------------
-
-    def _resolve(self, element_key: str, classic_font: str,
-                 classic_size: int,
-                 classic_color: Optional[Tuple[int, int, int]]) -> ElementStyle:
-        element_config = self._element_config(element_key)
-        element_defaults = self._element_defaults(element_key)
-
-        # Font family: forced only when it differs from the schema default
-        # (falling back to the classic font as the reference when the
-        # schema declares none).
-        default_font = element_defaults.get('font', classic_font)
-        configured_font = element_config.get('font')
-        font_forced = (isinstance(configured_font, str) and configured_font
-                       and configured_font != default_font)
-
-        # Font size: same rule, with defensive int coercion.
-        default_size = self._coerce_size(
-            element_defaults.get('font_size'), None)
-        if default_size is None:
-            default_size = self._coerce_size(classic_size, 8)
-        configured_size = self._coerce_size(element_config.get('font_size'),
-                                            None)
-        size_forced = (configured_size is not None
-                       and configured_size != default_size)
-
-        font_name = configured_font if font_forced else classic_font
-        font_size = configured_size if size_forced else self._coerce_size(
-            classic_size, 8)
-        user_forced = bool(font_forced or size_forced)
-
-        # Color: forced only when it differs from the schema default (or,
-        # absent one, from the classic color).
-        default_color = _normalize_color(element_defaults.get('text_color'))
-        configured_color = _normalize_color(element_config.get('text_color'))
-        reference_color = (default_color if default_color is not None
-                           else _normalize_color(classic_color))
-        color_forced = (configured_color is not None
-                        and configured_color != reference_color)
-        if color_forced:
-            color = configured_color
-        else:
-            color = (_normalize_color(classic_color) or default_color
-                     or (255, 255, 255))
-
-        return ElementStyle(
-            font=load_font(font_name, font_size),
-            color=color,
-            offset=self.offset(element_key),
-            font_name=font_name,
-            font_size=font_size,
-            user_forced=user_forced,
-            user_forced_color=bool(color_forced),
-        )
-
-    def _classic_style(self, classic_font: str, classic_size: int,
-                       classic_color: Optional[Tuple[int, int, int]]) -> ElementStyle:
-        """The untouched fallback style — used when resolution itself
-        fails, so ``style()`` can keep its never-raises promise."""
-        size = self._coerce_size(classic_size, 8)
-        return ElementStyle(
-            font=load_font(classic_font, size),
-            color=_normalize_color(classic_color) or (255, 255, 255),
-            offset=(0, 0),
-            font_name=classic_font,
-            font_size=size,
-            user_forced=False,
-            user_forced_color=False,
-        )
-
-    @staticmethod
-    def _coerce_size(value: Any, default: Optional[int]) -> Optional[int]:
-        """An int pixel size, or ``default`` for None/garbage."""
-        if value is None or isinstance(value, bool):
-            return default
-        try:
-            size = int(value)
-        except (TypeError, ValueError):
-            return default
-        return size if size > 0 else default

src/font_manager.py

@@ -659,25 +659,6 @@ class FontManager:
 
     # ==================== Font Discovery ====================
 
-    @staticmethod
-    def _resolve_asset_path(relative_path: str) -> str:
-        """Resolve a repo-relative asset path independently of the process cwd.
-
-        Prefers the working directory (preserving behavior when the process
-        runs from the install root), then falls back to the install root
-        derived from this module's own location. Without the fallback, any
-        process started outside the install root (e.g. the plugin safety
-        harness on CI) silently loses every font and degrades to PIL's
-        default face.
-        """
-        if os.path.exists(relative_path):
-            return relative_path
-        install_root = Path(__file__).resolve().parent.parent
-        candidate = install_root / relative_path
-        if candidate.exists():
-            return str(candidate)
-        return relative_path
-
     def _initialize_fonts(self):
         """Initialize font catalog and validate configuration."""
         self._scan_fonts_directory()
@@ -686,7 +667,7 @@ class FontManager:
 
     def _scan_fonts_directory(self):
         """Scan assets/fonts directory for available fonts."""
-        fonts_dir = self._resolve_asset_path("assets/fonts")
+        fonts_dir = "assets/fonts"
         if not os.path.exists(fonts_dir):
             logger.warning(f"Fonts directory not found: {fonts_dir}")
             return
@@ -702,7 +683,6 @@ class FontManager:
     def _register_common_fonts(self):
         """Register common font aliases from common_fonts dictionary."""
         for family_name, font_path in self.common_fonts.items():
-            font_path = self._resolve_asset_path(font_path)
             # Check if font file exists
             if os.path.exists(font_path):
                 # Register the common font name (overrides auto-generated name if exists)

src/logo_downloader.py

@@ -118,14 +118,7 @@ class LogoDownloader:
     
     @staticmethod
     def normalize_abbreviation(abbreviation: str) -> str:
-        """Normalize team abbreviation for consistent filename usage.
-
-        Public API: sports scoreboard plugins call this directly.
-        NOTE: LogoHelper.normalize_abbreviation (src/common/logo_helper.py)
-        is a deliberately different variant (strips spaces, fewer character
-        replacements) — keep both behaviors stable; logo filenames on
-        existing installs depend on them.
-        """
+        """Normalize team abbreviation for consistent filename usage."""
         # Handle special characters that can cause filesystem issues
         normalized = abbreviation.upper()
         

src/plugin_system/base_plugin.py

@@ -145,77 +145,6 @@ class BasePlugin(ABC):
         """
         raise NotImplementedError("Plugins must implement display()")
 
-    # -------------------------------------------------------------------------
-    # Global (whole-device) configuration
-    # -------------------------------------------------------------------------
-    @property
-    def global_config(self) -> Dict[str, Any]:
-        """
-        The full LEDMatrix configuration, for reading device-wide settings.
-
-        ``self.config`` is only this plugin's own slice, so cross-cutting
-        settings — ``target_fps``, ``timezone``, ``location`` — were previously
-        unreachable from a plugin without reaching into a manager by hand.
-
-        Resolution order mirrors the timezone helpers the sports plugins
-        already ship: ``plugin_manager.config_manager`` first (the cores that
-        hang it there), then ``cache_manager.config_manager``. Returns ``{}``
-        when neither is available, so callers can use plain ``.get()`` without
-        guarding, and a plugin on a core that predates this property still
-        loads — ``getattr(self, 'global_config', {})`` simply yields the
-        default.
-
-        Treat as read-only: the returned dict is the live config the core is
-        using, so mutating it edits every other consumer's view and can be
-        persisted back to disk.
-
-        Assignment is still allowed and wins over the resolved value. Several
-        shipped plugins (news, stock-news, ledmatrix-stocks, ledmatrix-
-        elections, ledmatrix-leaderboard, nfl-draft) set
-        ``self.global_config`` to their own ``config['global']`` sub-dict; a
-        property without a setter would raise AttributeError and stop those
-        plugins loading.
-
-        Example:
-            fps = self.global_config.get('target_fps')
-        """
-        override = getattr(self, '_global_config_override', None)
-        if override is not None:
-            return override
-        for owner in (self.plugin_manager, self.cache_manager):
-            config_manager = getattr(owner, 'config_manager', None)
-            if config_manager is None:
-                continue
-            try:
-                config = config_manager.get_config()
-            except Exception:
-                # A broken or unreadable config must never stop a plugin from
-                # loading; fall through to the next source, then to {}.
-                self.logger.debug(
-                    "Could not read global config from %s",
-                    type(owner).__name__, exc_info=True,
-                )
-                continue
-            # Only a real mapping is usable: callers do .get() on this and feed
-            # the result to numeric code, so handing back whatever a stub or a
-            # half-built manager returned would fail later and further away.
-            #
-            # An empty dict is treated as "nothing here yet" rather than a
-            # valid answer, so resolution continues to the next source. Both
-            # managers default to the same config/config.json, so falling
-            # through cannot pick up a different file's settings -- but it does
-            # rescue the case where the first manager simply hasn't loaded yet,
-            # which would otherwise return {} and silently disable every
-            # setting read through this property.
-            if isinstance(config, dict) and config:
-                return config
-        return {}
-
-    @global_config.setter
-    def global_config(self, value: Dict[str, Any]) -> None:
-        """Let a plugin substitute its own view (see the getter's docstring)."""
-        self._global_config_override = value
-
     # -------------------------------------------------------------------------
     # Adaptive layout support (opt-in)
     # -------------------------------------------------------------------------
@@ -576,40 +505,6 @@ class BasePlugin(ABC):
     # -------------------------------------------------------------------------
     # Vegas scroll mode support
     # -------------------------------------------------------------------------
-    def get_vegas_render_width(self) -> int:
-        """
-        Width the Vegas ticker wants this plugin's content to occupy.
-
-        On a wide panel a layout built to fill the screen reads as sparse in a
-        ticker — a forecast spread over five columns, a progress bar drawn at
-        100% width, a stat block with the panel's whole width between its
-        elements. Vegas asks for a narrower render so the plugin can choose a
-        tighter arrangement instead of being cropped afterwards.
-
-        Vegas also narrows ``display_manager`` for the duration of the call, so
-        a plugin that already sizes itself from ``matrix.width`` needs no
-        changes. Read this only when you size content some other way.
-
-        Controlled by the plugin's own ``vegas_width_pct`` config value, else
-        the global ``display.vegas_scroll.render_width_pct``.
-
-        Returns:
-            Target width in pixels. Outside a Vegas content request, the full
-            display width.
-        """
-        requested = getattr(self, '_vegas_render_width', None)
-        if isinstance(requested, int) and requested > 0:
-            return requested
-
-        display_manager = getattr(self, 'display_manager', None)
-        matrix = getattr(display_manager, 'matrix', None)
-        if matrix is not None and getattr(matrix, 'width', None):
-            return int(matrix.width)
-        width = getattr(display_manager, 'width', None)
-        if callable(width):
-            width = width()
-        return int(width) if width else 128
-
     def get_vegas_content(self) -> Optional[Any]:
         """
         Get content for Vegas-style continuous scroll mode.