fix(debug): let Companion-app users get a debug snapshot without a browser

[chalfontchubby]

Summary

• The HA Companion app's embedded webview ignores Content-Disposition: attachment, so the Debug panel's .tgz/single-file download links just render the content inline instead of saving it - a client-side limitation with no server fix, discussed in Rolling debug logs not accessible with HA Companion app #4720.
• Every rolling debug-history snapshot (Rolling debug-snapshot buffer with configurable interval/count, and a download UI #4417) is now written straight to config_root/debug/ - the same directory switch.predbat_debug_enable already uses - via new save_debug_copy()/load_debug_copy()/delete_debug_copy() methods on the Storage abstraction, so a Companion-app user can grab one with File Editor/Samba instead of the browser-only download routes.
• The dashboard's Debug panel and docs/customisation.md now say so.
• An install upgrading straight from before this change still has its existing snapshots readable (and eventually cleaned up) via a legacy-key fallback - see "Note on storage layout" below.

Note on storage layout

cache/ is generally the right place for cache-like, regenerable data, and this PR deliberately doesn't put snapshot content there - it goes straight to debug/, with only the small index staying in cache/. That's a pragmatic workaround for this specific problem (a real file on disk is what makes it reachable from the Companion app at all), not a new general pattern - it works here because create_debug_yaml() already writes unconditionally to that same real directory for switch.predbat_debug_enable, so nothing here is any more filesystem-dependent than the feature it's capturing snapshots of.

Test plan

• ./run_pre_commit (ruff, black, cspell, markdownlint, interrogate 100% on touched files) - green
• ./run_all --quick - green, including new tests for: the debug/ write/read/delete path, the pre-Rolling debug logs not accessible with HA Companion app #4720 legacy-key fallback (read) and reap (on eviction) on a real Storage backend, and the dashboard's Companion-app caveat text

Fixes #4720

[Copilot]

🟡 Changes recommended

Failed debug-file writes are currently recorded as successful captures.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Moves rolling debug snapshots into config_root/debug/ so Companion-app users can access them via File Editor or Samba.

Changes:

• Adds debug-file operations to the storage abstraction.
• Preserves legacy cached snapshots during upgrades.
• Updates dashboard guidance, documentation, and tests.

File summaries

File	Description
docs/customisation.md	Documents Companion-app workaround and snapshot location.
apps/predbat/web.py	Adds dashboard guidance.
apps/predbat/storage.py	Implements debug-directory storage operations.
apps/predbat/debug_history.py	Stores snapshots in debug/ with legacy fallback.
apps/predbat/tests/test_web_functions.py	Tests dashboard guidance.
apps/predbat/tests/test_storage.py	Tests debug-file operations.
apps/predbat/tests/test_debug_history.py	Tests retention and migration behavior.
apps/predbat/tests/test_debug_history_capture.py	Verifies snapshots are written to debug/.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.