docs: add CLAUDE.md and Claude skills (port-batcontrol-change, release-addon)

.claude/skills/port-batcontrol-change/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: port-batcontrol-change
+description: Port a change from the upstream MaStr/batcontrol repo into this Home Assistant add-on repository. Use when an upstream PR, commit, or release adds/changes/removes configuration parameters, when syncing the development add-on with upstream main, or when promoting a new upstream release into the stable add-on.
+---
+
+# Port a batcontrol change into the HA add-on
+
+Upstream repo: `MaStr/batcontrol` (Python application).
+This repo only packages it — porting a change means updating the add-on manifests and docs,
+never application code.
+
+## Step 1 — Identify what changed upstream
+
+Gather the upstream change set (PR number, commit range, or release tag). The authoritative
+source for configuration is the upstream reference config:
+
+```
+MaStr/batcontrol: config/batcontrol_config_dummy.yaml
+```
+
+Diff it against the add-on's `options:` block. If a local clone of batcontrol exists (e.g.
+`../batcontrol`), diff directly; otherwise fetch the file from GitHub (raw URL or MCP
+`get_file_contents`). Classify each difference:
+
+- **New/changed/removed config parameter** -> Steps 2-4 (config.yaml), 5 (DOCS), 6 (CHANGELOG), 7 (version)
+- **Behavior change, no config change** -> Steps 5-7 only (DOCS if user-facing, CHANGELOG, version)
+- **Build-relevant change** (entrypoint_ha.sh, pyproject, file moves in upstream `config/`) -> also check both Dockerfiles
+
+## Step 2 — Pick the target add-on
+
+- `batcontrol-development/` — **default target.** Tracks upstream `main`; every merged upstream
+  change is portable immediately.
+- `batcontrol/` (stable) — **only** when upstream has tagged a release. Its `version` must be
+  set to exactly that release tag (the Dockerfile downloads
+  `releases/download/<version>/batcontrol-<version>-py3-none-any.whl`). Never point stable at
+  an untagged state.
+
+When promoting a release to stable: replay all accumulated development changes (options,
+schema, DOCS.md) and move the "in Development" changelog content into a release section of
+the stable CHANGELOG.md.
+
+## Step 3 — Update `options:` in config.yaml
+
+- Insert the new key at the **same position and nesting** as in upstream
+  `batcontrol_config_dummy.yaml`, with a working example value and the upstream comment.
+- Parameters that most users leave at default: add as a **commented-out line** with default
+  noted (see `min_grid_charge_soc` or `market_price_refresh_time` for the pattern).
+- Do NOT expose keys the add-on manages itself: `logfile_path`, `logfile_enabled` (log path is
+  fixed to `/data/batcontrol.log` by `entrypoint_ha.sh`).
+- Removed/renamed upstream keys: remove/rename here too and record it as a breaking change in
+  the CHANGELOG.
+
+## Step 4 — Update `schema:` in config.yaml
+
+Every `options:` key needs a `schema:` entry at the same path. Mapping from upstream value
+types to HA schema syntax:
+
+| Upstream value | Schema entry |
+|---|---|
+| free string | `str` |
+| secret/token/password | `password` |
+| true/false | `bool` |
+| integer (bounded) | `int` / `int(0,23)` |
+| decimal (bounded) | `float` / `float(0,1)` |
+| fixed choice set | `list(default\|next)` |
+| optional anything | append `?`, e.g. `float(0,1)?` |
+| list of values | YAML list with one schema item, e.g. `- str` |
+
+Rules of thumb:
+- New parameters are almost always optional (`?`) so existing user configs stay valid —
+  a non-optional new key breaks every installed instance on update.
+- Carry the upstream comment onto the schema line (this repo documents both blocks).
+- SoC-style fractions -> `float(0,1)`, hours -> `int(0,23)`, watts/Wh -> `float(0,)`/`int(0,)`.
+
+## Step 5 — Update DOCS.md (if user-facing)
+
+`DOCS.md` is rendered in the HA add-on UI. Add/adjust the parameter under its section
+(`### \`battery_control:\``-style headings, backtick-quoted keys, short prose). For deep
+detail, link to https://mastr.github.io/batcontrol/ instead of duplicating it.
+
+## Step 6 — Update CHANGELOG.md
+
+Development add-on: keep/extend the top section `# Release X.Y.Z - in Development`, grouped
+by category (`### New Features`, `### Documentation`, ...), one bullet per change with the
+upstream PR number, e.g.:
+
+```markdown
+- **Dynamic Network Fees - Section 14a EnWG** (#364): short user-facing summary.
+```
+
+Stable add-on: changes only arrive with a release; add a `# Release X.Y.Z - Released on DD.MM.YYYY`
+section summarizing everything since the previous release.
+
+## Step 7 — Bump the version
+
+In the target `config.yaml`:
+- Development: increment the dev suffix (`0.8.1dev3` -> `0.8.1dev4`).
+- Stable: set to the upstream release tag (`0.8.0` -> `0.8.1`).
+
+Without a version bump HA never offers the update. Commit message convention:
+`chore(dev): bump version to X.Y.ZdevN, update changelog`.
+
+## Step 8 — Translations (rarely)
+
+`translations/en.yaml` only names/describes **top-level** option groups. Touch it only when a
+new top-level block was added in Step 3.
+
+## Step 9 — Verify
+
+1. YAML parses:
+   `python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" <addon>/config.yaml`
+2. Every `options:` key has a `schema:` counterpart at the same path (and vice versa).
+3. New keys are optional (`?`) unless a break is intended and documented.
+4. Version bumped, CHANGELOG entry present.
+5. Optional: CI (`lint.yaml`) runs `frenck/action-addon-linter` on push — it catches
+   schema/options mismatches.
+
+## Checklist
+
+```
+[ ] Upstream change identified (PR # / tag)
+[ ] Target chosen (development vs. stable)
+[ ] options: updated (position + comments match upstream dummy config)
+[ ] schema: updated (optional `?` for new keys)
+[ ] DOCS.md updated (if user-facing)
+[ ] CHANGELOG.md entry with upstream PR #
+[ ] version bumped in config.yaml
+[ ] translations/en.yaml (only for new top-level groups)
+[ ] YAML valid, options/schema consistent
+```

.claude/skills/release-addon/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: release-addon
+description: Promote a new upstream batcontrol release into the stable Home Assistant add-on and start the next development cycle. Use when upstream MaStr/batcontrol has tagged/published a release, when asked to release or update the stable add-on, or to bump the development add-on to the next dev cycle.
+---
+
+# Release the Home Assistant add-on
+
+Two-part process: (A) promote the upstream release into the **stable** add-on
+(`batcontrol/`), (B) open the next cycle in the **development** add-on
+(`batcontrol-development/`).
+
+Execution policy: perform edits and commits directly on a feature branch, but STOP and ask
+for confirmation before pushing/opening the PR, and never merge to `main` yourself.
+
+## Part A — Promote upstream release X.Y.Z into `batcontrol/`
+
+### Step 1 — Verify the upstream release is usable
+
+The stable Dockerfile downloads
+`https://github.com/MaStr/batcontrol/releases/download/X.Y.Z/batcontrol-X.Y.Z-py3-none-any.whl`.
+Confirm before touching anything:
+
+1. Tag `X.Y.Z` exists in MaStr/batcontrol.
+2. The release is **published** (not draft) and has the wheel asset with exactly that name.
+   Check via GitHub MCP release tools or
+   `curl -sI -L <wheel-url> | head -1` (must be HTTP 200).
+
+If the wheel is missing, stop and report — the add-on build would fail.
+
+### Step 2 — Sync configuration from development
+
+`batcontrol-development/` has been tracking upstream `main`, so it already contains every
+change that is now in the release. Diff and sync:
+
+```bash
+diff batcontrol/config.yaml batcontrol-development/config.yaml
+diff batcontrol/DOCS.md batcontrol-development/DOCS.md
+diff batcontrol/translations/en.yaml batcontrol-development/translations/en.yaml
+```
+
+- Copy over all `options:` and `schema:` differences that belong to the release.
+  Watch out: if development carries changes from upstream commits made AFTER the release
+  tag, exclude those (compare against upstream `config/batcontrol_config_dummy.yaml` at the
+  tag if unsure).
+- Keep the stable-only header intact: `name: "Batcontrol-next"`, `slug: "batcontrol"`,
+  stable description. Only sync options/schema/comments, not the manifest identity.
+- Sync DOCS.md and translations/en.yaml the same way.
+- Do NOT sync the Dockerfile blindly — stable builds from the release wheel, development
+  builds from `main` with uv. Only port Dockerfile changes that are explicitly
+  release-relevant (base image, runtime deps).
+
+### Step 3 — Set the stable version
+
+In `batcontrol/config.yaml`: `version: "X.Y.Z"` — must equal the upstream tag exactly
+(this value is the Dockerfile's `BUILD_VERSION`). This bump is what makes HA offer the
+update to users.
+
+### Step 4 — Stable CHANGELOG.md
+
+Prepend a new section matching the existing style (see the `0.8.0` entry — emoji headers):
+
+```markdown
+# 🚀 Release X.Y.Z - Released on DD.MM.YYYY
+
+## What's Changed
+### 🌟 Major New Features
+...
+```
+
+Source material: the `# Release X.Y.Z - in Development` section from
+`batcontrol-development/CHANGELOG.md` plus the upstream GitHub release notes. Keep upstream
+PR references (`#NNN`).
+
+### Step 5 — Validate
+
+1. `python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" batcontrol/config.yaml`
+2. Every `options:` key has a `schema:` counterpart at the same path (and vice versa).
+3. `version` matches the upstream tag character for character.
+4. CI (`lint.yaml`) will run the HA add-on linter; optionally trigger `manual-build.yaml`
+   for add-on `batcontrol` to test the image build against the real release wheel.
+
+## Part B — Open the next development cycle in `batcontrol-development/`
+
+Do this after Part A (or standalone right after upstream bumped `main` to the next dev
+version):
+
+1. `batcontrol-development/config.yaml`: set `version` to the next cycle,
+   `X.Y.(Z+1)dev1` (e.g. after releasing `0.8.1` -> `0.8.2dev1`).
+2. `batcontrol-development/CHANGELOG.md`: the released section was consumed by Part A.
+   Start a fresh top section:
+
+   ```markdown
+   # Release X.Y.(Z+1) - in Development
+
+   ## What's Changed
+   ```
+
+   Keep the released section below it for history only if that matches the existing file's
+   convention; otherwise remove the consumed content.
+
+## Finish  [CONFIRM before push]
+
+Commit both parts on a feature branch with a message like
+`chore: release add-on X.Y.Z, open X.Y.(Z+1)dev cycle`, then ask before pushing / opening
+the PR. Do not create a PR unless asked.
+
+## Checklist
+
+```
+[ ] Upstream release X.Y.Z published, wheel asset name verified
+[ ] batcontrol/config.yaml: options/schema/DOCS/translations synced from development
+[ ] batcontrol/config.yaml: version = X.Y.Z
+[ ] batcontrol/CHANGELOG.md: release section added (existing emoji style)
+[ ] YAML valid, options/schema consistent
+[ ] batcontrol-development/config.yaml: version = X.Y.(Z+1)dev1
+[ ] batcontrol-development/CHANGELOG.md: fresh "in Development" section
+[ ] Committed on feature branch; push/PR confirmed by user
+```

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md — batcontrol_ha_addon
+
+Home Assistant add-on repository packaging [MaStr/batcontrol](https://github.com/MaStr/batcontrol).
+There is **no application code here** — only HA add-on packaging, configuration manifests, and
+user documentation. The Python source lives in the upstream `batcontrol` repo.
+
+## Layout
+
+```
+repository.yaml               # HA add-on repository manifest (name, url, maintainer)
+batcontrol/                   # STABLE add-on ("Batcontrol-next")
+  config.yaml                 # Add-on manifest: name/version/slug + options: + schema:
+  Dockerfile                  # Image build; BUILD_VERSION is taken from config.yaml version
+  DOCS.md                     # User-facing parameter docs shown in the HA UI
+  CHANGELOG.md                # Shown in the HA UI on update
+  translations/en.yaml        # Names/descriptions of option groups in the HA config UI
+  build.yaml                  # Base images per architecture
+batcontrol-development/       # DEVELOPMENT add-on ("Batcontrol-development")
+.github/workflows/lint.yaml   # frenck/action-addon-linter over every add-on dir
+
+# Both add-on directories contain the same set of files:
+<addon>/config.yaml           # Add-on manifest: name/version/slug + options: + schema:
+<addon>/Dockerfile            # Image build; BUILD_VERSION is taken from config.yaml version
+<addon>/DOCS.md               # User-facing parameter docs shown in the HA UI
+<addon>/CHANGELOG.md          # Shown in the HA UI on update
+<addon>/translations/en.yaml  # Names/descriptions of option groups in the HA config UI
+<addon>/build.yaml            # Base images per architecture
+```
+
+## The two add-ons
+
+| | `batcontrol/` (stable) | `batcontrol-development/` |
+|---|---|---|
+| Builds from | Upstream **release wheel** for tag `<version>` | Upstream **`main` branch** zip, wheel built with uv |
+| `version` in config.yaml | Must equal an existing upstream release tag (e.g. `0.8.0`) | `X.Y.ZdevN` (e.g. `0.8.1dev3`) |
+| When to touch | Only when upstream publishes a release | First landing spot for every upstream change |
+
+Bumping `version` in `config.yaml` is what makes HA offer users an update — a Dockerfile or
+options change without a version bump is invisible to users.
+
+## Rules
+
+- Every key under `options:` needs a matching entry under `schema:` in the same `config.yaml`.
+  Schema syntax: `str`, `bool`, `int`, `float`, `password`, `list(a|b|c)`, ranges like
+  `int(0,23)` / `float(0,1)`, trailing `?` = optional. Reference:
+  https://developers.home-assistant.io/docs/add-ons/configuration/#options--schema
+- `options:` values mirror the upstream reference config
+  (`config/batcontrol_config_dummy.yaml` in MaStr/batcontrol): keep key names, nesting, order,
+  and comments aligned. Not every upstream key is exposed (e.g. `logfile_path`,
+  `logfile_enabled` are fixed by the add-on) — compare with the existing file before adding.
+- Changes go to `batcontrol-development/` first. `batcontrol/` is only synced when upstream
+  tags a release; then both `options:`/`schema:` and CHANGELOG are brought up to that release.
+- CHANGELOG.md (development) keeps a `# Release X.Y.Z - in Development` section on top,
+  grouped by category, referencing upstream PR numbers (`#NNN`).
+- `translations/en.yaml` only describes top-level option groups — extend it when a new
+  top-level block (like `dynamic_network_fees`) is added.
+- Validate YAML after editing: `python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" <file>`.
+  CI runs the official HA add-on linter on every add-on directory.
+
+## Skills
+
+- `port-batcontrol-change` (`.claude/skills/port-batcontrol-change/SKILL.md`): port a single
+  upstream change — diff the upstream reference config, update `options:`/`schema:`, DOCS.md,
+  CHANGELOG.md, translations, bump the dev version.
+- `release-addon` (`.claude/skills/release-addon/SKILL.md`): promote a published upstream
+  release into the stable add-on (sync from development, set `version` to the release tag,
+  write the release CHANGELOG section) and open the next `devN` cycle in
+  `batcontrol-development/`.