Docs: reflect this session's findings across the repo

- top-level README.md (new): system overview, subsystem map, skills pointer,
  notable findings.
- eg4battery README/NOTES: 3 -> 6 packs (pack 6 oddball 0x01/115200); SoC drift
  + calibration section; closed-loop comms evaluated and rejected (loses per-pack
  telemetry, no native protocol, doesn't fix drift); how to force a grid charge
  via output-priority SUB.
- LVX6048 README: closed-loop pending item -> resolved decision; new "SoC
  calibration & known firmware quirks" section (POP single-digit/POP01, MCHGC
  charge-lock, re_discharge=re-discharge can't exceed float, PIRI lag, powermon
  adhoc wedge); skills pointer.
- lvx-control README: POP encoding fix, POP crc-but-applies quirk, verify-by-
  behavior, grid-charge-via-SUB usage.
- troubleshoot-inverter skill: corrected the stale "dead string per inverter"
  claim — both strings healthy; low PV is tilt/heat/shade/curtailment.

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

README.md

@@ -0,0 +1,51 @@
+# solar — home power monitoring & control
+
+Monitoring, control, and calibration tooling for an off-grid-leaning solar + storage
+install, all published to one Home Assistant MQTT broker (`10.0.0.41`).
+
+## The system
+
+```
+6× EG4 LifePower4 v2 packs ──RS485 (1 FTDI each)──┐
+2× MPP Solar LVX6048 inverters ──USB-HID/PI18──────┤  monitoring Pi  ──MQTT──► Home Assistant
+1× OpenEVSE charger (10.0.0.249) ───────────────────┘  (daemons)            10.0.0.41:1883
+```
+
+- **14.4 kW PV** (36×400 W, 4×9s strings, 9s2p per inverter, 45° south) → 2 paralleled
+  LVX6048 inverters → **~30 kWh** EG4 LifePower4 bank (6× 100 Ah, 16S).
+
+## Subsystems
+
+| Dir | What | Entities |
+|-----|------|----------|
+| [`LVX6048/`](./LVX6048/) | 2 inverters via powermon (PI18/USB) + `lvx-flash` settings tool + `lvx-control` HA→PI18 bridge | `lvx6048_{1,2}_*` |
+| [`eg4battery/`](./eg4battery/) | 6 battery packs via RS485/Modbus daemon | `lifepower4_{1..6}_*` |
+| [`openevse/`](./openevse/) | EV charger HA-discovery publisher | `openevse_*` |
+| [`battery/`](./battery/) | legacy V1 protocol decoder (historical) | — |
+
+Each subsystem has its own `README.md` / `Install.md` / `NOTES.md`.
+
+## Agent skills
+
+Agent-runnable skills for monitoring, troubleshooting, and calibration live in
+[`.claude/skills/`](./.claude/skills/) — start with
+[`.claude/skills/REFERENCE.md`](./.claude/skills/REFERENCE.md) (system map, real HA
+entity ids, known firmware quirks, action policy):
+
+- `solar-health-check` — whole-system sweep + cross-checks + R/Y/G verdict
+- `troubleshoot-inverter` / `troubleshoot-battery` — subsystem deep-dives
+- `power-usage` — load vs PV vs grid vs battery balance
+- `calibration-charge` — re-anchor drifted EG4 SoC via a full charge
+- helpers: `lib/solar-snapshot` (live MQTT), `lib/ha-history` (HA recorder lookback),
+  `lib/grid-cal-monitor` (supervised grid calibration with auto-revert)
+
+## Notable findings (see per-subsystem docs + the skills' REFERENCE)
+
+- **EG4 SoC drifts** (counters never re-anchor without a full charge) → fixed by the
+  `calibration-charge` skill.
+- **"Low" PV is mostly geometry + curtailment, not a fault** — both strings are healthy
+  (~16 A @ 300 V at clear-noon peak); the shortfall is 45° tilt, heat, trees, and the
+  battery charge cap throttling midday harvest.
+- **LVX6048 firmware quirks**: PI18 `POP` is single-digit (`POP1`, not `POP01`);
+  MCHGC locked while charging; force a full grid charge via output-priority **SUB**, not
+  the voltage thresholds; PIRI readback lags ~5 min (verify by behavior).