Codebase audit: fix shipping bugs, remove verified-dead code, repair doc drift, add regression guards (#438)

* fix(web): implement delete_cached so the font catalog cache actually invalidates

api_v3.py's font upload/delete handlers import delete_cached from
web_interface.cache, but the function was never defined. The surrounding
except ImportError silently swallowed the failure, so the fonts_catalog
cache entry survived uploads/deletes and newly uploaded fonts did not
appear until the TTL expired or the service restarted.

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

* fix(web): remove dead weather/stocks partial routes that returned 500

The partial dispatcher still routed 'weather' and 'stocks' to loaders
rendering v3/partials/weather.html and stocks.html — templates that no
longer exist since weather and stocks became store plugins. Requesting
either partial raised TemplateNotFound, which the catch-all turned into
a 500. No template or JS references these partials (the only 'weather'
hit in the front end is a plugin-store category filter option), so the
branches and both loader functions are removed; unknown partials now
fall through to the existing 404 handler.

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

* fix(deps): align contradictory psutil/Flask-Limiter/freetype-py pins

requirements.txt's optional-install comment recommended psutil>=5.9,<6.0
while web_interface/requirements.txt hard-requires >=6.0,<7.0 — anyone
following the comment ends up with an unsatisfiable pair. The comment now
recommends the same range the web interface requires (all psutil APIs
used — Process, boot_time, cpu_percent, disk_usage, virtual_memory — are
stable in 6.x). Flask-Limiter gains the same <4.0 cap in both files and
freetype-py the same >=2.5.1 floor.

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

* fix(config): add template keys the code already reads

display.hardware gains pixel_mapper_config, row_address_type,
multiplexing and panel_type (read at display_manager.py with these exact
fallbacks — users on non-standard panels previously had no way to
discover them from the template). vegas_scroll gains
frame_based_scrolling and scroll_delay, the only two of its 27 keys the
template omitted (read in src/vegas_mode/config.py). plugin_system gains
development_mode, which the web UI reads and writes but the template
never declared.

Every added value is byte-identical to the code-side .get() fallback, so
ConfigManager._migrate_config() merging these keys into existing user
configs cannot change behavior on any installed device.

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

* fix(scripts): repair broken sys.path setup in utility scripts

clear_cache.py and download_nba_logos.py pointed sys.path at a 'src'
directory relative to the script's own folder (scripts/utils/src and
scripts/src — neither exists), so both crashed on import; they now insert
the project root and import via the src package like the other scripts.
debug_web_manual.py resolved 'project root' to scripts/debug/ instead of
two levels up. fix_nhl_cache.sh is removed: it used Python docstring
syntax in a bash script and invoked clear_nhl_cache.py, which does not
exist anywhere in the repo — it cannot ever have worked in its current
location.

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

* docs: correct stale file:line references and the loader-fallback contradiction

CLAUDE.md and .cursorrules disagreed about plugin-directory fallback
behavior; the code (SchemaManager.get_schema_path) probes plugins/
BEFORE plugin-repos/, and the main discovery path has no fallback at
all — both files now describe the real behavior, preferring symbol names
over line numbers so the references rot slower. REST_API_REFERENCE.md
pointed at app.py:144/:607 for mounts that live at :199/:799 and counted
92 routes where there are 94. PLUGIN_ARCHITECTURE_SPEC.md's historical
banner gains a note that its example imports
(src/plugin_system/base_classes/*_plugin.py) never shipped — the real
base classes are src.base_classes.sports.SportsCore and
src.base_classes.hockey.Hockey.

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

* docs: fix broken links, phantom script references, and stale CI description

Repairs every broken relative link in active docs (targets renamed or
archived long ago: PLUGIN_DEVELOPMENT.md -> PLUGIN_DEVELOPMENT_GUIDE.md,
API_REFERENCE.md -> REST_API_REFERENCE.md, PLUGIN_STORE_USER_GUIDE.md ->
PLUGIN_STORE_GUIDE.md, plugin_docs/ dir, TROUBLESHOOTING_QUICK_START.md,
and MIGRATION_GUIDE's README link that silently resolved to the docs
index instead of the project README). Replaces commands invoking scripts
that do not exist (scripts/update_stats.py, validate_registry.py,
check_updates.py, fix_permissions.sh) with the real tooling, and
rewrites HOW_TO_RUN_TESTS.md's CI section, which described a
security-audit workflow that was never committed and a pytest workflow
'queued to land' that landed long ago as test.yml.

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

* docs: complete the docs index and refresh the web interface file tree

docs/README.md's own policy says every page must be linked from the
index, yet five weren't — including the entire skin system
(SKIN_SYSTEM.md, CREATING_SKINS.md), ADAPTIVE_LAYOUT.md,
plugin-safety-harness.md and SPORTS_UNIFICATION.md. Each is now listed
in the section it belongs to, and PLUGIN_ARCHITECTURE_SPEC.md is marked
historical in the index (the doc itself already carries the banner).
web_interface/README.md's static/v3 tree showed only app.css/app.js;
it now reflects the actual contents.

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

* chore: remove dead modules confirmed unused in-repo and across all store plugins

- src/common/cli.py: imports a 'ledmatrix_common' package that exists
  nowhere (not in this repo, any requirements file, or the plugin
  monorepo), so it cannot ever have run; its README section claimed
  scripts/dev/* used it, which was also untrue.
- src/web_interface/logging_config.py: zero callers — the web app uses
  web_interface/logging_config.py (a different module), and nothing
  imports the src copy.
- handle_errors decorator in src/web_interface/error_handler.py: zero
  call sites (the module's response helpers stay — they are used).
- ConfigManager.get_clock_config(): reads a 'clock' config key that no
  longer exists anywhere; only caller was its own unit test.

Deliberately kept despite zero in-repo callers: DisplayError,
src/common/config_helper.py and display_helper.py — all documented as
plugin-facing API (docs/PLUGIN_ERROR_HANDLING.md, src/common/README.md),
and third-party plugins outside the official monorepo cannot be
enumerated. Verified against a fresh clone of ledmatrix-plugins (43
plugins): zero references to any removed symbol.

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

* chore: remove manager-era NBA test files and one-off debug scripts

The four test_nba_*.py files imported nba_managers, leaderboard_manager
and odds_manager — top-level modules deleted when sports displays became
plugins — inside try/except blocks that swallowed the ImportError, so
they passed while exercising nothing. test_nba_data_structure.py and
debug_nba_api.py (a diagnostic script living in test/) made live ESPN
API calls rather than testing repo code. None were enrolled in CI.

scripts/debug/direct_fix_imports.py and check_imports.py were one-shot
artifacts that edited/inspected a hardcoded ~/LEDMatrix/web_interface/
app.py to fix an import problem solved long ago; nothing references
them.

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

* chore: remove generate_report.py, which aggregates artifacts of CI jobs that do not exist

The script's only function is to merge JSON artifacts
(bandit/semgrep/pip-audit/safety/gitleaks results) produced by a
security-audit workflow that was never committed —
.github/workflows/ has no such jobs, so there is nothing for it to
aggregate and no way to run it usefully. Its siblings stay:
prove_security.py and audit_plugins.py both run standalone (verified),
and .codacy.yml stays because the Codacy service (README badge) reads it
server-side without a workflow file.

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

* fix(web): load the three widget scripts store plugins already declare

time-picker.js, file-upload-single.js and plugin-file-manager.js
register widgets that installed store plugins reference in their config
schemas (countdown uses x-widget: time-picker and file-upload-single;
of-the-day uses plugin-file-manager), but base.html never included the
scripts. plugin_config.html renders such fields as an empty container
that polls LEDMatrixWidgets.get(...) on a 50ms loop forever, so those
plugin config fields appeared permanently blank. The audit initially
flagged these files as dead code; the monorepo cross-check proved the
opposite — they were unreachable, not unused.

example-color-picker.js (the documented custom-widget example) gains an
explicit warning that including it in base.html would shadow the
built-in color-picker widget.

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

* chore: drop the legacy youtube block from the secrets template

No code reads a top-level youtube secrets key: the youtube-stats plugin
receives its API key namespaced under its own plugin id (declared via
x-secret in its config schema), like every other store plugin. The key
survives only in state_reconciliation.py's non-plugin-key exclusion set,
which stays — existing installs still carry the key in their generated
config_secrets.json, and the exclusion prevents it from being
misclassified as a plugin config. New installs simply stop being asked
for a YouTube API key they have nowhere to use.

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

* chore(deps): remove packages nothing imports, declare direct imports, move mypy to test deps

Removed from requirements.txt: python-socketio, python-engineio,
websockets, websocket-client — zero imports anywhere in this repo, and
the one store plugin that needs Socket.IO (ledmatrix-music) declares it
in its own requirements.txt, which the plugin store installs. Removed
the same quartet plus timezonefinder, geopy, google-auth-oauthlib,
google-auth-httplib2, google-api-python-client, unidecode, icalevents,
python-dateutil, flask-wtf and the werkzeug pin from
web_interface/requirements.txt — all leftovers from the deleted built-in
weather/calendar/music displays (flask-wtf was doubly dead: app.py
explicitly disables CSRF and sets csrf=None). scripts/
install_dependencies_apt.py, which mirrors these lists for the
first-time installer, drops the same packages.

Added: urllib3 (imported directly in four core modules), jinja2 and
markupsafe (imported directly in pages_v3.py) — previously reachable
only as transitives. mypy moves from runtime requirements to
requirements-test.txt.

Verified in a fresh venv: all four requirements files co-install, pip
check is clean, the full CI-enrolled suite (907 tests) and a Flask boot
smoke pass with the trimmed dependency set.

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

* refactor: single canonical DateTimeEncoder

src/cache_manager.py and src/cache/disk_cache.py each defined an
identical DateTimeEncoder (datetime -> ISO-8601). The disk_cache copy is
the only one actually used for serialization; cache_manager now
re-exports it instead of defining a twin, so the two can never silently
diverge. Import compatibility is preserved — from src.cache_manager
import DateTimeEncoder still works and is the same class object.

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

* docs(code): document deliberate duplicates instead of merging them

The audit surfaced several near-duplicate implementations that turned
out to be either deliberate forks or behaviorally different — merging
any of them would risk changing behavior on installed devices, so each
now carries an explicit comment stating the relationship:

- VisualDisplayManager: headless fork of DisplayManager; header now
  lists the ~15 mirrored methods and warns that DisplayManager changes
  must be mirrored.
- normalize_abbreviation: LogoDownloader's version (called directly by
  nine scoreboard plugins) replaces filesystem-unsafe characters;
  LogoHelper's strips spaces. Logo filenames on existing installs
  depend on both behaviors staying put.
- The two PluginTestBase classes: the shipped one is plugin-author
  API, the repo's own richer harness lives in test/plugins/ — now
  cross-referenced.

Also verified (no change needed): ConfigManager's backup/rollback
methods genuinely delegate to AtomicConfigManager, and SportsCore
already delegates _read_bdf_native_size to FontManager.

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

* docs: add a unified configuration reference

There was no single place documenting what lives in config.json —
display.* keys were scattered across README sections, vegas_scroll lived
in ADVANCED_FEATURES.md, and dim_schedule, display.double_sided,
sync.follower_position, plugin_system.development_mode and the four
newly-templated hardware keys were documented nowhere. CONFIG_REFERENCE.md
now lists every template key plus the code-read-only keys, each with
type, default, and the code location that reads it, and explains the
secrets file's plugin-id namespacing. Linked from the docs index.

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

* docs: bring the README's feature tour into the plugin era

The Core Features section still presented clock/weather/sports/stocks/
music displays as built into the project, when all of them are store
plugins installed from the ledmatrix-plugins monorepo — only
starlark-apps and web-ui-info ship in this repo. The intro now says so
(the showcase itself is unchanged; those are real displays available in
the store). The display_durations reference drops its built-in-calendar
example in favor of plugin-id keys, and the Configuration section links
the new CONFIG_REFERENCE.md.

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

* docs: archive the custom-icons status report, cross-link config docs, document assets/

PLUGIN_CUSTOM_ICONS_FEATURE.md was a 'What Was Implemented' status
report duplicating the actual guide (PLUGIN_CUSTOM_ICONS.md) — moved to
docs/archive/ per the docs index's own policy. The overlapping
plugin-config docs keep their content but PLUGIN_CONFIG_ARCHITECTURE.md
now states up front which doc is canonical for which purpose.

assets/README.md is new and load-bearing: assets/stocks, weather,
news_logos and broadcast_logos have zero references in this repo's code,
which makes them look deletable — but store plugins (ledmatrix-stocks,
ledmatrix-weather, news, odds-ticker) resolve those exact paths at
runtime against the install directory. The README records that evidence
so a future cleanup doesn't break installed plugins.

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

* test: add regression guards for the bug classes fixed in this PR

Three lightweight static checks, all enrolled in CI's unit-test
allowlist along with the new web-cache test:

- test_template_targets.py: every literal render_template() target must
  exist (would have caught the weather/stocks partial 500s at commit
  time).
- test_widget_scripts.py: every widget JS file must be script-included
  in base.html or explicitly allowlisted with a reason (would have
  caught the unloaded time-picker/file-upload-single/plugin-file-manager
  widgets), and allowlisted files must NOT be included (prevents the
  example widget from shadowing the real color-picker).
- test_doc_links.py: relative markdown links in active docs must
  resolve (docs/archive/ exempt).

Each guard was verified to fail against the pre-PR tree and pass now.

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

* fix(deps): restore the werkzeug version floor

Commit 1ec22db removed the werkzeug>=3.1.6,<4.0.0 pin along with the
genuinely-unused packages, but this one was a version floor on Flask's
transitive dependency, not a phantom: Flask 3.1.3 itself only requires
werkzeug>=3.1.0, so dropping the pin let fresh installs resolve
3.1.0-3.1.5. Restored with a comment explaining why it exists.

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

* fix(web): route pixel_mapper_config into display.hardware; guard time-picker registration

pixel_mapper_config was the only display.hardware key absent from both
the display_fields detection allowlist and the hardware write loop in
the settings save path. No form posts it today, but if one ever did the
key would fall through to the generic handler and land at the TOP level
of config.json — where state_reconciliation would mistake it for a
missing plugin id and loop auto-repair attempts (the failure class the
'github'/'youtube' exclusion comment documents). It now round-trips
into display.hardware like its siblings.

time-picker.js gains the same LEDMatrixWidgets-undefined guard its two
sibling widgets already have; correct today only via defer ordering.

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

* chore: align installer leftovers with the dependency cleanup

first_time_install.sh's fallback secrets heredoc (used only when the
template is missing) still wrote the legacy youtube block — now matches
the template (github only). install_dependencies_apt.py drops the
IMPORT_NAME_MAP entries for packages no longer in its install lists and
a stale google-api reference in a docstring.

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

* fix: address CodeRabbit review findings

Verified each finding against the code; fixes for the valid ones:

- install_dependencies_apt.py: the installer listed 'freetype', but the
  declared dependency is freetype-py — an apt miss would pip-install the
  wrong PyPI package. Now installs freetype-py with an import-name
  mapping (pre-existing bug, surfaced by the review).
- api_v3.py: pixel_mapper_config is validated as a string before being
  saved to display.hardware (JSON callers could previously store an
  object/list the matrix library can't use).
- .cursorrules: the Plugin Loading Process and File Organization
  sections still said discovery scans plugins/ — now consistent with the
  corrected overview (configured directory, default plugin-repos/).
- README.md: removed the stale '(except the core calendar)' claim — no
  core calendar exists in src/ — and qualified the plugin inventory
  (official plugins in the monorepo; third-party from their own repos).
- CONFIG_REFERENCE.md: hardware_mapping now shows the code fallback
  (adafruit-hat-pwm) alongside the template value.
- PLUGIN_REGISTRY_SETUP_GUIDE.md: check_plugin.py takes --plugin, not a
  positional id.
- scripts/fix_perms/fix_*.sh: exec bits set so the documented
  'sudo ./...' invocations work.
- Guard tests hardened: template guard now catches multi-line
  render_template() calls; widget guard parses actual <script> src
  values and fails if the widgets dir goes missing; type hints and
  docstrings added per repo coding guidelines.

Skipped with reasons (noted on the PR): limit_refresh_rate_hz 100-vs-90
is documented as intentional in CONFIG_REFERENCE.md; the psutil comment
already names the enforcing manifest; docs/archive/ findings are out of
scope per the docs policy (archive may rot).

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

* chore: remove Cursor IDE tooling, consolidate its guidance into CLAUDE.md

The maintainer no longer uses Cursor. .cursorrules, .cursorignore and the
.cursor/ tree (rules, plugin templates, a parallel 751-line plugins
guide) are removed; measurement showed near-zero literal overlap risk —
the canonical content already lives in docs/. Unique guidance worth
keeping moved before deletion:

- CLAUDE.md gains the dev workflow (dev_plugin_setup.sh, dev_server.py,
  run.py -e, check_plugin.py), the plugin-secrets namespacing contract,
  and the no-draw_image()/paste-onto-PIL pitfall.
- PLUGIN_DEVELOPMENT_GUIDE.md absorbs the plugin version-management
  rules (pre-push hook install, SKIP_TAG, version resolution order) that
  its own text previously linked out to .cursorrules for.
- The one completed plan doc (.cursor/plans/) is archived to
  docs/archive/ per the docs policy rather than deleted.

One of the deleted rule files (sports-managers.mdc) targeted
src/*_managers.py globs that have matched nothing since the plugin
migration.

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

* chore: second-pass cleanup — dead installer branch, broken script, orphaned JS, misfiled test deps

- first_time_install.sh: removed the pip fallback branch that installed
  from requirements_web_v2.txt — a file that has not existed since the
  v2 web interface was removed (the branch always printed its own
  'not found; skipping' warning).
- scripts/remove_plugin_backups.sh deleted: its PROJECT_ROOT resolved to
  the repo's PARENT directory, and its verify_submodules() checks for
  plugin submodules from an era before plugins moved to the store — it
  could never have worked from its current location.
- plugins_manager.js: removed three functions with zero call sites
  anywhere (addKeyValuePair, formatCommit, togglePasswordVisibility) —
  verified against all templates, all JS, and the dynamic window[name]
  dispatch sites, which resolve widget-registry keys only. Also replaced
  base.html's misleading 'Legacy ... during migration' label: the file
  is deliberately loaded last and provides the LIVE implementations of
  seven window.* plugin actions that shadow same-named definitions in
  app.js/app-shell.js.
- pytest/pytest-cov/pytest-mock moved from runtime requirements.txt to
  requirements-test.txt (CI already installs both files; the installer's
  line-by-line loop simply installs three fewer packages on devices; no
  store plugin declares pytest). HOW_TO_RUN_TESTS.md updated.
- scripts/add_defaults_to_schemas.py and analyze_plugin_schemas.py
  scanned the empty legacy plugins/ dir — now scan plugin-repos/.

Verified: fresh venv installs all four requirements files with pip check
clean and pytest available; bash -n on the installer; node --check on
the JS; widget/cache guard tests green.

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

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

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

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

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

* fix: raise the two new dependency floors past their CVEs, silence a deliberate re-export

All three of these were introduced by this PR, which is what makes them
worth fixing here rather than deferring.

`urllib3` and `jinja2` were added to the requirements so that direct
imports stop relying on transitives — right call, but both floors were
set to the version that introduced the API rather than a version that is
safe to install. `urllib3>=1.26.0` sits below roughly ten CVEs including
a decompression-bomb safeguard bypass, and `jinja2>=3.1.0` below five
including two sandbox breakouts. Raised to 2.7.0 and 3.1.6, which is what
a working device already runs, so no install is disturbed. The comments
now say the floor is a security floor, since the next person to read
"imported directly" would otherwise reasonably lower it again.

This is the same reasoning the PR already applied to werkzeug; these two
just missed it.

The `DateTimeEncoder` import in cache_manager is unused on purpose — the
canonical class moved to src.cache.disk_cache and this re-export keeps
the documented import path working. flake8 cannot see intent, so it gets
an explicit `# noqa: F401` rather than being removed and quietly breaking
anything importing it from here. Verified the re-export still resolves to
the same object and still serialises datetimes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Udr6MfaFLUPhX5Fgo67Jf5

* fix: address CodeRabbit re-review — installer robustness and doc lint

- install_dependencies_apt.py: an import-only check let Debian
  Bookworm's python3-freetype 2.3.0 satisfy the freetype-py>=2.5.1 pin.
  check_package_installed() now verifies the installed freetype-py
  version, and an apt install that lands below the minimum falls through
  to pip instead of counting as success.
- first_time_install.sh: the .web_deps_installed marker was created even
  when the smart installer failed, so re-runs skipped installation with
  dependencies missing. The marker is now created only on success.
- CONTRIBUTING.md: document installing the pre-commit CLI before
  'pre-commit install' (the requirements files don't provide it).
- Doc lint: fence language on the on-demand cache example (MD040),
  blockquote continuation in GETTING_STARTED (MD028), and the
  suppress_adapter_load_errors key removed from the emulator debug
  example to match the options table.

Skipped one finding with reason (noted on the PR): the per-plugin
display_duration field in PLUGIN_QUICK_REFERENCE's example is not
obsolete — BasePlugin.get_display_duration() reads it and
PLUGIN_CONFIG_CORE_PROPERTIES.md documents it as a core property;
display.display_durations is a per-mode override, not a replacement.

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

docs/ADVANCED_FEATURES.md

@@ -47,6 +47,11 @@ 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 |
@@ -57,7 +62,11 @@ Enable Vegas mode in `config/config.json`:
 | `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 panels to render ahead |
+| `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).
 
 ### Per-Plugin Configuration
 
@@ -79,9 +88,13 @@ Override Vegas behavior for specific plugins:
 | Setting | Values | Description |
 |---------|--------|-------------|
 | `vegas_mode` | `scroll`, `fixed`, `static` | Display mode for this plugin |
-| `vegas_panel_count` | `1-10` | Width in panels (1 panel = display width) |
+| `vegas_panel_count` | any positive integer | 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:**
@@ -451,7 +464,7 @@ time when something is active.
 
 ### REST API Reference
 
-The API is mounted at `/api/v3` (`web_interface/app.py:144`).
+The API is mounted at `/api/v3` (`web_interface/app.py:199`).
 
 #### Start On-Demand Display
 
@@ -518,13 +531,15 @@ 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), 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
+> 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
 > `display_on_demand_config` key is used by the controller itself
-> during activation to track what's currently running (written at
-> `display_controller.py:1195`, cleared at `:1221`).
+> during activation (`_activate_on_demand()`) to track what's
+> currently running, and is cleared by `_clear_on_demand()`.
 
 ### Duration Modes
 
@@ -646,13 +661,13 @@ keys helps troubleshoot stuck states.
 **When Set:** Every display loop iteration
 **Auto-Cleared:** Never (continuously updated)
 
-**4. display_on_demand_processed_id** (TTL: 5 minutes)
-```
+**4. display_on_demand_processed_id** (TTL: 1 hour)
+```text
 "uuid-string-of-last-processed-request"
 ```
 **Purpose:** Prevents duplicate request processing
 **When Set:** After processing request
-**Auto-Cleared:** After 5 minutes TTL
+**Auto-Cleared:** After 1 hour TTL
 
 ### When Manual Clearing is Needed
 
@@ -685,9 +700,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)
-- `~/.cache/ledmatrix/`
+- `~/.ledmatrix_cache/`
 - `/opt/ledmatrix/cache/`
-- `/tmp/ledmatrix-cache/` (fallback)
+- `$TMPDIR/ledmatrix_cache/` (fallback)
 
 ```bash
 # Find the cache dir actually in use
@@ -711,8 +726,9 @@ cache.clear_cache('display_on_demand_request')
 cache.clear_cache('display_on_demand_processed_id')
 ```
 
-> The actual public method is `clear_cache(key=None)` — there is no
-> `delete()` method on `CacheManager`.
+> `CacheManager` also has a `delete(key)` method — a thin wrapper over
+> `clear_cache(key)` — so `cache.delete('display_on_demand_config')`
+> works equally well.
 
 ### Cache Impact on Running Service
 
@@ -730,7 +746,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 5 minutes TTL
+- **Processed ID**: Expires after 1 hour TTL
 
 ---
 
@@ -821,9 +837,6 @@ 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"
 ```
@@ -832,9 +845,10 @@ sudo journalctl -u ledmatrix -f | grep "background"
 
 **View Statistics:**
 ```python
-from src.background_data_service import BackgroundDataService
+from src.background_data_service import get_background_service
+from src.cache_manager import CacheManager
 
-service = BackgroundDataService()
+service = get_background_service(CacheManager())
 stats = service.get_statistics()
 print(f"Active tasks: {stats['active_tasks']}")
 print(f"Completed: {stats['completed']}")
@@ -875,6 +889,7 @@ 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
 )
@@ -883,7 +898,10 @@ from src.common.permission_utils import (
 ensure_directory_permissions(Path("assets/sports"), get_assets_dir_mode())
 
 # Set file permissions after writing
-ensure_file_permissions(Path("config/config.json"), get_config_file_mode())
+# (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))
 ```
 
 ### When to Use Utilities
@@ -938,7 +956,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())
+ensure_file_permissions(config_path, get_config_file_mode(config_path))
 ```
 
 **Pattern 3: Downloading Logo**
@@ -984,8 +1002,11 @@ These core utilities **already handle permissions** - you don't need to call per
 If you encounter permission issues:
 
 ```bash
-# Fix all permissions at once
-sudo ./scripts/fix_permissions.sh
+# 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 specific directory
 sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix/config
@@ -1017,7 +1038,7 @@ stat -c "%a %n" config/config.json
 
 ## Related Documentation
 
-- [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) - Creating plugins with Vegas/on-demand support
+- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.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

@@ -0,0 +1,172 @@
+# 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 [API_REFERENCE.md](API_REFERENCE.md) for complete documentation.
+See [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for complete documentation.
 
 ## Display Manager Quick Methods
 
@@ -190,12 +190,13 @@ def display(self, force_clear=False):
 
 ```
 LEDMatrix/
-├── plugins/              # Installed plugins
+├── plugin-repos/         # Installed plugins (default; plugins/ is only
+│                         #   for dev symlinks via scripts/dev/dev_plugin_setup.sh)
 ├── config/
 │   ├── config.json      # Main configuration
 │   └── config_secrets.json  # API keys and secrets
 ├── docs/                 # Documentation
-│   ├── API_REFERENCE.md
+│   ├── REST_API_REFERENCE.md
 │   ├── PLUGIN_API_REFERENCE.md
 │   └── ...
 └── src/
@@ -207,7 +208,7 @@ LEDMatrix/
 
 ## Quick Links
 
-- [Complete API Reference](API_REFERENCE.md)
+- [Complete REST API Reference](REST_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,23 +69,24 @@ default configuration as it ships in the repo:
 ```json
 {
     "pixel_outline": 0,
-    "pixel_size": 5,
+    "pixel_size": 16,
     "pixel_style": "square",
     "pixel_glow": 6,
-    "display_adapter": "pygame",
+    "display_adapter": "browser",
+    "allow_adapter_fallback": true,
     "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": 24,
+        "target_fps": 60,
         "fps_display": false,
         "quality": 70,
         "image_border": true,
         "debug_text": false,
-        "image_format": "JPEG"
+        "image_format": "JPEG",
+        "open_immediately": false
     },
     "log_level": "info"
 }
@@ -96,13 +97,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 | 5 | 1-64 (8–16 is typical for testing) |
+| `pixel_size` | Size of each pixel | 16 | 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 | "pygame" | "pygame", "browser" |
+| `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 |
 | `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
 
@@ -111,18 +112,32 @@ When using the browser adapter, additional options are available:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `port` | Web server port | 8888 |
-| `target_fps` | Target frames per second | 24 |
+| `target_fps` | Target frames per second | 60 |
 | `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. Set Environment Variable
+### 1. Use the `-e` Flag (Recommended)
 
-Enable emulator mode by setting the `EMULATOR` 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:
 
 **Windows (Command Prompt):**
 ```cmd
@@ -137,15 +152,6 @@ 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
 ```
@@ -153,7 +159,8 @@ EMULATOR=true python3 run.py
 ### 3. Verify Emulator Mode
 
 When running in emulator mode, you should see:
-- A window displaying the LED matrix simulation
+- The emulated matrix — a web page at `http://localhost:8888` with the
+  default browser adapter, or a desktop window with the pygame adapter
 - Console output indicating emulator mode
 - No hardware initialization errors
 
@@ -161,7 +168,36 @@ When running in emulator mode, you should see:
 
 LEDMatrix supports two display adapters for the emulator:
 
-### 1. Pygame Adapter (Default)
+### 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)
 
 The pygame adapter provides a native desktop window with real-time display.
 
@@ -186,33 +222,6 @@ 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
@@ -274,8 +283,7 @@ Enable debug logging:
 ```json
 {
     "log_level": "debug",
-    "suppress_font_warnings": false,
-    "suppress_adapter_load_errors": false
+    "suppress_font_warnings": false
 }
 ```
 
@@ -299,17 +307,18 @@ Modify the display dimensions in your main config:
 
 ### 2. Plugin Development
 
-For plugin development with the emulator:
+`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:
 
 ```bash
-# Enable emulator mode
-export EMULATOR=true
+# Run the full display in emulator mode (optionally with debug logging)
+python3 run.py -e -d
 
-# Run with specific plugin
-python run.py --plugin my-plugin
+# Live single-plugin preview in the browser (port 5001)
+python3 scripts/dev_server.py
 
-# Debug mode
-python run.py --debug
+# Headless render/validation of one plugin
+python3 scripts/check_plugin.py --plugin my-plugin
 ```
 
 ### 3. Performance Tuning
@@ -344,11 +353,10 @@ The emulator can work alongside the web interface:
 
 ```bash
 # Terminal 1: Start emulator
-export EMULATOR=true
-python run.py
+python3 run.py -e
 
-# Terminal 2: Start web interface
-python web_interface/app.py
+# Terminal 2: Start web interface (supported entry point)
+python3 web_interface/start.py
 ```
 
 Access the web interface at `http://localhost:5000` while the emulator runs.
@@ -365,13 +373,14 @@ Access the web interface at `http://localhost:5000` while the emulator runs.
 ### 2. Plugin Testing
 
 ```bash
-# Test specific plugin
-export EMULATOR=true
-python run.py --plugin clock-simple
+# Test a specific plugin (headless check)
+python3 scripts/check_plugin.py --plugin clock-simple
 
-# Test all plugins
-export EMULATOR=true
-python run.py --test-plugins
+# 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
 ```
 
 ### 3. Configuration Management
@@ -385,9 +394,8 @@ python run.py --test-plugins
 ### Basic Clock Display
 
 ```bash
-# Start emulator with clock
-export EMULATOR=true
-python run.py
+# Start emulator with clock enabled in config.json
+python3 run.py -e
 ```
 
 ### Sports Scores
@@ -395,16 +403,16 @@ python run.py
 ```bash
 # Configure for sports display
 # Edit config/config.json to enable sports plugins
-export EMULATOR=true
-python run.py
+python3 run.py -e
 ```
 
 ### Custom Text Display
 
 ```bash
-# Use text display plugin
-export EMULATOR=true
-python run.py --plugin text-display --text "Hello World"
+# 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
 ```
 
 ## Support

docs/GETTING_STARTED.md

@@ -21,18 +21,30 @@ This guide will help you set up your LEDMatrix display for the first time and ge
 
 ---
 
-## Quick Start (5 Minutes)
+## Quick Start
 
-### 1. First Boot
+### 1. Install LEDMatrix
 
-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)
+There is no prebuilt SD card image — you install LEDMatrix onto stock
+Raspberry Pi OS Lite yourself:
 
-**Expected Behavior:**
+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:**
 - LED matrix will light up
-- Display will show default plugins (clock, weather, etc.)
+- 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
 - Pi creates WiFi network "LEDMatrix-Setup" if not connected
 
 ### 2. Connect to WiFi
@@ -73,7 +85,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 16–128 range, but 64 and 96 are the values the bundled
+     in the 1–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
@@ -115,11 +127,16 @@ 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, display duration, etc.)
+   update intervals, 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
@@ -208,12 +225,14 @@ The fastest way to verify a plugin works without waiting for the rotation:
 ### Customize Your Display
 
 **Adjust display durations:**
-- Each plugin's tab has a **Display Duration (seconds)** field — set how
-  long that plugin stays on screen each rotation.
+- 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`).
 
 **Organize plugin order:**
-- Use the **Plugin Manager** tab to enable/disable plugins. The display
-  cycles through enabled plugins in the order they appear.
+- 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.
 
 **Add more plugins:**
 - Check the **Plugin Store** section of **Plugin Manager** for new plugins.
@@ -280,10 +299,14 @@ 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()`)
@@ -303,11 +326,14 @@ 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,10 +10,7 @@ Make sure you have the testing packages installed:
 
 ```bash
 # Install all dependencies including test packages
-pip install -r requirements.txt
-
-# Or install just the test dependencies
-pip install pytest pytest-cov pytest-mock
+pip install -r requirements.txt -r requirements-test.txt
 ```
 
 ### 2. Set Environment Variables
@@ -253,7 +250,6 @@ 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
@@ -303,7 +299,7 @@ If tests fail due to missing packages:
 
 ```bash
 # Install all dependencies
-pip install -r requirements.txt
+pip install -r requirements.txt -r requirements-test.txt
 
 # Or install specific missing package
 pip install <package-name>
@@ -335,15 +331,15 @@ pytest --cov=src --cov-report=html
 
 ## Continuous Integration
 
-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.
+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.
 
 ## 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 [README.md](README.md) for current installation and usage instructions
+1. Check the [project root README](../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,8 +201,9 @@ the mode selector for this plugin.
 
 #### `get_vegas_segment_width() -> Optional[int]`
 
-For `FIXED_SEGMENT` plugins, the width in pixels of the segment they
-occupy in the scroll. `None` lets the controller pick a default.
+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.
 
 > 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,9 +8,12 @@
 > - 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:144`).
+>   blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
 > - 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,5 +1,11 @@
 # 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_docs/) - How to create plugins
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - 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](docs/plugin_development.md)
-- [Troubleshooting Quick Start](TROUBLESHOOTING_QUICK_START.md)
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
 

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -589,11 +589,24 @@ Your plugin must:
 ### Versioning Best Practices
 
 - **Use semantic versioning**: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
-- **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
+- **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):
 
-See the [Git Workflow rules](../.cursorrules) for version management details.
+  ```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).
 
 ### Submitting to Official Registry
 
@@ -667,5 +680,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 User Guide](PLUGIN_STORE_USER_GUIDE.md) - Using the plugin store
+- [Plugin Store Guide](PLUGIN_STORE_GUIDE.md) - Using the plugin store
 

docs/PLUGIN_QUICK_REFERENCE.md

@@ -14,8 +14,10 @@ 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/`; the loader also searches
-   `plugins/` as a fallback)
+   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/`)
 
 ## File Structure
 
@@ -109,7 +111,7 @@ git push -u origin main
 git tag v1.0.0
 git push origin v1.0.0
 
-# Submit to registry (PR to ChuckBuilds/ledmatrix-plugin-registry)
+# Submit to registry (PR to ChuckBuilds/ledmatrix-plugins)
 ```
 
 ## Using Plugins
@@ -120,12 +122,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**: order is set by the position in `display_modes` /
-   plugin order; rearranging via drag-and-drop is not yet supported
+5. **Reorder**: use the drag-and-drop **Rotation Order** list in the
+   **Rotation** tab (saved to `display.plugin_rotation_order`)
 
 ### REST API
 
-The API is mounted at `/api/v3` (`web_interface/app.py:144`).
+The API is mounted at `/api/v3` (`web_interface/app.py:199`).
 
 ```bash
 # Install plugin from the registry

docs/PLUGIN_REGISTRY_SETUP_GUIDE.md

@@ -323,16 +323,22 @@ curl -X POST http://pi:5000/api/v3/plugins/install-from-url \
 ### Regular Updates
 
 ```bash
-# Update stars/downloads counts
-python3 scripts/update_stats.py
+# Refresh local clones of all plugin repos
+python3 scripts/update_plugin_repos.py
 
-# Validate all plugin entries
-python3 scripts/validate_registry.py
+# (Re-)create local plugin repo checkouts from the registry
+python3 scripts/setup_plugin_repos.py
 
-# Check for plugin updates
-python3 scripts/check_updates.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>
 ```
 
+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:
@@ -400,7 +406,7 @@ print(f'Found {len(registry[\"plugins\"])} plugins')
 
 ## References
 
-- Plugin Store Implementation: See `PLUGIN_STORE_IMPLEMENTATION_SUMMARY.md`
-- User Guide: See `PLUGIN_STORE_USER_GUIDE.md`
+- Plugin Store Implementation: See `PLUGIN_IMPLEMENTATION_SUMMARY.md`
+- User Guide: See `PLUGIN_STORE_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.md](PLUGIN_DEVELOPMENT.md) for instructions.
+A: Yes! See [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) for instructions.
 
 ---
 
 ## Related Documentation
 
-- [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) - Create your own plugins
+- [PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md) - Create your own plugins
 - [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md) - Plugin API documentation
-- [PLUGIN_ARCHITECTURE.md](PLUGIN_ARCHITECTURE.md) - Plugin system architecture
+- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) - Plugin system architecture (historical)
 - [REST_API_REFERENCE.md](REST_API_REFERENCE.md) - Complete REST API reference

docs/README.md

@@ -29,15 +29,16 @@ Start here:
 Going deeper:
 
 - [ADVANCED_PLUGIN_DEVELOPMENT.md](ADVANCED_PLUGIN_DEVELOPMENT.md) — advanced patterns
-- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — full plugin-system spec
+- [PLUGIN_ARCHITECTURE_SPEC.md](PLUGIN_ARCHITECTURE_SPEC.md) — original plugin-system design spec (historical; see its banner for what has drifted)
 - [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_FEATURE.md](PLUGIN_CUSTOM_ICONS_FEATURE.md)
+- [PLUGIN_CUSTOM_ICONS.md](PLUGIN_CUSTOM_ICONS.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
 
@@ -52,9 +53,12 @@ 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
@@ -66,6 +70,7 @@ 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:144`).
+> The API blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
 > SSE stream endpoints (`/api/v3/stream/*`) are defined directly on the
-> Flask app at `app.py:607-615`. There are about 92 routes total — see
+> Flask app at `app.py:799-809`. There are 94 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 `src/base_classes/sports.py`) renders through exactly one seam:
+built on the `src/base_classes/sports/` package, `core.py`) renders through exactly one seam:
 `SportsCore._render_game(game, force_clear)`.
 
 1. The mode class's `display()` (live, `SportsUpcoming`, `SportsRecent`)

docs/TROUBLESHOOTING.md

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

docs/WEB_INTERFACE_GUIDE.md

@@ -39,12 +39,18 @@ 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)
+  mapping, GPIO slowdown, brightness, PWM) and Vegas Scroll Mode
+  settings
+- **Rotation** — drag-and-drop **Rotation Order** list and per-plugin
+  **Screen Durations**
 - **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:
 
@@ -111,6 +117,12 @@ 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
@@ -159,9 +171,10 @@ Manage fonts for your display:
 - See font previews
 - Check font sizes and styles
 
-**Plugin Font Overrides:**
-- Set custom fonts for specific plugins
-- Override default font choices
+**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
 - Preview font changes
 
 **Delete Fonts:**
@@ -183,9 +196,11 @@ 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
-- **Pause**: Pause auto-scrolling
+- **Auto-scroll** checkbox: toggle automatic scrolling to the latest
+  entries
 
 ---
 
@@ -248,7 +263,8 @@ The web interface uses Server-Sent Events (SSE) for real-time updates:
 **Performance:**
 - Minimal bandwidth usage
 - Server-side rendering for fast load times
-- Progressive enhancement - works without JavaScript
+- The UI is built on Alpine.js and HTMX, so JavaScript must be enabled
+  in the browser
 
 ---
 
@@ -267,17 +283,6 @@ 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:
@@ -288,7 +293,7 @@ http://your-pi-ip:5000/api/v3
 ```
 
 The API blueprint mounts at `/api/v3` (see
-`web_interface/app.py:144`). All endpoints below are relative to that
+`web_interface/app.py:199`). All endpoints below are relative to that
 base.
 
 **Common Endpoints:**

docs/archive/CURSOR_PLUGIN_SCHEMA_AUDIT_PLAN.md

@@ -0,0 +1,202 @@
+# Implementation Plan: Fix Config Schema Validation Issues
+
+Based on audit results showing 186 issues across 20 plugins.
+
+## Overview
+
+Three priority fixes identified from audit:
+1. **Priority 1 (HIGH)**: Remove core properties from required array - will fix ~150 issues
+2. **Priority 2 (MEDIUM)**: Verify default merging logic - will fix remaining required field issues
+3. **Priority 3 (LOW)**: Calendar plugin schema cleanup - will fix 3 extra field warnings
+
+## Priority 1: Remove Core Properties from Required Array
+
+### Problem
+Core properties (`enabled`, `display_duration`, `live_priority`) are system-managed but listed in schema `required` arrays. SchemaManager injects them into properties but doesn't remove them from `required`, causing validation failures.
+
+### Solution
+**File**: `src/plugin_system/schema_manager.py`
+**Location**: `validate_config_against_schema()` method, after line 295
+
+### Implementation Steps
+
+1. **Add code to remove core properties from required array**:
+   ```python
+   # After injecting core properties (around line 295), add:
+   # Remove core properties from required array (they're system-managed)
+   if "required" in enhanced_schema:
+       core_prop_names = list(core_properties.keys())
+       enhanced_schema["required"] = [
+           field for field in enhanced_schema["required"] 
+           if field not in core_prop_names
+       ]
+   ```
+
+2. **Add logging for debugging** (optional but helpful):
+   ```python
+   if "required" in enhanced_schema and core_prop_names:
+       removed_from_required = [
+           field for field in enhanced_schema.get("required", [])
+           if field in core_prop_names
+       ]
+       if removed_from_required and plugin_id:
+           self.logger.debug(
+               f"Removed core properties from required array for {plugin_id}: {removed_from_required}"
+           )
+   ```
+
+3. **Test the fix**:
+   - Run audit script: `python scripts/audit_plugin_configs.py`
+   - Expected: Issue count drops from 186 to ~30-40
+   - All "enabled" related errors should be eliminated
+
+### Expected Outcome
+- All 20 plugins should no longer fail validation due to missing `enabled` field
+- ~150 issues resolved (all enabled-related validation errors)
+
+## Priority 2: Verify Default Merging Logic
+
+### Problem
+Some plugins have required fields with defaults that should be applied before validation. Need to verify the default merging happens correctly and handles nested objects.
+
+### Solution
+**File**: `web_interface/blueprints/api_v3.py`
+**Location**: `save_plugin_config()` method, around lines 3218-3221
+
+### Implementation Steps
+
+1. **Review current default merging logic**:
+   - Check that `merge_with_defaults()` is called before validation (line 3220)
+   - Verify it's called after preserving enabled state but before validation
+
+2. **Verify merge_with_defaults handles nested objects**:
+   - Check `src/plugin_system/schema_manager.py` → `merge_with_defaults()` method
+   - Ensure it recursively merges nested objects (it does use deep_merge)
+   - Test with plugins that have nested required fields
+
+3. **Check if defaults are applied for nested required fields**:
+   - Review how `generate_default_config()` extracts defaults from nested schemas
+   - Verify nested required fields with defaults are included
+
+4. **Test with problematic plugins**:
+   - `ledmatrix-weather`: required fields `api_key`, `location_city` (check if defaults exist)
+   - `mqtt-notifications`: required field `mqtt` object (check if default exists)
+   - `text-display`: required field `text` (check if default exists)
+   - `ledmatrix-music`: required field `preferred_source` (check if default exists)
+
+5. **If defaults don't exist in schemas**:
+   - Either add defaults to schemas, OR
+   - Make fields optional in schemas if they're truly optional
+
+### Expected Outcome
+- Plugins with required fields that have schema defaults should pass validation
+- Issue count further reduced from ~30-40 to ~5-10
+
+## Priority 3: Calendar Plugin Schema Cleanup
+
+### Problem
+Calendar plugin config has fields not in schema:
+- `show_all_day` (config) but schema has `show_all_day_events` (field name mismatch)
+- `date_format` (not in schema, not used in manager.py)
+- `time_format` (not in schema, not used in manager.py)
+
+### Investigation Results
+- Schema defines: `show_all_day_events` (boolean, default: true)
+- Manager.py uses: `show_all_day_events` (line 82: `config.get('show_all_day_events', True)`)
+- Config has: `show_all_day` (wrong field name - should be `show_all_day_events`)
+- `date_format` and `time_format` appear to be deprecated (not used in manager.py)
+
+### Solution
+
+**File**: `config/config.json` → `calendar` section
+
+### Implementation Steps
+
+1. **Fix field name mismatch**:
+   - Rename `show_all_day` → `show_all_day_events` in config.json
+   - This matches the schema and manager.py code
+
+2. **Remove deprecated fields**:
+   - Remove `date_format` from config (not used in code)
+   - Remove `time_format` from config (not used in code)
+
+3. **Alternative (if fields are needed)**: Add `date_format` and `time_format` to schema
+   - Only if these fields should be supported
+   - Check if they're used anywhere else in the codebase
+
+4. **Test calendar plugin**:
+   - Run audit for calendar plugin specifically
+   - Verify no extra field warnings remain
+   - Test calendar plugin functionality to ensure it still works
+
+### Expected Outcome
+- Calendar plugin shows 0 extra field warnings
+- Final issue count: ~3-5 (only edge cases remain)
+
+## Testing Strategy
+
+### After Each Priority Fix
+
+1. **Run local audit**:
+   ```bash
+   python scripts/audit_plugin_configs.py
+   ```
+
+2. **Check issue count reduction**:
+   - Priority 1: Should drop from 186 to ~30-40
+   - Priority 2: Should drop from ~30-40 to ~5-10
+   - Priority 3: Should drop from ~5-10 to ~3-5
+
+3. **Review specific plugin results**:
+   ```bash
+   python scripts/audit_plugin_configs.py --plugin <plugin-id>
+   ```
+
+### After All Fixes
+
+1. **Full audit run**:
+   ```bash
+   python scripts/audit_plugin_configs.py
+   ```
+
+2. **Deploy to Pi**:
+   ```bash
+   ./scripts/deploy_to_pi.sh src/plugin_system/schema_manager.py web_interface/blueprints/api_v3.py
+   ```
+
+3. **Run audit on Pi**:
+   ```bash
+   ./scripts/run_audit_on_pi.sh
+   ```
+
+4. **Manual web interface testing**:
+   - Access each problematic plugin's config page
+   - Try saving configuration
+   - Verify no validation errors appear
+   - Check that configs save successfully
+
+## Success Criteria
+
+- [ ] Priority 1: All "enabled" related validation errors eliminated
+- [ ] Priority 1: Issue count reduced from 186 to ~30-40
+- [ ] Priority 2: Plugins with required fields + defaults pass validation
+- [ ] Priority 2: Issue count reduced to ~5-10
+- [ ] Priority 3: Calendar plugin extra field warnings resolved
+- [ ] Priority 3: Final issue count at ~3-5 (only edge cases)
+- [ ] All fixes work on Pi (not just local)
+- [ ] Web interface saves configs without validation errors
+
+## Files to Modify
+
+1. `src/plugin_system/schema_manager.py` - Remove core properties from required array
+2. `plugins/calendar/config_schema.json` OR `config/config.json` - Calendar cleanup (if needed)
+3. `web_interface/blueprints/api_v3.py` - May need minor adjustments for default merging (if needed)
+
+## Risk Assessment
+
+**Priority 1**: Low risk - Only affects validation logic, doesn't change behavior
+**Priority 2**: Low risk - Only ensures defaults are applied (already intended behavior)
+**Priority 3**: Very low risk - Only affects calendar plugin, cosmetic issue
+
+All changes are backward compatible and improve the system rather than changing core functionality.
+