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/ADVANCED_FEATURES.md

@@ -984,8 +984,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
+# Targeted permission fixes (see scripts/fix_perms/README.md)
-sudo ./scripts/fix_permissions.sh
+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 +1020,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/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
 
@@ -195,7 +195,7 @@ LEDMatrix/
 │   ├── 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 +207,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/HOW_TO_RUN_TESTS.md

@@ -335,15 +335,15 @@ pytest --cov=src --cov-report=html
 
 ## Continuous Integration
 
-The repo runs
+The repo runs the pytest suite via
-[`.github/workflows/security-audit.yml`](../.github/workflows/security-audit.yml)
+[`.github/workflows/test.yml`](../.github/workflows/test.yml) on every
-(bandit + semgrep) on every push. A pytest CI workflow at
+push and pull request: a plugin-safety job (harness, visual rendering
-`.github/workflows/tests.yml` is queued to land alongside this
+and plugin-matrix tests) plus a unit-test job that runs an explicit
-PR ([ChuckBuilds/LEDMatrix#307](https://github.com/ChuckBuilds/LEDMatrix/pull/307));
+allowlist of suites — new test files must be added to that list to run
-the workflow file itself was held back from that PR because the
+in CI. Release version consistency is checked by
-push token lacked the GitHub `workflow` scope, so it needs to be
+[`.github/workflows/release-version-check.yml`](../.github/workflows/release-version-check.yml).
-committed separately by a maintainer. Once it's in, this section
+Bandit, flake8, mypy and gitleaks run as pre-commit hooks (see
-will be updated to describe what the job runs.
+`.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_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)
+- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)
-- [Troubleshooting Quick Start](TROUBLESHOOTING_QUICK_START.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
 

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -667,5 +667,5 @@ For your plugin to work well in the plugin store:
 - [Advanced Plugin Development](ADVANCED_PLUGIN_DEVELOPMENT.md) - Advanced patterns and examples
 - [Plugin Quick Reference](PLUGIN_QUICK_REFERENCE.md) - Quick development reference
 - [Plugin Configuration Guide](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup
-- [Plugin Store User Guide](PLUGIN_STORE_USER_GUIDE.md) - Using the plugin store
+- [Plugin Store Guide](PLUGIN_STORE_GUIDE.md) - Using the plugin store
 

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
+# Refresh local clones of all plugin repos
-python3 scripts/update_stats.py
+python3 scripts/update_plugin_repos.py
 
-# Validate all plugin entries
+# (Re-)create local plugin repo checkouts from the registry
-python3 scripts/validate_registry.py
+python3 scripts/setup_plugin_repos.py
 
-# Check for plugin updates
+# Audit installed plugins for manifest/schema problems
-python3 scripts/check_updates.py
+python3 scripts/audit_plugins.py
+
+# Validate a single plugin
+python3 scripts/check_plugin.py <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`
+- Plugin Store Implementation: See `PLUGIN_IMPLEMENTATION_SUMMARY.md`
-- User Guide: See `PLUGIN_STORE_USER_GUIDE.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