mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-18 04:49:13 +00:00
ChuckBuildsandClaude Opus 5
9e1c339273
This PR was opened to say B6 was deliberately held. It has since run, so the document said the opposite of the truth -- which is the exact failure it was written to fix: "a plan that misreports which phase it is in is worse than no plan". Merges current main first (53 commits), which brings in #508's corrections to this same file, then replaces the hold with what happened. **Why the hold lifted is worth recording, because the stated gate was never met.** It asked for evidence of 3.2.0 uptake, and that evidence could not arrive: the core updates by `git pull --rebase`, so release-asset counts cannot measure it, and no store-side telemetry exists. What changed is that the risk the gate protected against was closed directly -- the store now refuses a plugin whose floor exceeds the running core on all three routes in: install_plugin (#431/#433), update_plugin's git branch (#508), and install_from_url (#510). A pre-3.2.0 user cannot receive a sunset plugin at all, so they keep the version they run. Refusal replaced the bundled copy, which is what the copy stood in for. Records what shipped (eight plugins, ~5,800 lines, plugins #346/#349/#350/#351) and the two findings worth carrying to the next module: baseball's fallback was the only one holding orchestration logic the core lacked, and two tests had been leaning on the guard -- soccer's stubbed `src` in a way that shadowed the core, so it had been exercising the frozen copy rather than the shipping class since B5. The remaining-work list is replaced too. Its first item was "nothing on the critical path, B6 is waiting on calendar time", which is no longer true. What remains: hardware soaks (with a note to check the rig's display_mode first, or a board in switch mode tells you nothing about the scroll code), cutting 3.3.0 -- not required by B6, whose floors are 3.2.0, but calendar 1.2.3 floors at 3.3.0 and is un-installable until it exists -- and reconsidering the modules held back during the sunset. Keeps the pre-B6 sections as history. The reasoning still applies to the next module; it is just no longer in force for this one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9
LEDMatrix Documentation
This directory contains guides, references, and architectural notes for the LEDMatrix project. If you are setting up a Pi for the first time, start with the project root README — it covers hardware, OS imaging, and the one-shot installer. The pages here go deeper.
I'm a new user
- GETTING_STARTED.md — first-time setup walkthrough
- WEB_INTERFACE_GUIDE.md — using the web UI
- PLUGIN_STORE_GUIDE.md — installing and managing plugins
- WIFI_NETWORK_SETUP.md — WiFi and AP-mode setup
- TROUBLESHOOTING.md — common issues and fixes
- SSH_UNAVAILABLE_AFTER_INSTALL.md — recovering SSH after install
- CONFIG_DEBUGGING.md — diagnosing config problems
- LOW_MEMORY_BOARDS.md — Pi Zero 2 W / 3B+ / 1GB Pi 4 memory limits
I want to write a plugin
Start here:
- PLUGIN_DEVELOPMENT_GUIDE.md — end-to-end workflow
- PLUGIN_QUICK_REFERENCE.md — cheat sheet
- PLUGIN_API_REFERENCE.md — display, cache, and plugin-manager APIs
- PLUGIN_ERROR_HANDLING.md — error-handling patterns
- DEV_PREVIEW.md — preview plugins on your dev machine without a Pi
- EMULATOR_SETUP_GUIDE.md — running the matrix emulator
Going deeper:
- ADVANCED_PLUGIN_DEVELOPMENT.md — advanced patterns
- PLUGIN_ARCHITECTURE_SPEC.md — original plugin-system design spec (historical; see its banner for what has drifted)
- PLUGIN_DEPENDENCY_GUIDE.md / PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
- PLUGIN_WEB_UI_ACTIONS.md (+ example JSON)
- PLUGIN_CUSTOM_ICONS.md
- PLUGIN_REGISTRY_SETUP_GUIDE.md (+ registry template)
- STARLARK_APPS_GUIDE.md — Starlark-based mini-apps
- widget-guide.md — widget development
- ADAPTIVE_LAYOUT.md — render legibly on any panel size (opt-in font/layout scaling)
- plugin-safety-harness.md — test a plugin across every screen and matrix size
Configuring plugins
- PLUGIN_CONFIG_QUICK_START.md — minimal config you need
- PLUGIN_CONFIGURATION_GUIDE.md — schema design
- PLUGIN_CONFIGURATION_TABS.md — multi-tab UI configs
- PLUGIN_CONFIG_ARCHITECTURE.md — how the config system works
- PLUGIN_CONFIG_CORE_PROPERTIES.md — properties every plugin honors
Advanced features
- ADVANCED_FEATURES.md — Vegas scroll, on-demand display, cache management, background services, permissions
- FONT_MANAGER.md — font system
- SKIN_SYSTEM.md — skin architecture for sports scoreboards
- CREATING_SKINS.md — writing and validating a skin
Reference
- CONFIG_REFERENCE.md — every key in config.json and config_secrets.json
- REST_API_REFERENCE.md — all web-interface HTTP endpoints
- PLUGIN_API_REFERENCE.md — Python APIs available to plugins
- DEVELOPER_QUICK_REFERENCE.md — common dev tasks
- PLUGIN_IMPLEMENTATION_SUMMARY.md — what the plugin system actually does
Contributing to LEDMatrix itself
- DEVELOPMENT.md — environment setup
- HOW_TO_RUN_TESTS.md — running the test suite
- MULTI_ROOT_WORKSPACE_SETUP.md — multi-repo workspace
- MIGRATION_GUIDE.md — breaking changes between releases
- SPORTS_UNIFICATION.md — how the sports scoreboard base classes are organized
Archive
docs/archive/ holds older guides that have been superseded or describe
features that have been removed. They are kept for historical context and
git history but should not be relied on.
Contributing to the docs
- Markdown only, professional tone, minimal emoji.
- Prefer adding to an existing page over creating a new one. If you add a new page, link it from this index in the section it belongs to.
- If a page becomes obsolete, move it to
docs/archive/rather than deleting it, so links don't rot. - Keep examples runnable — paths, commands, and config keys here should match what's actually in the repo.