docs: initialize project

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: FireSon

.planning/PROJECT.md

@@ -0,0 +1,75 @@
+# Zendure HA — Codebase Quality Sweep
+
+## What This Is
+
+A comprehensive quality pass on the Zendure Home Assistant integration — a custom component that manages Zendure solar/battery devices via MQTT and BLE. The goal is to audit the entire codebase, fix bugs, clean up code structure, and improve reliability and performance.
+
+## Core Value
+
+Clean, reliable code that a developer can confidently read, extend, and maintain.
+
+## Requirements
+
+### Validated
+
+- ✓ Home Assistant integration with config flow — existing
+- ✓ Cloud MQTT device communication — existing
+- ✓ Local MQTT support — existing
+- ✓ BLE device communication via ZenSDK — existing
+- ✓ Power distribution and management — existing
+- ✓ Multi-device support (SolarFlow, Hub, ACE, AIO, Hyper) — existing
+- ✓ Entity auto-creation from device properties — existing
+- ✓ State persistence across restarts — existing
+- ✓ Fuse group power constraints — existing
+- ✓ P1 meter integration for smart matching — existing
+
+### Active
+
+- [ ] Fix known bugs (attribute name typos, missing base class attributes)
+- [ ] Replace broad exception handling with specific exception types
+- [ ] Clean up code structure (reduce complexity, extract methods)
+- [ ] Improve thread/async safety in MQTT callbacks
+- [ ] Remove credentials from log output
+- [ ] Replace datetime sentinel values with explicit state tracking
+- [ ] Improve BLE connection reliability
+- [ ] Optimize performance (BLE scanner caching, power calculation caching)
+- [ ] Add MQTT payload validation
+
+### Out of Scope
+
+- New device support — this is a quality pass, not a feature release
+- Test infrastructure — separate initiative after code is clean
+- Migration from paho-mqtt to async MQTT — major change, defer
+- UI/dashboard changes — not part of codebase cleanup
+- SHA1/MD5 replacement — constrained by Zendure API requirements
+
+## Context
+
+This is a brownfield Home Assistant custom integration with ~1500 lines across core modules. The codebase has no tests, broad exception handling throughout, and several known bugs identified during mapping. The integration supports multiple Zendure device families via MQTT (cloud and local) and BLE protocols, with a power distribution algorithm managing charge/discharge across devices.
+
+Key concerns from codebase audit:
+- **27 broad exception handlers** masking specific failures
+- **Attribute name typo** (`hemsStateUpdate` vs `hemsStateUpdated`) causing runtime errors
+- **Missing base class attribute** (`aggrOffGrid`) causing AttributeError on some device types
+- **Credentials logged** in plaintext
+- **Complex methods** with high cyclomatic complexity (entityUpdate, powerChanged)
+- **Thread safety issues** in MQTT callback handlers
+
+## Constraints
+
+- **Compatibility**: Must remain compatible with Home Assistant 2026.2.0+
+- **Protocol**: SHA1/MD5 usage is dictated by Zendure's cloud API — cannot change unilaterally
+- **Dependencies**: paho-mqtt 2.1.0 is the current MQTT client — no library migration in this scope
+- **Behavior**: Existing functionality must continue working — this is cleanup, not redesign
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Full sweep, no off-limits areas | User wants comprehensive cleanup | — Pending |
+| Keep external behavior identical | Quality pass should not break existing setups | — Pending |
+| Defer test infrastructure | Clean code first, then add tests | — Pending |
+| Defer async MQTT migration | Too large for a quality pass | — Pending |
+
+---
+*Last updated: 2026-03-27 after initialization*