Add configuration controls, robust energy sensors, and migration support

.gitignore

@@ -101,6 +101,7 @@ venv.bak/
 *.swp
 *.swo
 *~
+.devcontainer/
 
 # OS
 .DS_Store
@@ -109,3 +110,4 @@ Thumbs.db
 # Home Assistant specific
 *.log
 solark_debug.log
+solark_secrets.json

AGENTS.md

@@ -0,0 +1,31 @@
+# Instructions for Coding Agents
+
+This repo includes a Home Assistant integration and a CLI tool. If you are an
+automated coding agent, follow these rules when making changes.
+
+## Must Follow
+
+- Always update documentation when code changes alter behavior, outputs, or
+  configuration. At minimum, review and update:
+  - `README.md`
+  - `QUICKSTART.md`
+  - `CLI.md`
+  - `ENERGY_DASHBOARD_SETUP.md` (if energy/sensor behavior changes)
+- Keep secrets out of commits. Use `solark_secrets.template.json` for examples
+  and never commit `solark_secrets.json`.
+- Prefer small, focused edits; avoid unrelated formatting changes.
+- If you change CLI flags or output structure, update `CLI.md` in the same PR.
+- If you change sensor names/units/behavior, update README tables and quick
+  start instructions.
+
+## Helpful Context
+
+- CLI entry point: `python -m solark_cli`
+- Integration code: `custom_components/solark/`
+- Template secrets file: `solark_secrets.template.json`
+
+## Quality Checks (Optional but Recommended)
+
+- Run the CLI against a test secrets file when changing CLI behavior.
+- Validate Home Assistant config flow and sensor parsing when touching those
+  modules.

CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## [5.2.0] - 2026-01-30
+
+### ✨ Improvements
+
+- Added System Work Mode configuration entities (numbers, switches, time).
+- Added write-access toggle in the config flow (disabled by default).
+- Settings are fetched/written only against the master inverter.
+- Master inverter SN is cached in memory to reduce repeated lookups.
+- Options updates now reload the integration so write access toggles take effect.
+- Settings entities now optimistically show new values briefly and retry refresh
+  to handle API propagation delays.
+- Work Mode and Energy Pattern are now select entities with labeled options.
+- Added Time Of Use day-of-week switches.
+- Added Home Consumption Energy sensor (integrated from load power).
+- Added config entry migration to seed new options (allow write access).
+
+### 📚 Documentation
+
+- Added configuration write-access guidance.
+
+## [5.1.1] - 2026-01-30
+
+### ✨ Improvements
+
+- Added native battery charge/discharge power sensors:
+  - `sensor.solark_battery_charge_power`
+  - `sensor.solark_battery_discharge_power`
+- Added native battery charge/discharge energy sensors using the integration
+  method (trapezoidal):
+  - `sensor.solark_battery_charge_energy`
+  - `sensor.solark_battery_discharge_energy`
+
+### 📚 Documentation
+
+- Updated Energy dashboard setup to use built-in battery energy sensors.
+- Updated sensor lists and counts in README and Quick Start.
+- Fixed options flow initialization for older Home Assistant versions.
+
+## [5.1.0] - 2026-01-29
+
+### ✨ Improvements
+
+- Added native energy sensors for grid import/export:
+  - `sensor.solark_grid_import_energy`
+  - `sensor.solark_grid_export_energy`
+- Added status sensors:
+  - `sensor.solark_grid_status`
+  - `sensor.solark_generator_status`
+- Grid import/export now derives from `gridOrMeterPower` + direction flags when
+  no CT meter is present.
+- Battery power sign is inferred from flow direction flags (`toBat`/`batTo`).
+- Logging now respects Home Assistant's logging configuration (no forced file
+  logging).
+
+### 📚 Documentation
+
+- Updated Energy dashboard setup to use built-in energy sensors.
+- Updated sensor lists and troubleshooting guidance.
+
 ## [5.0.0] - 2024-11-21
 
 ### 🎉 Major Features

CLI.md

@@ -0,0 +1,141 @@
+# SolArk Cloud CLI
+
+This document describes the command-line interface located in `solark_cli/`.
+
+## Overview
+
+The CLI is a lightweight wrapper around the SolArk Cloud API client. It is
+intended for quick diagnostics, testing credentials, and inspecting live and
+flow data without Home Assistant.
+
+Entry point:
+
+```bash
+python -m solark_cli
+```
+
+## Requirements
+
+- Python 3.10+ (same baseline as the integration)
+- `aiohttp` installed (the CLI will exit with an error if missing)
+
+## Secrets File
+
+The CLI can read credentials from a JSON file. A template exists in the repo:
+
+- `solark_secrets.template.json` (safe to commit)
+
+Copy it to `solark_secrets.json` and fill in your values:
+
+```json
+{
+  "username": "your-email@example.com",
+  "password": "your-password",
+  "plant_id": "YOUR_PLANT_ID",
+  "base_url": "https://www.mysolark.com",
+  "api_url": "https://ecsprod-api-new.solarkcloud.com"
+}
+```
+
+Default lookup path for secrets is `solark_secrets.json` in the repo root.
+
+## Usage
+
+```bash
+python -m solark_cli [options]
+```
+
+If no action flags are provided, the CLI fetches everything it can:
+plants, inverters, live data, flow data, combined data, parsed sensors,
+gateways, and common settings (where possible).
+
+## Options
+
+Authentication and URLs:
+
+- `--secrets PATH` - Path to secrets JSON file
+- `--username USERNAME` - SolArk account username
+- `--password PASSWORD` - SolArk account password
+- `--plant-id PLANT_ID` - SolArk plant ID
+- `--base-url BASE_URL` - Base URL for the SolArk web app
+- `--api-url API_URL` - Base URL for the SolArk API
+
+Data fetch actions:
+
+- `--plants` - Fetch plant list
+- `--inverters` - Fetch inverter list
+- `--live` - Fetch inverter live data
+- `--flow` - Fetch plant flow data
+- `--combined` - Fetch combined plant data (live + flow)
+- `--parsed` - Parse combined plant data into sensor values
+- `--gateways` - Fetch gateways list
+- `--settings` - Fetch common settings for an inverter
+
+Settings updates:
+
+- `--set-slot` - Update a system work mode slot for an inverter
+- `--inverter-sn SN` - Inverter serial number for settings changes
+- `--slot N` - Slot number (1-6)
+- `--slot-time HH:MM` - Sell time for the slot
+- `--slot-pac VALUE` - Sell power (PAC) for the slot
+- `--slot-volt VALUE` - Sell voltage for the slot
+- `--slot-cap VALUE` - Battery cap for the slot
+- `--slot-mode sell|charge` - Slot mode
+- `--sys-work-mode VALUE` - System work mode value (e.g., 1 for sell)
+- `--allow-non-master` - Allow setting changes on non-master inverters
+
+## Behavior Notes
+
+- `--live` without `--inverter-sn` fetches the plant inverter list and uses
+  the first inverter found.
+- `--flow`, `--combined`, and `--parsed` require a valid `plant_id`.
+- `--settings` and `--set-slot` require `--inverter-sn`.
+- `--set-slot` requires `--inverter-sn` and `--slot`.
+- Output is printed as JSON with sorted keys inside section headers.
+
+## Examples
+
+Fetch combined live + flow data and parsed sensors:
+
+```bash
+python -m solark_cli --secrets solark_secrets.json --combined --parsed
+```
+
+Fetch live data for a specific inverter:
+
+```bash
+python -m solark_cli --secrets solark_secrets.json --live --inverter-sn 2201064650
+```
+
+Fetch plant flow data only:
+
+```bash
+python -m solark_cli --secrets solark_secrets.json --flow
+```
+
+Update slot 2 to sell at 18:00 with 3000W:
+
+```bash
+python -m solark_cli \
+  --secrets solark_secrets.json \
+  --set-slot \
+  --inverter-sn 2201064650 \
+  --slot 2 \
+  --slot-time 18:00 \
+  --slot-pac 3000 \
+  --slot-mode sell
+```
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Login/API error or missing dependency (`aiohttp`)
+- `2` - Missing required arguments (e.g., credentials or slot info)
+
+## Troubleshooting
+
+- **Missing dependency**: Install `aiohttp` in your environment.
+- **Missing required values**: Provide required flags or a secrets file.
+- **API error**: Verify credentials at mysolark.com and confirm your Plant ID.
+- **No inverters found**: Ensure the Plant ID is correct and the account has
+  access to at least one inverter.