bahmcloud_store/.idea/start prompt.md

## Bahmcloud Store Start Prompt

You are working in the `Bahmcloud Store` repository.

Project identity:
- This is a Home Assistant custom integration named `bahmcloud_store`.
- The product goal is a provider-neutral store for Home Assistant custom integrations, similar in spirit to HACS, but not limited to GitHub.
- Current real provider implementation is strongest for GitHub, GitLab, and Gitea-compatible providers. Unknown providers currently fall through the Gitea-style code paths, so do not assume every arbitrary Git provider works without verification.

Working rules:
- Never push, commit, tag, or create a release without explicit user approval.
- Always document every change in `.idea/changes.md` with the current date and a detailed description of what changed, why it changed, and any verification done.
- If a new release is created, update `CHANGELOG.md` with all relevant changes since the last released version.
- Prefer changing the real active code paths, not legacy or duplicate files.
- When docs and code disagree, trust the current code first, then update docs to match verified behavior.
- Do not remove user changes or perform destructive git actions unless the user explicitly asks for them.

Repository facts to keep in mind:
- Main integration path: `custom_components/bahmcloud_store/`
- Entry point: `__init__.py`
- Main runtime/service layer: `core.py`
- HTTP API layer: `views.py`
- Provider detection and remote version/readme fetching: `providers.py`
- Repo metadata loading (`bcs.yaml`, `hacs.yaml`, `hacs.json`): `metadata.py`
- Persistent storage: `storage.py`
- Update entities: `update.py`
- Repairs restart flow: `repairs.py`
- Frontend panel actually loaded by Home Assistant: `panel/panel.js`
- Panel registration uses `/api/bahmcloud_store_static/panel.js?v=109`; if frontend assets change in a real release, bump the version query to break HA browser cache.

Current architecture summary:
- Setup is config-entry only. YAML configuration is intentionally unsupported and only logs a warning if present.
- Only one integration instance is allowed.
- The official store index URL is fixed in `const.py`:
  `https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml`
- The store index format currently used by the active code is a YAML mapping with:
  - `refresh_seconds`
  - `repos`
  - each repo entry contains at least `url`, optionally `name` and `category`
- Refresh flow:
  - integration initializes storage and caches
  - after `homeassistant_started`, a delayed refresh runs
  - periodic refresh also runs on an interval from the store index
  - refresh merges official index repos, optional HACS repos, and user custom repos
  - cached enrichment is applied first, installed repos are refreshed eagerly, and the rest are enriched in the background
- Optional HACS support exists behind the `hacs_enabled` setting and currently loads the official HACS integration list from `data-v2.hacs.xyz`. That path is GitHub-only metadata, not a general provider abstraction.
- Install/update flow:
  - picks a ref from selected version, latest version, or default branch
  - downloads a ZIP from the provider-specific archive endpoint
  - extracts the repository
  - finds `custom_components`
  - installs every integration folder inside `custom_components/*` that contains `manifest.json`
  - stores the installed ref and manifest version in HA storage
  - creates backups before overwriting existing domains
  - marks restart required through Repairs
- Backup/restore behavior:
  - backups live under `/config/.bcs_backups/<domain>/<timestamp>/`
  - restore updates stored installed-version info so the UI and update entities reflect the restored state
  - retention is currently 5 backups per domain
- Installed-state reconciliation exists:
  - if folders are deleted from `/config/custom_components`, stale installed entries are removed from storage
  - BCS also tries to self-reconcile as installed when it was deployed externally

Public/API contract to preserve unless intentionally changed:
- `GET /api/bcs`
- `POST /api/bcs?action=refresh`
- `GET /api/bcs/settings`
- `POST /api/bcs/settings`
- `GET /api/bcs/readme?repo_id=...`
- `GET /api/bcs/versions?repo_id=...`
- `GET /api/bcs/repo?repo_id=...`
- `POST /api/bcs/install?repo_id=...&version=...`
- `POST /api/bcs/update?repo_id=...&version=...`
- `POST /api/bcs/uninstall?repo_id=...`
- `GET /api/bcs/backups?repo_id=...`
- `POST /api/bcs/restore?repo_id=...&backup_id=...`
- `POST /api/bcs/restart`
- `DELETE /api/bcs/custom_repo?id=...`

Storage model:
- Home Assistant storage key: `bcs_store`
- Stored sections:
  - `custom_repos`
  - `installed_repos`
  - `settings`
  - `hacs_cache`
  - `repo_cache`

Frontend/UI facts:
- The active HA panel script is `custom_components/bahmcloud_store/panel/panel.js`.
- The richer UI is implemented there: source filtering, HACS toggle, repo detail loading, version selection, backups restore modal, restart action, and history handling.
- `panel/app.js`, `panel/index.html`, and `panel/styles.css` look like older standalone or legacy panel assets. Treat them as secondary unless you confirm they are still used for a real path.

Code-analysis findings that should influence future work:
- `store.py` represents an older store implementation with a different data model (`packages`, `source_path`, older API routes). It does not appear to be the active runtime path for the current integration flow.
- `custom_repo_view.py` duplicates logic that already exists in `views.py` and looks legacy/unreferenced.
- README files describe the project direction correctly at a high level, but some wording overstates provider generality. The actual code is provider-neutral in intent, but concretely implemented around GitHub, GitLab, and Gitea-style endpoints.
- The end-user and full READMEs contain some stale or inconsistent details compared with the current UI and code. Verify behavior in source before using README text as specification.
- There are visible encoding/mojibake issues in some documentation and older UI assets. Preserve valid UTF-8 when editing.

Project constraints to respect in future edits:
- Keep async I/O non-blocking in Home Assistant.
- Avoid startup-heavy network work before HA is fully started.
- Preserve repo-cache and HACS-cache behavior unless intentionally redesigning refresh logic.
- Preserve backup-before-overwrite safety for install/update/restore flows.
- Preserve update-entity behavior for installed repos.
- Keep the integration UI-admin-only and config-entry-based.

Recommended workflow for future tasks:
1. Read `README.md`, `README_DEVELOPER.md`, and relevant source files.
2. Verify whether the requested change belongs in active code or in legacy files.
3. Implement the change in the active runtime path.
4. Update documentation if behavior changed.
5. Append a detailed dated entry to `.idea/changes.md`.
6. If and only if a release is being prepared with user approval, fold release-worthy changes into `CHANGELOG.md`.

Current release baseline:
- `manifest.json` version is `0.7.3`
- Latest documented release in `CHANGELOG.md` is `0.7.3` dated `2026-03-23`