Bump version to 0.7.4

.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/Projects.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/changes.md

@@ -0,0 +1,47 @@
+# Changes Log
+
+## 2026-03-23
+
+### Added
+- Created `.idea/start prompt.md` as a persistent project working prompt for future sessions.
+- Added `.idea/changes.md` as the preferred in-project location for the detailed session change log.
+- Added release notes support in the active Bahmcloud Store runtime path: backend provider fetching, a dedicated API endpoint, and panel display for the currently selected version when provider release notes are available.
+- Bumped the Home Assistant panel asset cache-buster from `v=109` to `v=110` so the updated frontend loads reliably after deployment.
+- Bumped the integration version from `0.7.2` to `0.7.3`.
+- Added the `0.7.3` release entry to `CHANGELOG.md` with the new release-notes and project-workflow changes.
+- Added a persistent rule that commit messages, pushes, release notes, and changelog entries must never mention prompts, AI/KI tools, or `.idea` folder files.
+- Added a persistent release rule that future git tags and release names must use plain version numbers without a leading `v`.
+- Added a broader persistent rule that internal workflow or prompt/process decisions must never appear in any public-facing project communication.
+- Added a persistent language rule that all project-facing repository content must stay in English regardless of the chat language.
+- Added persistent pinned repositories support: favorites are stored in settings, exposed by the backend, filterable and sortable in the store view, and toggleable from the detail view without forcing a full repository refresh.
+- Bumped the integration version from `0.7.3` to `0.7.4` and added the `0.7.4` release entry to `CHANGELOG.md` for the pinned-repositories feature.
+
+### Documented
+- Captured the verified project identity from the repository and README files: Bahmcloud Store is a Home Assistant custom integration intended to behave like a provider-neutral store for custom integrations, similar to HACS but broader than GitHub-only workflows.
+- Recorded the actual active architecture from source analysis, including the config-entry-only setup, the fixed Bahmcloud store index, delayed startup refresh, periodic refresh, repo merge flow, cache usage, install/update/uninstall pipeline, backup/restore pipeline, update entities, and Repairs-based restart handling.
+- Recorded the current provider reality from code: GitHub, GitLab, and Gitea-compatible repositories are the concrete supported paths today, while truly generic "all git providers" support is still an intention and must be validated case by case.
+- Recorded the public API endpoints exposed by `views.py` so future work preserves the current backend contract unless a deliberate breaking change is approved.
+- Recorded storage facts from `storage.py`, including the `bcs_store` Home Assistant storage key and the persisted sections for custom repositories, installed repositories, settings, HACS cache, and repo enrichment cache.
+- Recorded frontend facts from the active panel registration in `__init__.py` and the active frontend implementation in `panel/panel.js`, including the cache-busting panel asset version query.
+- Updated the persistent start prompt to point future work to `.idea/changes.md` as the canonical detailed work log.
+- Release notes are intentionally tied to provider release objects, so tags or branches without release bodies now return a clear "not available" state instead of misleading fallback text.
+
+### Important findings from code analysis
+- Identified `custom_components/bahmcloud_store/panel/panel.js` as the active Home Assistant panel script currently loaded by the integration.
+- Identified `custom_components/bahmcloud_store/panel/app.js`, `custom_components/bahmcloud_store/panel/index.html`, and `custom_components/bahmcloud_store/panel/styles.css` as likely legacy or secondary assets that should not be treated as authoritative without verification.
+- Identified `custom_components/bahmcloud_store/store.py` as an older implementation with a different data model and API shape than the active `BCSCore` runtime.
+- Identified `custom_components/bahmcloud_store/custom_repo_view.py` as duplicate or legacy API code because the active custom-repo handling already exists in `views.py`.
+- Noted that the README set is directionally useful but not fully authoritative where it conflicts with current code behavior.
+- Noted that some repository files contain encoding or mojibake artifacts, so future edits should preserve valid UTF-8 and avoid spreading broken text.
+
+### Project rules written into the start prompt
+- Never push, commit, tag, or create a release without explicit user approval.
+- Always append a dated and detailed entry to `.idea/changes.md` for every change made.
+- When a release is created, collect all relevant changes since the last release into `CHANGELOG.md`.
+
+### Verification
+- Reviewed repository structure and current git status.
+- Read `README.md`, `README_DEVELOPER.md`, `README_FULL.md`, `bcs.yaml`, and the current `CHANGELOG.md`.
+- Analyzed the active backend files: `__init__.py`, `const.py`, `core.py`, `providers.py`, `metadata.py`, `storage.py`, `views.py`, `config_flow.py`, `update.py`, and `repairs.py`.
+- Checked panel and legacy-related files to distinguish the currently active UI path from older or duplicated files.
+- Verified that the active panel (`panel/panel.js`) now requests release notes from the new backend route and reloads them when the selected install version changes.

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/Projects.iml" filepath="$PROJECT_DIR$/.idea/Projects.iml" />
+    </modules>
+  </component>
+</project>

.idea/start prompt.md

@@ -0,0 +1,123 @@
+## 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:
+- All project-facing work must be done in English only, regardless of the language the user speaks in chat. This applies to code comments, documentation, changelog entries, release notes, commit messages, PR text, UI text, issue text, and any other project artifacts unless the user explicitly requests a specific exception for repository content.
+- 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.
+- Never mention prompts, AI tools, KI tools, or files inside the `.idea` folder in commit messages, push descriptions, release notes, or changelog entries.
+- Use plain version numbers for future git tags and release names, without a leading `v` prefix. Example: `0.7.4`, not `v0.7.4`.
+- Never mention internal workflow rules or repository-internal prompt/process decisions in any public-facing project communication. This includes commit messages, push descriptions, git tags, release names, release notes, changelog entries, and similar outward-facing texts.
+- 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.4`
+- Latest documented release in `CHANGELOG.md` is `0.7.4` dated `2026-03-23`

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

CHANGELOG.md

@@ -11,6 +11,149 @@ Sections:
 
 ---
 
+## 0.7.4 - 2026-03-23
+
+### Added
+- Pinned repositories support to let admins keep important integrations easy to find.
+- Pin and unpin actions in the repository detail view.
+- Store filtering and sorting options for pinned repositories.
+
+### Changed
+- Repository favorites are now persisted in settings and restored across reloads.
+- Pinned repositories are highlighted in the store overview with a dedicated badge.
+- Frontend asset version updated so the latest panel changes load immediately after deployment.
+
+## 0.7.3 - 2026-03-23
+
+### Added
+- Release notes support in the repository detail view for provider releases.
+- New backend endpoint to fetch release notes for the selected repository version.
+
+
+### Changed
+- Home Assistant panel asset cache-buster bumped to ensure updated frontend assets load after deployment.
+- Release-note lookups now clearly report when a selected version has no provider release body instead of implying notes exist for plain tags or branches.
+
+## 0.7.2 – 2026-01-20
+
+### Fixed
+- When Bahmcloud Store is installed via an external installer (files copied into /config/custom_components), it now reconciles itself as "installed" in BCS storage so update checks work immediately.
+
+## 0.7.1 – 2026-01-20
+
+### Fixed
+- GitHub version provider now reliably fetches the latest 20 releases/tags using authenticated API requests.
+- Repositories that were previously fetched in a degraded state (only `latest` and `branch`) are now automatically refreshed on repository view.
+- Cached version lists with incomplete data are no longer reused and are re-fetched from the provider.
+
+## [0.7.0] - 2026-01-20
+
+### Added
+- Options dialog (gear icon) for the Bahmcloud Store integration.
+- Optional GitHub token can now be set, changed or removed via the Home Assistant UI.
+
+### Fixed
+- Fixed missing options flow when clicking the integration settings button.
+
+## [0.6.9] – 2026-01-19
+### Added
+- New Home Assistant **GUI setup** (Config Flow) – no YAML configuration required.
+- Optional **GitHub Token** support to increase API limits (up to 5000 req/h).  
+  Configurable via *Integration → Options*.
+- Clear setup guidance and warning about GitHub rate limits.
+- Automatic detection and warning if YAML setup is still present (ignored safely).
+
+### Changed
+- **store.yaml** URL is now fixed to the official Bahmcloud Store index:
+  https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml
+- Installation workflow fully aligned with standard HA integrations.
+- Update platform migrated to `async_setup_entry`.
+
+### Fixed
+- Minor stability and persistence improvements in startup sequence.
+- Prevented duplicate background initialization when HA reloads the integration.
+
+### Notes
+- To enable extended GitHub access, create a fine-grained personal access token
+  (read-only) at https://github.com/settings/tokens and add it via the integration options.
+
+## 0.6.8 – Performance & Cache Stabilization (2026-01-19)
+
+### Fixed
+- Fixed excessive GitHub API requests causing rate limiting
+- Fixed missing persistence of repository versions and metadata
+- Fixed background enrichment re-running after Home Assistant restart
+
+### Changed
+- Repository metadata (versions, README, descriptions) is now fetched once in the background
+- Cached data is reused and only refreshed on explicit user interaction
+- Improved separation between startup refresh and on-demand updates
+
+### Improved
+- Significantly reduced Home Assistant startup time
+- Greatly reduced GitHub API usage
+- More reliable version selection for GitHub and HACS repositories
+
+### Notes
+- Background tasks may still appear in DEBUG logs (expected behavior)
+- No functional UI changes in this release
+
+## [0.6.7] - 2026-01-19
+
+### Fixed
+- Repository metadata loaded on demand is now persisted and restored after Home Assistant restart.
+- Background enrichment reliably updates latest versions and descriptions for HACS repositories.
+- Cached repository data is correctly restored on startup for non-installed repositories.
+
+### Changed
+- Repository details are only considered fully enriched once latest version information is available.
+- Improved reliability of background cache synchronization without impacting startup performance.
+
+## [0.6.6] - 2026-01-18
+
+### Added
+- Source filter to limit repositories by origin: BCS Official, HACS, or Custom.
+- Visual source badges for repositories (BCS Official, HACS, Custom).
+- Restored HACS enable/disable toggle in the Store UI.
+
+### Changed
+- HACS repositories now display human-readable names and descriptions based on official HACS metadata.
+- Improved Store usability on mobile devices by fixing back navigation from repository detail view.
+
+### Fixed
+- Fixed missing HACS toggle after UI updates.
+- Fixed mobile browser back button exiting the Store instead of returning to the repository list.
+
+## [0.6.5] - 2026-01-18
+
+### Added
+- Separate handling of HACS official repositories with an enable/disable toggle in the Store UI.
+- HACS repositories are now loaded independently from the main store index.
+
+### Changed
+- Store index can remain minimal and curated; HACS repositories are no longer required in store.yaml.
+- Improved Store performance and clarity by clearly separating repository sources.
+
+### Fixed
+- Browser cache issues resolved by proper panel cache-busting for UI updates.
+
+### Internal
+- No changes to install, update, backup, or restore logic.
+- Fully backward compatible with existing installations and configurations.
+
+## [0.6.4] - 2026-01-18
+
+### Fixed
+- Fixed long Home Assistant startup times caused by background repository enrichment running too early.
+
+### Changed
+- Background repository enrichment is now started only after Home Assistant has fully started.
+- Repository cache updates now run fully asynchronous without blocking Home Assistant startup.
+
+### Internal
+- Improved alignment with Home Assistant startup lifecycle.
+- No functional changes to store behavior or UI.
+
 ## [0.6.3] - 2026-01-18
 
 ### Changed

README.md

@@ -1,3 +1,50 @@
-# bahmcloud_store
+# Bahmcloud Store (BCS) for Home Assistant
 
-Bahmcloud Store for installing costum_components to Homeassistant
+Bahmcloud Store (BCS) is a provider-neutral store for Home Assistant custom integrations.
+It allows you to browse, install, update, downgrade, uninstall and restore integrations
+directly from the Home Assistant UI.
+
+This README is intended for **end users**.
+
+---
+
+## Installation
+
+### Option A: Home Assistant OS / Supervised (Add-on – recommended)
+
+1. Open **Settings → Add-ons → Add-on Store**
+2. Add the Bahmcloud Add-on repository
+   `https://git.bahmcloud.de/bahmcloud/addons`
+3. Install **Bahmcloud Store Installer**
+4. Start the add-on
+5. Restart Home Assistant
+
+Installed to:
+/config/custom_components/bahmcloud_store
+
+---
+
+### Option B: Manual Installation (Container / Core)
+
+1. Download the latest release
+2. Copy `custom_components/bahmcloud_store` to:
+   /config/custom_components/bahmcloud_store
+3. Restart Home Assistant
+
+---
+
+## Repository Sources
+
+- **BCS Official**
+- **HACS**
+- **Custom**
+
+---
+
+## Documentation
+
+Developer documentation:
+https://git.bahmcloud.de/bahmcloud/bahmcloud_store/src/branch/main/README_DEVELOPER.md
+
+Full technical documentation:
+https://git.bahmcloud.de/bahmcloud/bahmcloud_store/src/branch/main/README_FULL.md

README_DEVELOPER.md

@@ -0,0 +1,115 @@
+# Bahmcloud Store – Developer Documentation
+
+For contributors and maintainers.
+
+## Architecture
+
+Repositories:
+1) Installer Add-on (HAOS/Supervised) ```https://git.bahmcloud.de/bahmcloud/addons```
+2) Core Integration ```https://git.bahmcloud.de/bahmcloud/bahmcloud_store```
+3) Store Index (`store.yaml`) ```https://git.bahmcloud.de/bahmcloud/ha_store```
+
+### Integration Layout
+
+custom_components/bahmcloud_store/
+- __init__.py: setup, panel registration, schedule background after HA started
+- core.py: index merge, enrichment, install/update/uninstall, backups, restore, caching
+- providers.py: GitHub/GitLab/Gitea repo info + latest version helpers
+- metadata.py: read bcs.yaml / hacs.json / hacs.yaml
+- storage.py: persistent storage (installed, custom, repo cache, hacs cache)
+- views.py: HTTP API endpoints
+- update.py: UpdateEntity implementation
+- repairs.py: (optional) Repairs flow for restart
+- panel/: UI (panel.js, styles.css, etc.)
+- manifest.json
+
+## Runtime Model
+
+- RepoItem (merged)
+- Installed repos (storage)
+- Repo cache (persisted enrichment)
+- HACS meta cache (mapping owner/repo → name/description)
+
+## Background
+
+- Heavy work only after `homeassistant_started`
+- Refresh: if index unchanged → installed-only refresh + schedule enrichment
+- Opening a repo triggers `ensure_repo_details()` and persists to cache
+
+## Providers
+
+- GitHub: API/releases/tags/atom + raw readme
+- GitLab: API releases/tags + raw readme
+- Gitea: API releases/tags + raw readme
+- Custom: API or HTTPS Request to your Git Provider
+
+## Metadata
+
+- Prefer `bcs.yaml`, fallback `hacs.json` / `hacs.yaml`
+- Populate name/description/category/author/maintainer
+
+## HTTP API (excerpt)
+
+Base: /api/bcs
+
+- GET  /api/bcs
+- POST /api/bcs?action=refresh
+- GET  /api/bcs/readme?repo_id=...
+- GET  /api/bcs/versions?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=...
+- (optional) POST/DELETE custom_repo
+
+## Update Entities
+
+- Unique id bcs:<repo_id>
+- Compare installed ref vs latest ref
+- Dispatcher signal on refresh/install/update
+
+## Storage
+
+- JSON in HA `.storage`
+- async read/write helpers
+- repo cache applied on startup
+
+## Contributing to **BCS Official**
+
+1) Add pull request to `https://git.bahmcloud.de/bahmcloud/ha_store` (with your integration added to) `store.yaml`)  
+2) Add entry:
+```yaml
+- name: Your Integration Name
+  url: https://your-git-hoster.com/your-org/your-repo
+  category: Category (actually only "Integrations" are supported)
+```
+3) (Recommended) Add `bcs.yaml` to your repo:
+```yaml
+name: Your Integration Name
+description: One-liner for the store (optional, store information are also catched from git repository)
+category: Integrations (actually only supported)
+author: Your Name
+maintainer: Your Handle
+```
+4) Open PR; validation checks: reachable, has `custom_components/<domain>/manifest.json`, sensible metadata
+5) Merge → appears in **BCS Official** after refresh
+
+## Coding Guidelines
+
+- Async I/O, no blocking event loop
+- Respect provider rate limits
+- Clean logging around refresh/install/update/restore
+- Keep UI responsive; throttle updates
+
+---
+
+## Planed Features
+
+- Add Downloads and install for category "Dashboard"
+- Add Downloads and install for category "Template"
+- Add Downloads and install for category "Theme"
+- Add Downloads and install for category "Blueprint"
+- 
+
+

README_FULL.md

@@ -0,0 +1,217 @@
+# Bahmcloud Store – Full User Guide
+
+This guide explains **all features** of Bahmcloud Store (BCS) for Home Assistant.
+It is written for users and admins who want a complete, practical reference.
+
+> BCS lets you install & manage custom integrations from **GitHub/GitLab/Gitea** and your own sources, with backups, restore, and version pinning.
+
+---
+
+## Contents
+- Concepts
+- Sources (BCS / HACS / Custom)
+- UI Overview
+- Finding Integrations
+- Installing
+- Selecting Versions / Downgrading
+- Updating
+- Uninstalling
+- Backups & Restore
+- Custom Repositories
+- HACS Repositories
+- Update Entities in Home Assistant
+- Background Caching & Performance
+- Restart Required
+- Troubleshooting
+- FAQ
+
+---
+
+## Concepts
+
+- **Sources**:
+  - **BCS Official** → entries from index (`store.yaml`) made and added from Bahmcloud
+  - **HACS** → official HACS integrations list (toggleable)
+  - **Custom** → manual entries you add locally
+- **Install location**: `/config/custom_components/<domain>`
+- **Backup**: BCS keeps pre‑update copies in `/config/.bcs_backups/<domain>/<timestamp>/`
+
+---
+
+## Sources (BCS / HACS / Custom)
+
+Each repository card shows a **source badge**:
+- **BCS Official** – from Bahmcloud index
+- **HACS** – from HACS official list (enable with the toggle)
+- **Custom** – added by you
+
+You can **filter by source** with the **Source** dropdown (All / BCS Official / HACS / Custom).
+
+---
+
+## UI Overview
+
+Top bar:
+- **Search** (name/description)
+- **Source** filter (All/BCS Official/HACS/Custom)
+- **Category** filter (actually only Integrations are supported)
+- **State-Filter** filter (All/Installed/Not installed/Update available/Custom repos)
+- **Sort** (name (A-Z)/Updates first/Installed first)
+- **HACS official** toggle (on/off)
+
+Repository card:
+- Name, description, badges (source, installed/update), category
+- Buttons: **Install / Update / Uninstall**
+- **Readme** expandable
+- **Open** to see details (available versions, metadata)
+
+---
+
+## Finding Integrations
+
+1. Use **Search** to filter by keywords.
+2. Combine with **Category** and **Source**.
+3. Sort to surface desired results.
+
+Descriptions and latest versions are filled progressively by a background process; opening a repo loads details on demand.
+
+---
+
+## Installing
+
+1. Open a repository.
+2. Optionally select **Install version** (default: **Latest**).
+3. Click **Install** and wait for confirmation.
+4. Follow the **Restart required** prompt. (or use restart toggle in HomeAssistant Settings)
+
+**What happens internally**
+- BCS downloads the repository ZIP for the selected version (release/tag/branch).
+- It extracts all integrations found under `custom_components/<domain>` and deploys them.
+- It saves the **installed version (ref)** to track updates reliably, even if the repo’s own `manifest.json` is wrong/outdated.
+
+---
+
+## Selecting Versions / Downgrading
+
+- Use the **Install version** dropdown in the detail view.
+- Choose **Latest** or a previous **release/tag**.
+- Installing a chosen ref **pins** the integration to that ref (no surprise updates).
+- You can upgrade again later by selecting **Latest** and clicking **Update**.
+
+---
+
+## Updating
+
+- The **Update** button appears when `latest_version` differs from your **installed version (ref)**.
+- Updates are also available via **Home Assistant → Settings → Updates** (native Update entity).
+- Clicking **Update** runs the same safe pipeline as **Install** (with backup).
+
+**Tip:** Opening a repository detail view forces an immediate check for the latest version for that repo.
+
+---
+
+## Uninstalling
+
+- Click **Uninstall** on the repository.
+- BCS removes the integration folders under `custom_components/<domain>`.
+- The installed state is cleared in the Store.
+- Restart Home Assistant if prompted.
+
+---
+
+## Backups & Restore
+
+Before an update/install over existing files, BCS creates a backup:
+
+```
+/config/.bcs_backups/<domain>/<timestamp>/
+```
+
+**Restore**:
+1. Open the repository in store.
+2. Select **Restore…**.
+3. Pick one of the **last backups** (up to retention limit). (Version details are showed in ())
+4. Confirm – BCS restores files and reconciles installed version to the restored ref.
+5. Restart Home Assistant if prompted.
+
+If the old backup lacks metadata, BCS best‑effort derives the installed version from the backup’s `manifest.json`, or marks the ref as `restored:<timestamp>` so updates remain possible.
+
+---
+
+## Custom Repositories
+
+You can add any public repository (GitHub/GitLab/Gitea/Any other Git Hoster). BCS will attempt to detect:
+- provider & default branch
+- latest version (release/tag/atom)
+- repo metadata (prefer `bcs.yaml`, fallback `hacs.json/hacs.yaml`)
+- readme (common filenames)
+
+**Add an custom repository**(typical flows):
+- From the Store UI
+  1. If you start up Bahmcloud Store, you are on tab "Store"
+  2. Go to tab "Manage" 
+  3. Add Repository URL (Example: ``https://git.bahmcloud.de/bahmcloud/bahmcloud_store``) and (optional) Name you want to show up (will be grabbed from GIT Repository)
+  4. Repository show up in Custom Repositories-list and in "Store" Tab, if available
+
+**Remove an custom repository**(typical flows):
+- From the Store UI
+  1. If you start up Bahmcloud Store, you are on tab "Store"
+  2. Go to tab "Manage" 
+  3. Your repository you want to remove (if its custom) show up in the list
+  4. Press "Remove" Button to delete from Store (Attention: If you Remove installed Repository, you won´t be able to Uninstall from Store, you have to remove by your own (Delete Folder from ```config/custom_components/*```))
+
+Custom repos get the **Custom** badge and can be filtered via **Source**.
+
+---
+
+## HACS Repositories
+
+Enable the **HACS official** toggle to include official HACS integrations.
+
+- BCS downloads the HACS integration list and maps **human‑readable names/descriptions** from HACS metadata.
+- HACS entries are **not** part of your BCS-Official Repositories (avoid duplicate entries).
+
+With many HACS repos, metadata loads in the background; names/descriptions appear progressively and are cached.
+
+---
+
+## Update Entities in Home Assistant
+
+BCS exposes update entities for installed repos:
+- Found under **Settings → Updates**
+- Clicking **Install** triggers BCS update pipeline
+- Shows **installed** and **latest** versions (BCS ref logic)
+
+---
+
+## Background Caching & Performance
+
+- **Fast initial list**: index + local cache only
+- **Background enrichment**: provider info, latest version, metadata, description, readme (best effort)
+- **On‑demand**: opening a repo triggers immediate enrichment; data is **persisted** to cache
+- **Persistent cache**: survives HA restarts; speeds up subsequent runs
+- **Refresh**: immediately rechecks installed repos and key metadata
+
+---
+
+## Restart Required
+
+After install, update, or restore, BCS raises a **Restart required** item in Home Assistant (Repairs). You can restart directly from there.
+
+---
+
+## Troubleshooting
+
+- **New release but no update**: Open the repo detail once; ensure it’s a **release/tag** (commits alone don’t change the ref).
+- **Descriptions/Latest missing**: Wait for background enrichment or open the repo detail (forces enrichment). Cached afterwards.
+(You also can Install new version by selecting in Version tab)
+- **Slow startup**: BCS schedules heavy work after HA started. Keep indexes reasonable.
+
+---
+
+## FAQ
+
+- **Backups path?** `/config/.bcs_backups/<domain>/<timestamp>/`
+- **Install path?** `/config/custom_components/<domain>`
+- **Downgrade?** Yes, pick an older version and install.
+- **Restart needed?** Yes, after install/update/restore.

bcs.yaml

@@ -4,7 +4,7 @@ description: >
   Supports GitHub, GitLab, Gitea and Bahmcloud repositories with
   a central index, UI panel and API, similar to HACS but independent.
 
-category: integration
+category: Integrations
 
 author: Bahmcloud
 maintainer: Bahmcloud

custom_components/bahmcloud_store/__init__.py

@@ -3,39 +3,63 @@ from __future__ import annotations
 import logging
 from datetime import timedelta
 
+from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.components.panel_custom import async_register_panel
-from homeassistant.helpers.event import async_track_time_interval
-from homeassistant.helpers.discovery import async_load_platform
+from homeassistant.const import EVENT_HOMEASSISTANT_STARTED
+from homeassistant.helpers.event import async_call_later, async_track_time_interval
 
-from .core import BCSCore, BCSConfig, BCSError
+from .const import CONF_GITHUB_TOKEN, DEFAULT_STORE_URL, DOMAIN
+from .core import BCSError, BCSConfig, BCSCore
 
 _LOGGER = logging.getLogger(__name__)
 
-DOMAIN = "bahmcloud_store"
-
-DEFAULT_STORE_URL = "https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml"
-CONF_STORE_URL = "store_url"
+PLATFORMS: list[str] = ["update"]
 
 
 async def async_setup(hass: HomeAssistant, config: dict) -> bool:
-    cfg = config.get(DOMAIN, {}) or {}
-    store_url = cfg.get(CONF_STORE_URL, DEFAULT_STORE_URL)
+    """Set up Bahmcloud Store.
 
-    core = BCSCore(hass, BCSConfig(store_url=store_url))
-    hass.data[DOMAIN] = core
+    We intentionally do NOT support YAML configuration.
+    This method is kept so we can log a helpful message if someone tries.
+    """
+    if DOMAIN in (config or {}):
+        _LOGGER.warning(
+            "BCS YAML configuration is no longer supported. "
+            "Please remove 'bahmcloud_store:' from configuration.yaml and set up the integration via the UI."
+        )
+    return True
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Set up Bahmcloud Store from a config entry (UI setup)."""
+    # Only one instance.
+    hass.data.setdefault(DOMAIN, {})
+
+    github_token = (entry.options.get(CONF_GITHUB_TOKEN) or "").strip() or None
+
+    core = BCSCore(
+        hass,
+        BCSConfig(
+            store_url=DEFAULT_STORE_URL,
+            github_token=github_token,
+        ),
+    )
+
+    hass.data[DOMAIN][entry.entry_id] = core
+    # Keep a convenient shortcut for platforms that previously used hass.data[DOMAIN] directly.
+    hass.data[DOMAIN]["_core"] = core
 
     await core.async_initialize()
 
-    # Provide native Update entities in Settings -> System -> Updates.
-    # This integration is YAML-based (async_setup), therefore we load the platform manually.
-    await async_load_platform(hass, "update", DOMAIN, {}, config)
-
+    # HTTP views + panel (registered once per entry; we only allow one entry).
     from .views import (
         StaticAssetsView,
         BCSApiView,
+        BCSSettingsView,
         BCSReadmeView,
         BCSVersionsView,
+        BCSReleaseNotesView,
         BCSRepoDetailView,
         BCSCustomRepoView,
         BCSInstallView,
@@ -48,8 +72,10 @@ async def async_setup(hass: HomeAssistant, config: dict) -> bool:
 
     hass.http.register_view(StaticAssetsView())
     hass.http.register_view(BCSApiView(core))
+    hass.http.register_view(BCSSettingsView(core))
     hass.http.register_view(BCSReadmeView(core))
     hass.http.register_view(BCSVersionsView(core))
+    hass.http.register_view(BCSReleaseNotesView(core))
     hass.http.register_view(BCSRepoDetailView(core))
     hass.http.register_view(BCSCustomRepoView(core))
     hass.http.register_view(BCSInstallView(core))
@@ -64,18 +90,25 @@ async def async_setup(hass: HomeAssistant, config: dict) -> bool:
         frontend_url_path="bahmcloud-store",
         webcomponent_name="bahmcloud-store-panel",
         # IMPORTANT: bump v to avoid caching old JS
-        module_url="/api/bahmcloud_store_static/panel.js?v=106",
+        module_url="/api/bahmcloud_store_static/panel.js?v=111",
         sidebar_title="Bahmcloud Store",
         sidebar_icon="mdi:store",
         require_admin=True,
         config={},
     )
 
+    async def _do_startup_refresh(_now=None) -> None:
         try:
             await core.full_refresh(source="startup")
         except BCSError as e:
             _LOGGER.error("Initial refresh failed: %s", e)
 
+    # Do not block startup; refresh after HA is up.
+    def _on_ha_started(_event) -> None:
+        async_call_later(hass, 30, _do_startup_refresh)
+
+    hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STARTED, _on_ha_started)
+
     async def periodic(_now) -> None:
         try:
             await core.full_refresh(source="timer")
@@ -87,4 +120,16 @@ async def async_setup(hass: HomeAssistant, config: dict) -> bool:
     interval_seconds = int(getattr(core, "refresh_seconds", 300) or 300)
     async_track_time_interval(hass, periodic, timedelta(seconds=interval_seconds))
 
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Unload a config entry."""
+    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
+        try:
+            hass.data.get(DOMAIN, {}).pop(entry.entry_id, None)
+        except Exception:
+            pass
+    return unload_ok

custom_components/bahmcloud_store/config_flow.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import logging
+
+import voluptuous as vol
+
+from homeassistant import config_entries
+from homeassistant.core import callback
+
+from .const import CONF_GITHUB_TOKEN, DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _schema(default_token: str | None = None) -> vol.Schema:
+    default_token = (default_token or "").strip()
+    return vol.Schema({vol.Optional(CONF_GITHUB_TOKEN, default=default_token): str})
+
+
+class BahmcloudStoreConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
+    """Config flow for Bahmcloud Store.
+
+    The store index URL is fixed and not user-configurable.
+    The only optional setting is a GitHub token to increase API rate limits.
+    """
+
+    VERSION = 1
+
+    async def async_step_user(self, user_input: dict | None = None):
+        # Allow only one instance.
+        await self.async_set_unique_id(DOMAIN)
+        self._abort_if_unique_id_configured()
+
+        if user_input is None:
+            return self.async_show_form(step_id="user", data_schema=_schema(None))
+
+        token = str(user_input.get(CONF_GITHUB_TOKEN, "")).strip() or None
+
+        return self.async_create_entry(
+            title="Bahmcloud Store",
+            data={},
+            options={CONF_GITHUB_TOKEN: token} if token else {},
+        )
+
+    @staticmethod
+    @callback
+    def async_get_options_flow(config_entry: config_entries.ConfigEntry):
+        return BahmcloudStoreOptionsFlowHandler(config_entry)
+
+
+class BahmcloudStoreOptionsFlowHandler(config_entries.OptionsFlow):
+    """Options flow to manage optional GitHub token."""
+
+    def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
+        self._config_entry = config_entry
+
+    async def async_step_init(self, user_input: dict | None = None):
+        if user_input is None:
+            current = self._config_entry.options.get(CONF_GITHUB_TOKEN) or ""
+            return self.async_show_form(step_id="init", data_schema=_schema(str(current)))
+
+        token = str(user_input.get(CONF_GITHUB_TOKEN, "")).strip() or None
+        options = dict(self._config_entry.options)
+
+        # Allow clearing the token.
+        if token:
+            options[CONF_GITHUB_TOKEN] = token
+        else:
+            options.pop(CONF_GITHUB_TOKEN, None)
+
+        return self.async_create_entry(title="", data=options)

custom_components/bahmcloud_store/const.py

@@ -0,0 +1,11 @@
+"""Constants for Bahmcloud Store."""
+
+from __future__ import annotations
+
+DOMAIN = "bahmcloud_store"
+
+# Fixed store index URL (not user-configurable).
+DEFAULT_STORE_URL = "https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml"
+
+# Config entry option keys
+CONF_GITHUB_TOKEN = "github_token"

custom_components/bahmcloud_store/core.py

@@ -20,7 +20,14 @@ from homeassistant.helpers import issue_registry as ir
 from homeassistant.util import yaml as ha_yaml
 
 from .storage import BCSStorage, CustomRepo
-from .providers import fetch_repo_info, detect_provider, RepoInfo, fetch_readme_markdown, fetch_repo_versions
+from .providers import (
+    fetch_repo_info,
+    detect_provider,
+    RepoInfo,
+    fetch_readme_markdown,
+    fetch_repo_versions,
+    fetch_release_notes_markdown,
+)
 from .metadata import fetch_repo_metadata, RepoMetadata
 
 _LOGGER = logging.getLogger(__name__)
@@ -32,6 +39,20 @@ RESTART_REQUIRED_ISSUE_ID = "restart_required"
 
 BACKUP_META_FILENAME = ".bcs_backup_meta.json"
 
+# Optional HACS integrations index (GitHub repositories only).
+HACS_INTEGRATIONS_URL = "https://data-v2.hacs.xyz/integration/repositories.json"
+HACS_INTEGRATIONS_DATA_URL = "https://data-v2.hacs.xyz/integration/data.json"
+HACS_DEFAULT_CATEGORY = "Integrations"
+HACS_CACHE_TTL_SECONDS = 60 * 60 * 24  # 24h
+
+# Repo enrichment cache:
+# - persists across restarts
+# - keeps UI populated (name/description/latest) without blocking startup
+REPO_CACHE_TTL_SECONDS = 6 * 60 * 60  # 6h
+# Release/tag lists change rarely and can be expensive for some providers (e.g. GitHub rate limits).
+# Cache them longer and refresh only on-demand (when the user opens the version selector).
+VERSIONS_CACHE_TTL_SECONDS = 7 * 24 * 60 * 60  # 7d
+
 
 class BCSError(Exception):
     """BCS core error."""
@@ -44,6 +65,7 @@ class BCSInstallError(BCSError):
 @dataclass
 class BCSConfig:
     store_url: str
+    github_token: str | None = None
 
 
 @dataclass
@@ -95,6 +117,20 @@ class BCSCore:
         self._install_lock = asyncio.Lock()
         self._installed_cache: dict[str, Any] = {}
 
+        # Persistent settings (UI toggles etc.)
+        self.settings: dict[str, Any] = {"hacs_enabled": False, "favorite_repo_ids": []}
+
+        # Cached HACS metadata (display names/descriptions). Loaded from storage.
+        self._hacs_meta_fetched_at: int = 0
+        self._hacs_meta: dict[str, dict[str, Any]] = {}
+        self._hacs_meta_lock = asyncio.Lock()
+
+        # Persistent per-repo enrichment cache (name/description/latest). Loaded from storage.
+        self._repo_cache_fetched_at: int = 0
+        self._repo_cache: dict[str, dict[str, Any]] = {}
+        self._repo_cache_lock = asyncio.Lock()
+        self._repo_enrich_task: asyncio.Task | None = None
+
         # Phase F2: backups before install/update
         self._backup_root = Path(self.hass.config.path(".bcs_backups"))
         self._backup_keep_per_domain: int = 5
@@ -104,9 +140,42 @@ class BCSCore:
         self.version = await self._read_manifest_version_async()
         await self._refresh_installed_cache()
 
+        # Load persistent settings (do not fail startup)
+        try:
+            s = await self.storage.get_settings()
+            if isinstance(s, dict):
+                self.settings.update(s)
+        except Exception:
+            pass
+
         # After a successful HA restart, restart-required is no longer relevant.
         self._clear_restart_required_issue()
 
+        # Load cached HACS metadata (optional; improves UX when HACS toggle is enabled).
+        try:
+            hc = await self.storage.get_hacs_cache()
+            if isinstance(hc, dict):
+                self._hacs_meta_fetched_at = int(hc.get("fetched_at") or 0)
+                repos = hc.get("repos")
+                if isinstance(repos, dict):
+                    # Normalize to string keys
+                    self._hacs_meta = {str(k): (v if isinstance(v, dict) else {}) for k, v in repos.items()}
+        except Exception:
+            self._hacs_meta_fetched_at = 0
+            self._hacs_meta = {}
+
+        # Load persisted per-repo enrichment cache (keeps UI populated after restart).
+        try:
+            rc = await self.storage.get_repo_cache()
+            if isinstance(rc, dict):
+                self._repo_cache_fetched_at = int(rc.get("fetched_at") or 0)
+                repos = rc.get("repos")
+                if isinstance(repos, dict):
+                    self._repo_cache = {str(k): (v if isinstance(v, dict) else {}) for k, v in repos.items()}
+        except Exception:
+            self._repo_cache_fetched_at = 0
+            self._repo_cache = {}
+
     async def _read_manifest_version_async(self) -> str:
         def _read() -> str:
             try:
@@ -119,6 +188,108 @@ class BCSCore:
 
         return await self.hass.async_add_executor_job(_read)
 
+    async def _read_manifest_info_async(self) -> dict[str, str]:
+        """Read manifest.json fields that help identify this integration."""
+
+        def _read() -> dict[str, str]:
+            try:
+                manifest_path = Path(__file__).resolve().parent / "manifest.json"
+                data = json.loads(manifest_path.read_text(encoding="utf-8"))
+                out: dict[str, str] = {}
+                for k in ("version", "documentation", "name", "domain"):
+                    v = data.get(k)
+                    if v:
+                        out[str(k)] = str(v)
+                return out
+            except Exception:
+                return {}
+
+        return await self.hass.async_add_executor_job(_read)
+
+    def _normalize_repo_base(self, url: str) -> str:
+        """Normalize repository URLs to a stable base for matching.
+
+        Example:
+          https://git.example.tld/org/repo/raw/branch/main/store.yaml
+        becomes:
+          https://git.example.tld/org/repo
+        """
+        try:
+            p = urlsplit(str(url or "").strip())
+            parts = [x for x in (p.path or "").split("/") if x]
+            base_path = "/" + "/".join(parts[:2]) if len(parts) >= 2 else (p.path or "")
+            return urlunsplit((p.scheme, p.netloc, base_path.rstrip("/"), "", "")).lower()
+        except Exception:
+            return str(url or "").strip().lower()
+
+    async def _ensure_self_marked_installed(self, repos: dict[str, RepoItem]) -> None:
+        """Ensure BCS is treated as installed when deployed via external installer.
+
+        When users install BCS via an installer that places files into
+        /config/custom_components, our internal storage has no installed entry.
+        This breaks update detection for the BCS repo entry in the Store.
+        """
+        try:
+            # Already tracked as installed?
+            items = await self.storage.list_installed_repos()
+            for it in items:
+                if DOMAIN in [str(d) for d in (it.domains or [])]:
+                    return
+
+            # Files must exist on disk.
+            cc_root = Path(self.hass.config.path("custom_components"))
+            manifest_path = cc_root / DOMAIN / "manifest.json"
+            if not manifest_path.exists():
+                return
+
+            info = await self._read_manifest_info_async()
+            doc = (info.get("documentation") or "").strip()
+            name = (info.get("name") or "").strip()
+            ver = (info.get("version") or self.version or "unknown").strip()
+
+            doc_base = self._normalize_repo_base(doc) if doc else ""
+
+            # Identify the matching repo entry in our current repo list.
+            chosen: RepoItem | None = None
+            if doc_base:
+                for r in repos.values():
+                    if self._normalize_repo_base(r.url) == doc_base:
+                        chosen = r
+                        break
+
+            if not chosen and name:
+                for r in repos.values():
+                    if (r.name or "").strip().lower() == name.lower():
+                        chosen = r
+                        break
+
+            if not chosen:
+                for r in repos.values():
+                    if "bahmcloud_store" in (r.url or "").lower():
+                        chosen = r
+                        break
+
+            if not chosen:
+                _LOGGER.debug("BCS self-install reconcile: could not match repo entry")
+                return
+
+            await self.storage.set_installed_repo(
+                repo_id=chosen.id,
+                url=chosen.url,
+                domains=[DOMAIN],
+                installed_version=ver if ver != "unknown" else None,
+                installed_manifest_version=ver if ver != "unknown" else None,
+                ref=ver if ver != "unknown" else None,
+            )
+
+            _LOGGER.info(
+                "BCS self-install reconcile: marked as installed (repo_id=%s version=%s)",
+                chosen.id,
+                ver,
+            )
+        except Exception:
+            _LOGGER.debug("BCS self-install reconcile failed", exc_info=True)
+
     def add_listener(self, cb) -> None:
         self._listeners.append(cb)
 
@@ -175,22 +346,88 @@ class BCSCore:
         data = (self._installed_cache or {}).get(repo_id)
         return data if isinstance(data, dict) else None
 
+    def get_settings_public(self) -> dict[str, Any]:
+        """Return UI-relevant settings (no I/O)."""
+        favorite_repo_ids = self.settings.get("favorite_repo_ids") or []
+        if not isinstance(favorite_repo_ids, list):
+            favorite_repo_ids = []
+        return {
+            "hacs_enabled": bool(self.settings.get("hacs_enabled", False)),
+            "favorite_repo_ids": [str(x) for x in favorite_repo_ids if str(x).strip()],
+        }
+
+    async def set_settings(self, updates: dict[str, Any]) -> dict[str, Any]:
+        """Persist settings and apply them."""
+        safe_updates: dict[str, Any] = {}
+        reload_required = False
+        if "hacs_enabled" in (updates or {}):
+            safe_updates["hacs_enabled"] = bool(updates.get("hacs_enabled"))
+            reload_required = True
+        if "favorite_repo_ids" in (updates or {}):
+            raw = updates.get("favorite_repo_ids") or []
+            if not isinstance(raw, list):
+                raw = []
+            favorite_ids: list[str] = []
+            seen: set[str] = set()
+            for item in raw:
+                rid = str(item or "").strip()
+                if not rid or rid in seen:
+                    continue
+                seen.add(rid)
+                favorite_ids.append(rid)
+            safe_updates["favorite_repo_ids"] = favorite_ids
+
+        merged = await self.storage.set_settings(safe_updates)
+        if isinstance(merged, dict):
+            self.settings.update(merged)
+
+        if reload_required:
+            await self.full_refresh(source="settings")
+        else:
+            self.signal_updated()
+        return self.get_settings_public()
+
+    def is_favorite_repo(self, repo_id: str) -> bool:
+        favorite_repo_ids = self.settings.get("favorite_repo_ids") or []
+        if not isinstance(favorite_repo_ids, list):
+            return False
+        target = str(repo_id or "").strip()
+        return bool(target) and target in [str(x).strip() for x in favorite_repo_ids]
+
     async def refresh(self) -> None:
         index_repos, refresh_seconds = await self._load_index_repos()
         self.refresh_seconds = refresh_seconds
 
+        hacs_enabled = bool(self.settings.get("hacs_enabled", False))
+        hacs_repos: list[RepoItem] = []
+        if hacs_enabled:
+            try:
+                hacs_repos = await self._load_hacs_repos()
+            except Exception as e:
+                _LOGGER.warning("BCS HACS index load failed: %s", e)
+
         custom_repos = await self.storage.list_custom_repos()
 
         # Fast path: if index + custom repos did not change, skip expensive work.
         try:
             custom_sig = [(c.id, (c.url or '').strip(), (c.name or '').strip()) for c in (custom_repos or [])]
             custom_sig.sort()
-            refresh_signature = json.dumps({"index_hash": self.last_index_hash, "custom": custom_sig}, sort_keys=True)
+            hacs_sig = len(hacs_repos) if hacs_enabled else 0
+            refresh_signature = json.dumps({"index_hash": self.last_index_hash, "custom": custom_sig, "hacs": hacs_sig, "hacs_enabled": hacs_enabled}, sort_keys=True)
         except Exception:
-            refresh_signature = f"{self.last_index_hash}:{len(custom_repos or [])}"
+            refresh_signature = f"{self.last_index_hash}:{len(custom_repos or [])}:{'h' if hacs_enabled else 'n'}:{len(hacs_repos)}"
 
         if self._last_refresh_signature and refresh_signature == self._last_refresh_signature and self.repos:
-            _LOGGER.debug("BCS refresh skipped (no changes detected)")
+            _LOGGER.debug("BCS refresh fast-path (no repo list changes)")
+
+            # Even if the repo list is unchanged, we still want fresh versions/descriptions
+            # for installed repos and we still want background enrichment to keep the
+            # overview populated.
+            if hacs_enabled and self._hacs_meta_needs_refresh():
+                self.hass.async_create_task(self._refresh_hacs_meta_background())
+
+            await self._enrich_installed_only(self.repos)
+            self._schedule_repo_enrich_background()
             return
 
 
@@ -199,6 +436,9 @@ class BCSCore:
         for item in index_repos:
             merged[item.id] = item
 
+        for item in hacs_repos:
+            merged[item.id] = item
+
         for c in custom_repos:
             merged[c.id] = RepoItem(
                 id=c.id,
@@ -210,24 +450,397 @@ class BCSCore:
         for r in merged.values():
             r.provider = detect_provider(r.url)
 
+        # Apply cached HACS display metadata immediately (fast UX).
+        if hacs_enabled and hacs_repos:
+            self._apply_hacs_meta(merged)
+
+            # Refresh HACS metadata in the background if cache is missing/stale.
+            if self._hacs_meta_needs_refresh():
+                self.hass.async_create_task(self._refresh_hacs_meta_background())
+
+        # Apply persisted per-repo enrichment cache (instant UI after restart).
+        self._apply_repo_cache(merged)
+
+        # If BCS itself was installed via an external installer (i.e. files exist on disk
+        # but our storage has no installed entry yet), we still want update checks to work.
+        # Reconcile this once we have the current repo list.
+        await self._ensure_self_marked_installed(merged)
+        await self._refresh_installed_cache()
+
         await self._enrich_installed_only(merged)
         self.repos = merged
 
+        # Enrich remaining repos in the background and persist results (non-blocking).
+        self._schedule_repo_enrich_background()
+
         self._last_refresh_signature = refresh_signature
 
         _LOGGER.info(
-            "BCS refresh complete: repos=%s (index=%s, custom=%s)",
+            "BCS refresh complete: repos=%s (index=%s, hacs=%s, custom=%s)",
             len(self.repos),
             len([r for r in self.repos.values() if r.source == "index"]),
+            len([r for r in self.repos.values() if r.source == "hacs"]),
             len([r for r in self.repos.values() if r.source == "custom"]),
         )
 
+    async def _load_hacs_repos(self) -> list[RepoItem]:
+        """Load the official HACS integrations repository list.
+
+        This is used as an optional additional source to keep the local store index small.
+        We only parse owner/repo strings and map them to GitHub URLs.
+        """
+        session = async_get_clientsession(self.hass)
+        headers = {
+            "User-Agent": "BahmcloudStore (Home Assistant)",
+            "Cache-Control": "no-cache, no-store, max-age=0",
+            "Pragma": "no-cache",
+        }
+        async with session.get(HACS_INTEGRATIONS_URL, timeout=60, headers=headers) as resp:
+            if resp.status != 200:
+                raise BCSError(f"HACS index returned {resp.status}")
+            data = await resp.json()
+
+        if not isinstance(data, list):
+            raise BCSError("HACS repositories.json must be a list")
+
+        items: list[RepoItem] = []
+        for entry in data:
+            if not isinstance(entry, str):
+                continue
+            full_name = entry.strip().strip("/")
+            if not full_name or "/" not in full_name:
+                continue
+            repo_id = f"hacs:{full_name.lower()}"
+            owner = full_name.split("/", 1)[0].strip()
+            items.append(
+                RepoItem(
+                    id=repo_id,
+                    # Name is improved later via cached HACS meta (manifest.name).
+                    name=full_name,
+                    url=f"https://github.com/{full_name}",
+                    source="hacs",
+                    owner=owner,
+                    provider_repo_name=full_name,  # keep stable owner/repo reference
+                    meta_category=HACS_DEFAULT_CATEGORY,
+                )
+            )
+        return items
+
+    def _hacs_meta_needs_refresh(self) -> bool:
+        if not self._hacs_meta_fetched_at or not self._hacs_meta:
+            return True
+        age = int(time.time()) - int(self._hacs_meta_fetched_at)
+        return age > HACS_CACHE_TTL_SECONDS
+
+    def _apply_hacs_meta(self, merged: dict[str, RepoItem]) -> None:
+        """Apply cached HACS metadata to matching repos (no I/O)."""
+        if not self._hacs_meta:
+            return
+
+        def _full_name_from_repo(r: RepoItem) -> str | None:
+            # Prefer the original owner/repo (stable) if we kept it.
+            if r.provider_repo_name and "/" in str(r.provider_repo_name):
+                return str(r.provider_repo_name).strip()
+            # Fall back to URL path: https://github.com/owner/repo
+            try:
+                u = urlparse((r.url or "").strip())
+                parts = [p for p in (u.path or "").strip("/").split("/") if p]
+                if len(parts) >= 2:
+                    repo = parts[1]
+                    if repo.endswith(".git"):
+                        repo = repo[:-4]
+                    return f"{parts[0]}/{repo}"
+            except Exception:
+                pass
+            return None
+
+        for r in merged.values():
+            if r.source != "hacs":
+                continue
+
+            key = _full_name_from_repo(r)
+            if not key or "/" not in key:
+                continue
+
+            meta = self._hacs_meta.get(key)
+            if not isinstance(meta, dict) or not meta:
+                continue
+
+            # Prefer HACS manifest name as display name.
+            display_name = meta.get("name")
+            if isinstance(display_name, str) and display_name.strip():
+                r.name = display_name.strip()
+                r.meta_name = display_name.strip()
+
+            desc = meta.get("description")
+            if isinstance(desc, str) and desc.strip():
+                r.meta_description = desc.strip()
+
+            domain = meta.get("domain")
+            # We don't store domain in RepoItem fields, but keep it in meta_source for debugging.
+            # (Optional: extend RepoItem later if needed.)
+            if isinstance(domain, str) and domain.strip():
+                # Keep under meta_source marker to help identify source.
+                pass
+
+            r.meta_source = r.meta_source or "hacs"
+            r.meta_category = r.meta_category or HACS_DEFAULT_CATEGORY
+
+    async def _refresh_hacs_meta_background(self) -> None:
+        """Fetch and cache HACS integration metadata in the background.
+
+        Uses the official HACS data endpoint which includes manifest data.
+        This avoids per-repo GitHub calls and improves the UX (names/descriptions).
+        """
+        async with self._hacs_meta_lock:
+            # Another task might have refreshed already.
+            if not self._hacs_meta_needs_refresh():
+                return
+
+            session = async_get_clientsession(self.hass)
+            headers = {
+                "User-Agent": "BahmcloudStore (Home Assistant)",
+                "Cache-Control": "no-cache, no-store, max-age=0",
+                "Pragma": "no-cache",
+            }
+
+            try:
+                async with session.get(HACS_INTEGRATIONS_DATA_URL, timeout=120, headers=headers) as resp:
+                    if resp.status != 200:
+                        raise BCSError(f"HACS data.json returned {resp.status}")
+                    data = await resp.json()
+            except Exception as e:
+                _LOGGER.warning("BCS HACS meta refresh failed: %s", e)
+                return
+
+            # Build mapping owner/repo -> {name, description, domain}
+            meta_map: dict[str, dict[str, Any]] = {}
+            if isinstance(data, dict):
+                for _, obj in data.items():
+                    if not isinstance(obj, dict):
+                        continue
+                    full_name = obj.get("full_name")
+                    if not isinstance(full_name, str) or "/" not in full_name:
+                        continue
+
+                    manifest = obj.get("manifest")
+                    mname = None
+                    mdesc = None
+                    mdomain = None
+                    if isinstance(manifest, dict):
+                        mname = manifest.get("name")
+                        mdesc = manifest.get("description")
+                        mdomain = manifest.get("domain")
+
+                    entry: dict[str, Any] = {}
+                    if isinstance(mname, str) and mname.strip():
+                        entry["name"] = mname.strip()
+                    if isinstance(mdesc, str) and mdesc.strip():
+                        entry["description"] = mdesc.strip()
+                    if isinstance(mdomain, str) and mdomain.strip():
+                        entry["domain"] = mdomain.strip()
+
+                    if entry:
+                        meta_map[full_name.strip()] = entry
+
+            self._hacs_meta = meta_map
+            self._hacs_meta_fetched_at = int(time.time())
+
+            try:
+                await self.storage.set_hacs_cache({
+                    "fetched_at": self._hacs_meta_fetched_at,
+                    "repos": self._hacs_meta,
+                })
+            except Exception:
+                _LOGGER.debug("Failed to persist HACS cache", exc_info=True)
+
+            # Apply meta to current repos and notify UI.
+            try:
+                self._apply_hacs_meta(self.repos)
+            except Exception:
+                pass
+
+            _LOGGER.info("BCS HACS metadata cached: repos=%s", len(self._hacs_meta))
+            self.signal_updated()
+
+    # ---------- Persistent per-repo enrichment cache ----------
+
+    def _apply_repo_cache(self, merged: dict[str, RepoItem]) -> None:
+        """Apply persisted per-repo enrichment cache to RepoItem objects.
+
+        This is a fast, no-I/O operation used to keep the UI populated immediately
+        after a Home Assistant restart.
+        """
+        if not self._repo_cache:
+            return
+
+        for repo_id, r in merged.items():
+            cached = self._repo_cache.get(str(repo_id))
+            if not isinstance(cached, dict) or not cached:
+                continue
+
+            cached_url = cached.get("url")
+            if isinstance(cached_url, str) and cached_url and r.url and cached_url != r.url:
+                # Repo id reused for different URL; ignore.
+                continue
+
+            # Fill gaps only; never override fresh values from current refresh.
+            if (not r.name or r.name == r.url) and isinstance(cached.get("name"), str) and cached.get("name"):
+                r.name = str(cached.get("name"))
+
+            for attr, key in (
+                ("owner", "owner"),
+                ("provider_repo_name", "provider_repo_name"),
+                ("provider_description", "provider_description"),
+                ("default_branch", "default_branch"),
+                ("latest_version", "latest_version"),
+                ("latest_version_source", "latest_version_source"),
+                ("meta_source", "meta_source"),
+                ("meta_name", "meta_name"),
+                ("meta_description", "meta_description"),
+                ("meta_category", "meta_category"),
+                ("meta_author", "meta_author"),
+                ("meta_maintainer", "meta_maintainer"),
+            ):
+                if getattr(r, attr, None):
+                    continue
+                v = cached.get(key)
+                if v is None:
+                    continue
+                if isinstance(v, str):
+                    vv = v.strip()
+                    if vv:
+                        setattr(r, attr, vv)
+
+    def _repo_needs_enrich(self, repo_id: str, r: RepoItem) -> bool:
+        """Return True if this repo should be enriched in background."""
+        cached = self._repo_cache.get(str(repo_id)) if isinstance(self._repo_cache, dict) else None
+        ts = 0
+        if isinstance(cached, dict):
+            ts = int(cached.get("ts") or 0)
+
+            # Background enrichment should be a one-time best-effort pass.
+            # If we already attempted it once for this repo, do not keep retrying on every refresh.
+            # On-demand (opening repo details / version selector) can still refresh and persist.
+            if bool(cached.get("bg_done")):
+                return False
+
+        # Missing key fields -> enrich.
+        if not r.latest_version:
+            return True
+        if not (r.meta_description or r.provider_description):
+            return True
+
+        # Stale cache -> enrich.
+        if ts <= 0:
+            return True
+        age = int(time.time()) - ts
+        return age > REPO_CACHE_TTL_SECONDS
+
+    def _update_repo_cache_from_repo(self, repo_id: str, r: RepoItem) -> None:
+        self._repo_cache[str(repo_id)] = {
+            "ts": int(time.time()),
+            "url": r.url,
+            "name": r.name,
+            "owner": r.owner,
+            "provider_repo_name": r.provider_repo_name,
+            "provider_description": r.provider_description,
+            "default_branch": r.default_branch,
+            "latest_version": r.latest_version,
+            "latest_version_source": r.latest_version_source,
+            "meta_source": r.meta_source,
+            "meta_name": r.meta_name,
+            "meta_description": r.meta_description,
+            "meta_category": r.meta_category,
+            "meta_author": r.meta_author,
+            "meta_maintainer": r.meta_maintainer,
+        }
+
+    def _schedule_repo_enrich_background(self) -> None:
+        """Schedule background enrichment for repo details.
+
+        This is non-blocking and safe to call repeatedly.
+        """
+        if self._repo_enrich_task and not self._repo_enrich_task.done():
+            return
+        self._repo_enrich_task = self.hass.async_create_task(self._repo_enrich_background())
+
+    async def _repo_enrich_background(self) -> None:
+        # Small delay to avoid competing with critical startup work.
+        await asyncio.sleep(2)
+
+        repo_ids = list(self.repos.keys())
+        updated = 0
+
+        # Keep it conservative to avoid rate limits.
+        sem = asyncio.Semaphore(4)
+
+        async def process_one(repo_id: str) -> None:
+            nonlocal updated
+            r = self.repos.get(repo_id)
+            if not r:
+                return
+            if not self._repo_needs_enrich(repo_id, r):
+                return
+            async with sem:
+                try:
+                    await self._enrich_one_repo(r)
+                except Exception:
+                    _LOGGER.debug("BCS background enrich failed for %s", repo_id, exc_info=True)
+                    # Mark as attempted so we don't keep hammering the provider.
+                    async with self._repo_cache_lock:
+                        cached = self._repo_cache.setdefault(str(repo_id), {})
+                        if isinstance(cached, dict):
+                            cached["bg_done"] = True
+                            cached["bg_done_ts"] = int(time.time())
+                    return
+
+            async with self._repo_cache_lock:
+                self._update_repo_cache_from_repo(repo_id, r)
+                cached = self._repo_cache.setdefault(str(repo_id), {})
+                if isinstance(cached, dict):
+                    cached["bg_done"] = True
+                    cached["bg_done_ts"] = int(time.time())
+                updated += 1
+
+        # Process sequentially but allow limited concurrency.
+        tasks: list[asyncio.Task] = []
+        for repo_id in repo_ids:
+            tasks.append(self.hass.async_create_task(process_one(repo_id)))
+
+            # Flush in batches to limit memory/connection churn.
+            if len(tasks) >= 25:
+                await asyncio.gather(*tasks, return_exceptions=True)
+                tasks = []
+                if updated:
+                    await self._persist_repo_cache()
+                    self.signal_updated()
+                await asyncio.sleep(0)
+
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        if updated:
+            await self._persist_repo_cache()
+            self.signal_updated()
+
+    async def _persist_repo_cache(self) -> None:
+        async with self._repo_cache_lock:
+            payload = {
+                "fetched_at": int(time.time()),
+                "repos": self._repo_cache,
+            }
+        try:
+            await self.storage.set_repo_cache(payload)
+        except Exception:
+            _LOGGER.debug("BCS failed to persist repo cache", exc_info=True)
+
     async def _enrich_and_resolve(self, merged: dict[str, RepoItem]) -> None:
         sem = asyncio.Semaphore(6)
 
         async def process_one(r: RepoItem) -> None:
             async with sem:
-                info: RepoInfo = await fetch_repo_info(self.hass, r.url)
+                info: RepoInfo = await fetch_repo_info(self.hass, r.url, github_token=self.config.github_token)
 
                 r.provider = info.provider or r.provider
                 r.owner = info.owner or r.owner
@@ -286,7 +899,7 @@ class BCSCore:
 
     async def _enrich_one_repo(self, r: RepoItem) -> None:
         """Fetch provider info + metadata for a single repo item."""
-        info: RepoInfo = await fetch_repo_info(self.hass, r.url)
+        info: RepoInfo = await fetch_repo_info(self.hass, r.url, github_token=self.config.github_token)
 
         r.provider = info.provider or r.provider
         r.owner = info.owner or r.owner
@@ -321,21 +934,88 @@ class BCSCore:
         if not r:
             return None
 
-        # If we already have a latest_version (or provider_description), consider it enriched.
-        if r.latest_version or r.provider_description or r.meta_source:
+        # Consider it enriched only if we already have a latest_version and at least
+        # some descriptive info (meta/provider). HACS repos often have meta_source set
+        # early, but still need provider latest_version.
+        if r.latest_version and (r.provider_description or r.meta_description or r.meta_source):
             return r
 
         try:
             await self._enrich_one_repo(r)
+
+            # Persist the newly fetched details so they survive a Home Assistant restart.
+            async with self._repo_cache_lock:
+                self._update_repo_cache_from_repo(repo_id, r)
+            await self._persist_repo_cache()
         except Exception:
             _LOGGER.debug("BCS ensure_repo_details failed for %s", repo_id, exc_info=True)
         return r
 
-    async def list_repo_versions(self, repo_id: str) -> list[dict[str, Any]]:
+    async def list_repo_versions(
+        self,
+        repo_id: str,
+        *,
+        limit: int = 20,
+        force_refresh: bool = False,
+    ) -> list[dict[str, Any]]:
         repo = self.get_repo(repo_id)
         if not repo:
             return []
-        return await fetch_repo_versions(self.hass, repo.url)
+
+        # Prefer cached version lists to avoid hammering provider APIs (notably GitHub unauthenticated
+        # rate limits). However, if the cached list is clearly a degraded fallback (e.g. only
+        # "Latest" + "Branch"), we treat it as stale and retry immediately when the user requests
+        # versions again.
+        cached = None
+        cached_ts = 0
+        async with self._repo_cache_lock:
+            cached = self._repo_cache.get(str(repo_id)) if isinstance(self._repo_cache, dict) else None
+            if isinstance(cached, dict):
+                cached_ts = int(cached.get("versions_ts", 0) or 0)
+
+        now = int(time.time())
+        cached_versions = list(cached.get("versions") or []) if isinstance(cached, dict) else []
+        cache_fresh = (now - cached_ts) < VERSIONS_CACHE_TTL_SECONDS
+
+        # Cache hit if it's fresh and not degraded, unless the caller explicitly wants a refresh.
+        if (
+            not force_refresh
+            and cached_versions
+            and cache_fresh
+            and len(cached_versions) > 2
+        ):
+            return cached_versions
+
+        try:
+            versions = await fetch_repo_versions(
+                self.hass,
+                repo.url,
+                provider=repo.provider,
+                default_branch=repo.default_branch,
+                limit=limit,
+                github_token=self.config.github_token,
+            )
+        except Exception:
+            versions = []
+
+        # If the provider fetch returned only the basic fallbacks ("Latest" + "Branch") but we have
+        # a previously cached richer list, keep using the cached list.
+        if (
+            isinstance(cached, dict)
+            and cached.get("versions")
+            and len(list(cached.get("versions") or [])) > 2
+            and len(versions) <= 2
+        ):
+            return list(cached.get("versions") or [])
+
+        # Persist whatever we got (even if small) to avoid repeated calls when rate-limited.
+        async with self._repo_cache_lock:
+            entry = self._repo_cache.setdefault(str(repo_id), {}) if isinstance(self._repo_cache, dict) else {}
+            if isinstance(entry, dict):
+                entry["versions"] = versions
+                entry["versions_ts"] = now
+        await self._persist_repo_cache()
+        return versions
 
     def _add_cache_buster(self, url: str) -> str:
         parts = urlsplit(url)
@@ -499,6 +1179,7 @@ class BCSCore:
                     "installed_version": installed_version,
                     "installed_manifest_version": installed_manifest_version,
                     "installed_domains": installed_domains,
+                    "favorite": self.is_favorite_repo(r.id),
                 }
             )
         return out
@@ -515,21 +1196,21 @@ class BCSCore:
             default_branch=repo.default_branch,
         )
 
-    async def list_repo_versions(self, repo_id: str, *, limit: int = 20) -> list[dict[str, str]]:
-        """List installable versions/refs for a repo.
-
-        This is used by the UI to allow selecting an older tag/release.
-        """
+    async def fetch_release_notes_markdown(self, repo_id: str, ref: str | None = None) -> str | None:
         repo = self.get_repo(repo_id)
         if not repo:
-            raise BCSInstallError(f"repo_id not found: {repo_id}")
+            return None
 
-        return await fetch_repo_versions(
+        target_ref = (ref or "").strip() or (repo.latest_version or "").strip()
+        if not target_ref:
+            return None
+
+        return await fetch_release_notes_markdown(
             self.hass,
             repo.url,
+            ref=target_ref,
             provider=repo.provider,
-            default_branch=repo.default_branch,
-            limit=limit,
+            github_token=self.config.github_token,
         )
 
     def _pick_ref_for_install(self, repo: RepoItem) -> str:

custom_components/bahmcloud_store/manifest.json

@@ -1,8 +1,9 @@
 {
   "domain": "bahmcloud_store",
   "name": "Bahmcloud Store",
-  "version": "0.6.3",
+  "version": "0.7.4",
   "documentation": "https://git.bahmcloud.de/bahmcloud/bahmcloud_store",
+  "config_flow": true,
   "platforms": ["update"],
   "requirements": [],
   "codeowners": ["@bahmcloud"],

custom_components/bahmcloud_store/panel/panel.js

@@ -18,6 +18,13 @@ class BahmcloudStorePanel extends HTMLElement {
     this._filter = "all"; // all|installed|not_installed|updates|custom
     this._sort = "az"; // az|updates_first|installed_first
 
+    // Source filter (all|bcs|hacs|custom)
+    this._sourceFilter = "all";
+
+    // HACS toggle (settings)
+    this._hacsEnabled = false;
+    this._favoriteRepoIds = [];
+
     this._detailRepoId = null;
     this._detailRepo = null;
     this._readmeLoading = false;
@@ -50,6 +57,14 @@ class BahmcloudStorePanel extends HTMLElement {
     this._versionsCache = {}; // repo_id -> [{ref,label,source}, ...]
     this._versionsLoadingRepoId = null;
     this._selectedVersionByRepoId = {}; // repo_id -> ref ("" means latest)
+    this._releaseNotesLoading = false;
+    this._releaseNotesText = null;
+    this._releaseNotesHtml = null;
+    this._releaseNotesError = null;
+
+    // History handling (mobile back button should go back to list, not exit panel)
+    this._historyBound = false;
+    this._handlingPopstate = false;
   }
 
   set hass(hass) {
@@ -57,10 +72,43 @@ class BahmcloudStorePanel extends HTMLElement {
     if (!this._rendered) {
       this._rendered = true;
       this._render();
+      this._ensureHistory();
       this._load();
     }
   }
 
+  _ensureHistory() {
+    if (this._historyBound) return;
+    this._historyBound = true;
+
+    try {
+      // Keep an internal history state for this panel.
+      const current = window.history.state || {};
+      if (!current || current.__bcs !== true) {
+        window.history.replaceState({ __bcs: true, view: "store" }, "");
+      }
+    } catch (e) {
+      // ignore
+    }
+
+    window.addEventListener("popstate", (ev) => {
+      const st = ev?.state;
+      if (!st || st.__bcs !== true) return;
+
+      this._handlingPopstate = true;
+      try {
+        const view = st.view || "store";
+        if (view === "detail" && st.repo_id) {
+          this._openRepoDetail(st.repo_id, false);
+        } else {
+          this._closeDetail(false);
+        }
+      } finally {
+        this._handlingPopstate = false;
+      }
+    });
+  }
+
   async _load() {
     if (!this._hass) return;
 
@@ -72,6 +120,18 @@ class BahmcloudStorePanel extends HTMLElement {
       const data = await this._hass.callApi("get", "bcs");
       this._data = data;
 
+      // Persistent settings (e.g. HACS toggle)
+      this._hacsEnabled = !!data?.settings?.hacs_enabled;
+      this._favoriteRepoIds = Array.isArray(data?.settings?.favorite_repo_ids)
+        ? data.settings.favorite_repo_ids.map((x) => String(x))
+        : [];
+
+      // Sync settings from backend (e.g. HACS toggle)
+      this._hacsEnabled = !!data?.settings?.hacs_enabled;
+      this._favoriteRepoIds = Array.isArray(data?.settings?.favorite_repo_ids)
+        ? data.settings.favorite_repo_ids.map((x) => String(x))
+        : [];
+
       if (this._view === "detail" && this._detailRepoId && Array.isArray(data?.repos)) {
         const fresh = data.repos.find((r) => this._safeId(r?.id) === this._detailRepoId);
         if (fresh) this._detailRepo = fresh;
@@ -84,6 +144,22 @@ class BahmcloudStorePanel extends HTMLElement {
     }
   }
 
+  async _setSettings(updates) {
+    if (!this._hass) return;
+    try {
+      const resp = await this._hass.callApi("post", "bcs/settings", updates || {});
+      if (resp?.ok) {
+        this._hacsEnabled = !!resp?.settings?.hacs_enabled;
+        this._favoriteRepoIds = Array.isArray(resp?.settings?.favorite_repo_ids)
+          ? resp.settings.favorite_repo_ids.map((x) => String(x))
+          : [];
+      }
+    } catch (e) {
+      // Do not fail UI for settings.
+      this._error = e?.message ? String(e.message) : String(e);
+    }
+  }
+
   async _refreshAll() {
     if (!this._hass) return;
     if (this._refreshing) return;
@@ -308,23 +384,17 @@ class BahmcloudStorePanel extends HTMLElement {
   }
 
   _goBack() {
-    if (this._view === "detail") {
-      this._view = "store";
-      this._detailRepoId = null;
-      this._detailRepo = null;
-      this._readmeText = null;
-      this._readmeHtml = null;
-      this._readmeError = null;
-      this._readmeExpanded = false;
-      this._update();
-      return;
-    }
     try {
+      // Prefer browser history so mobile back behaves as expected.
       history.back();
     } catch (_) {
+      if (this._view === "detail") {
+        this._closeDetail(true);
+      } else {
         window.location.href = "/";
       }
     }
+  }
 
   async _addCustomRepo() {
     if (!this._hass) return;
@@ -368,11 +438,15 @@ class BahmcloudStorePanel extends HTMLElement {
     }
   }
 
-  _openRepoDetail(repoId) {
+  _openRepoDetail(repoId, pushHistory = true) {
     const repos = Array.isArray(this._data?.repos) ? this._data.repos : [];
     const repo = repos.find((r) => this._safeId(r?.id) === repoId);
     if (!repo) return;
 
+    if (pushHistory) {
+      this._pushHistory({ view: "detail", repo_id: repoId });
+    }
+
     this._view = "detail";
     this._detailRepoId = repoId;
     this._detailRepo = repo;
@@ -382,6 +456,10 @@ class BahmcloudStorePanel extends HTMLElement {
     this._readmeError = null;
     this._readmeExpanded = false;
     this._readmeCanToggle = false;
+    this._releaseNotesLoading = false;
+    this._releaseNotesText = null;
+    this._releaseNotesHtml = null;
+    this._releaseNotesError = null;
 
     // Versions dropdown
     if (!(repoId in this._selectedVersionByRepoId)) {
@@ -392,6 +470,7 @@ class BahmcloudStorePanel extends HTMLElement {
     this._loadRepoDetails(repoId);
     this._loadReadme(repoId);
     this._loadVersions(repoId);
+    this._loadReleaseNotes(repoId);
   }
 
 
@@ -439,6 +518,41 @@ class BahmcloudStorePanel extends HTMLElement {
     }
   }
 
+  async _loadReleaseNotes(repoId) {
+    if (!this._hass || !repoId) return;
+
+    this._releaseNotesLoading = true;
+    this._releaseNotesText = null;
+    this._releaseNotesHtml = null;
+    this._releaseNotesError = null;
+    this._update();
+
+    try {
+      const sel = this._safeText(this._selectedVersionByRepoId?.[repoId] || "").trim();
+      const qv = sel ? `&ref=${encodeURIComponent(sel)}` : "";
+      const resp = await this._hass.callApi(
+        "get",
+        `bcs/release_notes?repo_id=${encodeURIComponent(repoId)}${qv}`,
+      );
+
+      if (resp?.ok && typeof resp.release_notes === "string" && resp.release_notes.trim()) {
+        this._releaseNotesText = resp.release_notes;
+        this._releaseNotesHtml =
+          typeof resp.html === "string" && resp.html.trim() ? resp.html : null;
+      } else {
+        this._releaseNotesError =
+          this._safeText(resp?.message) || "Release notes not available for this version.";
+      }
+    } catch (e) {
+      this._releaseNotesError = e?.message
+        ? String(e.message)
+        : "Release notes not available for this version.";
+    } finally {
+      this._releaseNotesLoading = false;
+      this._update();
+    }
+  }
+
   async _loadReadme(repoId) {
     if (!this._hass) return;
     this._readmeLoading = true;
@@ -561,6 +675,24 @@ class BahmcloudStorePanel extends HTMLElement {
           box-shadow: 0 0 0 2px rgba(30,136,229,.15);
         }
 
+        .toggle{
+          display:inline-flex;
+          align-items:center;
+          gap:8px;
+          padding:10px 12px;
+          border-radius:14px;
+          border:1px solid var(--divider-color);
+          background: var(--card-background-color);
+          color: var(--primary-text-color);
+          user-select:none;
+          cursor:pointer;
+        }
+        .toggle input{
+          margin:0;
+          width:18px;
+          height:18px;
+        }
+
         button{
           padding:10px 12px;
           border-radius:14px;
@@ -844,6 +976,37 @@ class BahmcloudStorePanel extends HTMLElement {
     return v === true;
   }
 
+  _isFavoriteRepo(repoId) {
+    const id = this._safeId(repoId);
+    return !!id && Array.isArray(this._favoriteRepoIds) && this._favoriteRepoIds.includes(id);
+  }
+
+  async _toggleFavorite(repoId) {
+    if (!this._hass || !repoId) return;
+
+    const id = this._safeId(repoId);
+    const current = Array.isArray(this._favoriteRepoIds) ? this._favoriteRepoIds.slice() : [];
+    const next = current.includes(id)
+      ? current.filter((x) => x !== id)
+      : current.concat([id]);
+
+    this._favoriteRepoIds = next;
+
+    if (Array.isArray(this._data?.repos)) {
+      this._data.repos = this._data.repos.map((r) => {
+        if (this._safeId(r?.id) !== id) return r;
+        return { ...r, favorite: next.includes(id) };
+      });
+    }
+    if (this._detailRepo && this._safeId(this._detailRepo?.id) === id) {
+      this._detailRepo = { ...this._detailRepo, favorite: next.includes(id) };
+    }
+
+    this._update();
+    await this._setSettings({ favorite_repo_ids: next });
+    await this._load();
+  }
+
   _renderStore() {
     const repos = Array.isArray(this._data.repos) ? this._data.repos : [];
 
@@ -859,15 +1022,22 @@ class BahmcloudStorePanel extends HTMLElement {
         const cat = this._safeText(r?.category) || "";
         if (this._category !== "all" && this._category !== cat) return false;
 
+        // Source filter
+        if (this._sourceFilter === "bcs" && r?.source !== "index") return false;
+        if (this._sourceFilter === "hacs" && r?.source !== "hacs") return false;
+        if (this._sourceFilter === "custom" && r?.source !== "custom") return false;
+
         const latest = this._safeText(r?.latest_version);
         const installed = this._asBoolStrict(r?.installed);
         const installedVersion = this._safeText(r?.installed_version);
         const updateAvailable = installed && !!latest && (!installedVersion || latest !== installedVersion);
+        const favorite = this._asBoolStrict(r?.favorite) || this._isFavoriteRepo(r?.id);
 
         if (this._filter === "installed" && !installed) return false;
         if (this._filter === "not_installed" && installed) return false;
         if (this._filter === "updates" && !updateAvailable) return false;
         if (this._filter === "custom" && r?.source !== "custom") return false;
+        if (this._filter === "favorites" && !favorite) return false;
 
         return true;
       })
@@ -879,16 +1049,22 @@ class BahmcloudStorePanel extends HTMLElement {
         const ainstalled = this._asBoolStrict(a?.installed);
         const ainstalledVersion = this._safeText(a?.installed_version);
         const aupdate = ainstalled && !!alatest && (!ainstalledVersion || alatest !== ainstalledVersion);
+        const afavorite = this._asBoolStrict(a?.favorite) || this._isFavoriteRepo(a?.id);
 
         const blatest = this._safeText(b?.latest_version);
         const binstalled = this._asBoolStrict(b?.installed);
         const binstalledVersion = this._safeText(b?.installed_version);
         const bupdate = binstalled && !!blatest && (!binstalledVersion || blatest !== binstalledVersion);
+        const bfavorite = this._asBoolStrict(b?.favorite) || this._isFavoriteRepo(b?.id);
 
         if (this._sort === "updates_first") {
           if (aupdate !== bupdate) return aupdate ? -1 : 1;
           return an.localeCompare(bn);
         }
+        if (this._sort === "favorites_first") {
+          if (afavorite !== bfavorite) return afavorite ? -1 : 1;
+          return an.localeCompare(bn);
+        }
         if (this._sort === "installed_first") {
           if (ainstalled !== binstalled) return ainstalled ? -1 : 1;
           return an.localeCompare(bn);
@@ -911,9 +1087,15 @@ class BahmcloudStorePanel extends HTMLElement {
         const installed = this._asBoolStrict(r?.installed);
         const installedVersion = this._safeText(r?.installed_version);
         const updateAvailable = installed && !!latest && (!installedVersion || latest !== installedVersion);
+        const favorite = this._asBoolStrict(r?.favorite) || this._isFavoriteRepo(r?.id);
 
         const badges = [];
-        if (r?.source === "custom") badges.push("Custom");
+        // Source badges
+        if (r?.source === "index") badges.push("BCS Official");
+        else if (r?.source === "hacs") badges.push("HACS");
+        else if (r?.source === "custom") badges.push("Custom");
+
+        if (favorite) badges.push("Pinned");
         if (installed) badges.push("Installed");
         if (updateAvailable) badges.push("Update");
 
@@ -939,12 +1121,25 @@ class BahmcloudStorePanel extends HTMLElement {
     return `
       <div class="filters">
         <input id="q" placeholder="Search…" value="${this._esc(this._search)}" />
+
+        <label class="toggle" title="Show official HACS repositories">
+          <input id="hacs_toggle" type="checkbox" ${this._hacsEnabled ? "checked" : ""} />
+          <span>HACS</span>
+        </label>
+
+        <select id="src">
+          <option value="all" ${this._sourceFilter === "all" ? "selected" : ""}>All sources</option>
+          <option value="bcs" ${this._sourceFilter === "bcs" ? "selected" : ""}>BCS Official</option>
+          <option value="hacs" ${this._sourceFilter === "hacs" ? "selected" : ""}>HACS</option>
+          <option value="custom" ${this._sourceFilter === "custom" ? "selected" : ""}>Custom</option>
+        </select>
         <select id="cat">
           <option value="all">All categories</option>
           ${categories.map((c) => `<option value="${this._esc(c)}" ${this._category === c ? "selected" : ""}>${this._esc(c)}</option>`).join("")}
         </select>
         <select id="filter">
           <option value="all" ${this._filter === "all" ? "selected" : ""}>All</option>
+          <option value="favorites" ${this._filter === "favorites" ? "selected" : ""}>Pinned</option>
           <option value="installed" ${this._filter === "installed" ? "selected" : ""}>Installed</option>
           <option value="not_installed" ${this._filter === "not_installed" ? "selected" : ""}>Not installed</option>
           <option value="updates" ${this._filter === "updates" ? "selected" : ""}>Updates available</option>
@@ -952,6 +1147,7 @@ class BahmcloudStorePanel extends HTMLElement {
         </select>
         <select id="sort">
           <option value="az" ${this._sort === "az" ? "selected" : ""}>A–Z</option>
+          <option value="favorites_first" ${this._sort === "favorites_first" ? "selected" : ""}>Pinned first</option>
           <option value="updates_first" ${this._sort === "updates_first" ? "selected" : ""}>Updates first</option>
           <option value="installed_first" ${this._sort === "installed_first" ? "selected" : ""}>Installed first</option>
         </select>
@@ -972,6 +1168,8 @@ class BahmcloudStorePanel extends HTMLElement {
     const cat = root.getElementById("cat");
     const filter = root.getElementById("filter");
     const sort = root.getElementById("sort");
+    const src = root.getElementById("src");
+    const hacsToggle = root.getElementById("hacs_toggle");
 
     if (q) {
       q.addEventListener("input", (e) => {
@@ -998,12 +1196,51 @@ class BahmcloudStorePanel extends HTMLElement {
       });
     }
 
+    if (src) {
+      src.addEventListener("change", (e) => {
+        this._sourceFilter = e?.target?.value || "all";
+        this._update();
+      });
+    }
+
+    if (hacsToggle) {
+      hacsToggle.addEventListener("change", async (e) => {
+        const enabled = !!e?.target?.checked;
+        this._hacsEnabled = enabled;
+        this._update();
+        await this._setSettings({ hacs_enabled: enabled });
+        await this._load();
+      });
+    }
+
     root.querySelectorAll("[data-open]").forEach((el) => {
       const id = el.getAttribute("data-open");
-      el.addEventListener("click", () => this._openRepoDetail(id));
+      el.addEventListener("click", () => this._openRepoDetail(id, true));
     });
   }
 
+  _pushHistory(state) {
+    if (this._handlingPopstate) return;
+    try {
+      window.history.pushState({ __bcs: true, ...(state || {}) }, "");
+    } catch (e) {
+      // ignore
+    }
+  }
+
+  _closeDetail(pushHistory = true) {
+    this._view = "store";
+    this._detailRepoId = null;
+    this._detailRepo = null;
+    this._readmeText = null;
+    this._readmeHtml = null;
+    this._readmeError = null;
+    this._readmeExpanded = false;
+    this._readmeCanToggle = false;
+    if (pushHistory) this._pushHistory({ view: "store" });
+    this._update();
+  }
+
   _renderAbout() {
     return `
       <div class="card">
@@ -1076,6 +1313,7 @@ class BahmcloudStorePanel extends HTMLElement {
     const installedVersion = this._safeText(r?.installed_version);
     const installedDomains = Array.isArray(r?.installed_domains) ? r.installed_domains : [];
     const latestVersion = this._safeText(r?.latest_version);
+    const favorite = this._asBoolStrict(r?.favorite) || this._isFavoriteRepo(repoId);
 
     const busyInstall = this._installingRepoId === repoId;
     const busyUpdate = this._updatingRepoId === repoId;
@@ -1110,10 +1348,36 @@ class BahmcloudStorePanel extends HTMLElement {
       </div>
     `;
 
+    const releaseNotesBlock = this._releaseNotesLoading
+      ? `<div class="card" style="margin-top:12px;">Loading release notes...</div>`
+      : this._releaseNotesText
+      ? `
+        <div class="card" style="margin-top:12px;">
+          <div class="row" style="align-items:center;">
+            <div><strong>Release Notes</strong></div>
+            <div class="muted small">${this._esc(selectedRef || latestVersion || "-")}</div>
+          </div>
+          <div id="releaseNotesPretty" class="md" style="margin-top:12px;"></div>
+          <details>
+            <summary>Show raw release notes</summary>
+            <div style="margin-top:10px;">
+              <pre class="readme">${this._esc(this._releaseNotesText)}</pre>
+            </div>
+          </details>
+        </div>
+      `
+      : `
+        <div class="card" style="margin-top:12px;">
+          <div><strong>Release Notes</strong></div>
+          <div class="muted" style="margin-top:8px;">${this._esc(this._releaseNotesError || "Release notes not available for this version.")}</div>
+        </div>
+      `;
+
     const installBtn = `<button class="primary" id="btnInstall" ${installed || busy ? "disabled" : ""}>${busyInstall ? "Installing…" : installed ? "Installed" : "Install"}</button>`;
     const updateBtn = `<button class="primary" id="btnUpdate" ${!updateAvailable || busy ? "disabled" : ""}>${busyUpdate ? "Updating…" : updateAvailable ? "Update" : "Up to date"}</button>`;
     const uninstallBtn = `<button class="primary" id="btnUninstall" ${!installed || busy ? "disabled" : ""}>${busyUninstall ? "Uninstalling…" : "Uninstall"}</button>`;
     const restoreBtn = `<button class="primary" id="btnRestore" ${!installed || busy ? "disabled" : ""}>Restore</button>`;
+    const favoriteBtn = `<button id="btnFavorite">${favorite ? "Unpin" : "Pin"}</button>`;
 
     const restartHint = this._restartRequired
       ? `
@@ -1163,8 +1427,10 @@ class BahmcloudStorePanel extends HTMLElement {
             </div>
 
             ${versionSelect}
+            ${releaseNotesBlock}
 
             <div class="row" style="margin-top:14px; gap:10px; flex-wrap:wrap;">
+              ${favoriteBtn}
               ${installBtn}
               ${updateBtn}
               ${uninstallBtn}
@@ -1189,6 +1455,13 @@ class BahmcloudStorePanel extends HTMLElement {
     const btnRestart = root.getElementById("btnRestart");
     const btnReadmeToggle = root.getElementById("btnReadmeToggle");
     const selVersion = root.getElementById("selVersion");
+    const btnFavorite = root.getElementById("btnFavorite");
+
+    if (btnFavorite) {
+      btnFavorite.addEventListener("click", () => {
+        if (this._detailRepoId) this._toggleFavorite(this._detailRepoId);
+      });
+    }
 
     if (btnInstall) {
       btnInstall.addEventListener("click", () => {
@@ -1202,6 +1475,7 @@ class BahmcloudStorePanel extends HTMLElement {
         if (!this._detailRepoId) return;
         const v = selVersion.value != null ? String(selVersion.value) : "";
         this._selectedVersionByRepoId[this._detailRepoId] = v;
+        this._loadReleaseNotes(this._detailRepoId);
       });
     }
 
@@ -1240,7 +1514,22 @@ class BahmcloudStorePanel extends HTMLElement {
     }
 
     const mount = root.getElementById("readmePretty");
-    if (!mount) return;
+    if (!mount) {
+      const releaseMount = root.getElementById("releaseNotesPretty");
+      if (releaseMount) {
+        if (this._releaseNotesText) {
+          if (this._releaseNotesHtml) {
+            releaseMount.innerHTML = this._releaseNotesHtml;
+            this._postprocessRenderedMarkdown(releaseMount);
+          } else {
+            releaseMount.innerHTML = `<div class="muted">Rendered HTML not available. Use "Show raw release notes".</div>`;
+          }
+        } else {
+          releaseMount.innerHTML = "";
+        }
+      }
+      return;
+    }
 
     if (this._readmeText) {
       if (this._readmeHtml) {
@@ -1252,6 +1541,20 @@ class BahmcloudStorePanel extends HTMLElement {
     } else {
       mount.innerHTML = "";
     }
+
+    const releaseMount = root.getElementById("releaseNotesPretty");
+    if (releaseMount) {
+      if (this._releaseNotesText) {
+        if (this._releaseNotesHtml) {
+          releaseMount.innerHTML = this._releaseNotesHtml;
+          this._postprocessRenderedMarkdown(releaseMount);
+        } else {
+          releaseMount.innerHTML = `<div class="muted">Rendered HTML not available. Use "Show raw release notes".</div>`;
+        }
+      } else {
+        releaseMount.innerHTML = "";
+      }
+    }
   }
 
   _wireRestoreModal() {

custom_components/bahmcloud_store/providers.py

@@ -189,9 +189,11 @@ async def _github_latest_version_redirect(hass: HomeAssistant, owner: str, repo:
     return None, None
 
 
-async def _github_latest_version_api(hass: HomeAssistant, owner: str, repo: str) -> tuple[str | None, str | None]:
+async def _github_latest_version_api(
+    hass: HomeAssistant, owner: str, repo: str, *, github_token: str | None = None
+) -> tuple[str | None, str | None]:
     session = async_get_clientsession(hass)
-    headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+    headers = _github_headers(github_token)
 
     data, status = await _safe_json(session, f"https://api.github.com/repos/{owner}/{repo}/releases/latest", headers=headers)
     if isinstance(data, dict) and data.get("tag_name"):
@@ -217,12 +219,14 @@ async def _github_latest_version_api(hass: HomeAssistant, owner: str, repo: str)
     return None, None
 
 
-async def _github_latest_version(hass: HomeAssistant, owner: str, repo: str) -> tuple[str | None, str | None]:
+async def _github_latest_version(
+    hass: HomeAssistant, owner: str, repo: str, *, github_token: str | None = None
+) -> tuple[str | None, str | None]:
     tag, src = await _github_latest_version_redirect(hass, owner, repo)
     if tag:
         return tag, src
 
-    tag, src = await _github_latest_version_api(hass, owner, repo)
+    tag, src = await _github_latest_version_api(hass, owner, repo, github_token=github_token)
     if tag:
         return tag, src
 
@@ -316,7 +320,16 @@ async def _gitlab_latest_version(
     return None, None
 
 
-async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
+def _github_headers(github_token: str | None = None) -> dict:
+    headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+    token = (github_token or "").strip()
+    if token:
+        # PAT or fine-grained token
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+async def fetch_repo_info(hass: HomeAssistant, repo_url: str, *, github_token: str | None = None) -> RepoInfo:
     provider = detect_provider(repo_url)
     owner, repo = _split_owner_repo(repo_url)
 
@@ -337,7 +350,7 @@ async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
 
     try:
         if provider == "github":
-            headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+            headers = _github_headers(github_token)
             data, status = await _safe_json(session, f"https://api.github.com/repos/{owner}/{repo}", headers=headers)
 
             if isinstance(data, dict):
@@ -356,7 +369,7 @@ async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
                 if desc:
                     info.description = desc
 
-            ver, src = await _github_latest_version(hass, owner, repo)
+            ver, src = await _github_latest_version(hass, owner, repo, github_token=github_token)
             info.latest_version = ver
             info.latest_version_source = src
             return info
@@ -514,6 +527,7 @@ async def fetch_repo_versions(
     provider: str | None = None,
     default_branch: str | None = None,
     limit: int = 20,
+    github_token: str | None = None,
 ) -> list[dict[str, str]]:
     """List available versions/refs for a repository.
 
@@ -523,7 +537,7 @@ async def fetch_repo_versions(
       - source: release|tag|branch
 
     Notes:
-    - Uses public endpoints (no tokens) for public repositories.
+    - Uses provider APIs; for GitHub we include the configured token (if any) to avoid unauthenticated rate limits.
     - We prefer releases first (if available), then tags.
     """
 
@@ -541,6 +555,8 @@ async def fetch_repo_versions(
 
     session = async_get_clientsession(hass)
     headers = {"User-Agent": UA}
+    if prov == "github":
+        headers = _github_headers(github_token)
 
     out: list[dict[str, str]] = []
     seen: set[str] = set()
@@ -559,11 +575,13 @@ async def fetch_repo_versions(
 
     try:
         if prov == "github":
-            # Releases
-            gh_headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+            # Releases (prefer these over tags)
+            # Use the configured GitHub token (if any) to avoid unauthenticated rate limits.
+            gh_headers = _github_headers(github_token)
+            per_page = max(1, min(int(limit), 100))
             data, _ = await _safe_json(
                 session,
-                f"https://api.github.com/repos/{owner}/{repo}/releases?per_page={int(limit)}",
+                f"https://api.github.com/repos/{owner}/{repo}/releases?per_page={per_page}",
                 headers=gh_headers,
             )
             if isinstance(data, list):
@@ -581,7 +599,7 @@ async def fetch_repo_versions(
             # Tags
             data, _ = await _safe_json(
                 session,
-                f"https://api.github.com/repos/{owner}/{repo}/tags?per_page={int(limit)}",
+                f"https://api.github.com/repos/{owner}/{repo}/tags?per_page={per_page}",
                 headers=gh_headers,
             )
             if isinstance(data, list):
@@ -661,3 +679,77 @@ async def fetch_repo_versions(
     except Exception:
         _LOGGER.debug("fetch_repo_versions failed for %s", repo_url, exc_info=True)
         return out
+
+
+async def fetch_release_notes_markdown(
+    hass: HomeAssistant,
+    repo_url: str,
+    *,
+    ref: str | None,
+    provider: str | None = None,
+    github_token: str | None = None,
+) -> str | None:
+    """Fetch release notes for a specific release tag."""
+
+    repo_url = (repo_url or "").strip()
+    target_ref = (ref or "").strip()
+    if not repo_url or not target_ref:
+        return None
+
+    prov = (provider or "").strip().lower() if provider else ""
+    if not prov:
+        prov = detect_provider(repo_url)
+
+    owner, repo = _split_owner_repo(repo_url)
+    if not owner or not repo:
+        return None
+
+    session = async_get_clientsession(hass)
+
+    try:
+        if prov == "github":
+            data, status = await _safe_json(
+                session,
+                f"https://api.github.com/repos/{owner}/{repo}/releases/tags/{quote_plus(target_ref)}",
+                headers=_github_headers(github_token),
+            )
+            if status == 200 and isinstance(data, dict):
+                body = data.get("body")
+                if isinstance(body, str) and body.strip():
+                    return body
+            return None
+
+        if prov == "gitlab":
+            u = urlparse(repo_url.rstrip("/"))
+            base = f"{u.scheme}://{u.netloc}"
+            project = quote_plus(f"{owner}/{repo}")
+            data, status = await _safe_json(
+                session,
+                f"{base}/api/v4/projects/{project}/releases/{quote_plus(target_ref)}",
+                headers={"User-Agent": UA},
+            )
+            if status == 200 and isinstance(data, dict):
+                body = data.get("description")
+                if isinstance(body, str) and body.strip():
+                    return body
+            return None
+
+        u = urlparse(repo_url.rstrip("/"))
+        base = f"{u.scheme}://{u.netloc}"
+        data, status = await _safe_json(
+            session,
+            f"{base}/api/v1/repos/{owner}/{repo}/releases/tags/{quote_plus(target_ref)}",
+            headers={"User-Agent": UA},
+        )
+        if status == 200 and isinstance(data, dict):
+            body = data.get("body")
+            if isinstance(body, str) and body.strip():
+                return body
+            note = data.get("note")
+            if isinstance(note, str) and note.strip():
+                return note
+        return None
+
+    except Exception:
+        _LOGGER.debug("fetch_release_notes_markdown failed for %s ref=%s", repo_url, target_ref, exc_info=True)
+        return None

custom_components/bahmcloud_store/storage.py

@@ -36,6 +36,9 @@ class BCSStorage:
     Keys:
     - custom_repos: list of manually added repositories
     - installed_repos: mapping repo_id -> installed metadata
+    - settings: persistent user settings (e.g. toggles in the UI)
+    - hacs_cache: cached HACS metadata to improve UX (display names/descriptions)
+    - repo_cache: cached per-repo enrichment (names/descriptions/versions) to keep the UI populated after restart
     """
 
     def __init__(self, hass: HomeAssistant) -> None:
@@ -53,8 +56,92 @@ class BCSStorage:
         if "installed_repos" not in data or not isinstance(data.get("installed_repos"), dict):
             data["installed_repos"] = {}
 
+        if "settings" not in data or not isinstance(data.get("settings"), dict):
+            data["settings"] = {}
+
+        if "hacs_cache" not in data or not isinstance(data.get("hacs_cache"), dict):
+            data["hacs_cache"] = {}
+
+        if "repo_cache" not in data or not isinstance(data.get("repo_cache"), dict):
+            data["repo_cache"] = {}
+
         return data
 
+    async def get_repo_cache(self) -> dict[str, Any]:
+        """Return cached per-repo enrichment data.
+
+        Shape:
+        {
+          "fetched_at": <unix_ts>,
+          "repos": {
+             "<repo_id>": {
+                "ts": <unix_ts>,
+                "url": "...",
+                "name": "...",
+                "provider_description": "...",
+                "meta_name": "...",
+                "meta_description": "...",
+                "meta_category": "...",
+                "meta_source": "...",
+                "latest_version": "...",
+                "latest_version_source": "...",
+                "default_branch": "...",
+                "owner": "...",
+                "provider_repo_name": "..."
+             }
+          }
+        }
+        """
+        data = await self._load()
+        cache = data.get("repo_cache", {})
+        return cache if isinstance(cache, dict) else {}
+
+    async def set_repo_cache(self, cache: dict[str, Any]) -> None:
+        """Persist cached per-repo enrichment data."""
+        data = await self._load()
+        data["repo_cache"] = cache if isinstance(cache, dict) else {}
+        await self._save(data)
+
+    async def get_hacs_cache(self) -> dict[str, Any]:
+        """Return cached HACS metadata.
+
+        Shape:
+        {
+          "fetched_at": <unix_ts>,
+          "repos": {"owner/repo": {"name": "...", "description": "...", "domain": "..."}}
+        }
+        """
+        data = await self._load()
+        cache = data.get("hacs_cache", {})
+        return cache if isinstance(cache, dict) else {}
+
+    async def set_hacs_cache(self, cache: dict[str, Any]) -> None:
+        """Persist cached HACS metadata."""
+        data = await self._load()
+        data["hacs_cache"] = cache if isinstance(cache, dict) else {}
+        await self._save(data)
+
+    async def get_settings(self) -> dict[str, Any]:
+        """Return persistent settings.
+
+        Currently used for UI/behavior toggles.
+        """
+        data = await self._load()
+        settings = data.get("settings", {})
+        return settings if isinstance(settings, dict) else {}
+
+    async def set_settings(self, updates: dict[str, Any]) -> dict[str, Any]:
+        """Update persistent settings and return the merged settings."""
+        data = await self._load()
+        settings = data.get("settings", {})
+        if not isinstance(settings, dict):
+            settings = {}
+        for k, v in (updates or {}).items():
+            settings[str(k)] = v
+        data["settings"] = settings
+        await self._save(data)
+        return settings
+
     async def _save(self, data: dict[str, Any]) -> None:
         await self._store.async_save(data)
 

custom_components/bahmcloud_store/strings.json

@@ -1,4 +1,29 @@
 {
+  "config": {
+    "abort": {
+      "single_instance_allowed": "Only one Bahmcloud Store instance can be configured."
+    },
+    "step": {
+      "user": {
+        "title": "Bahmcloud Store",
+        "description": "Bahmcloud Store uses a fixed official store index. You can optionally add a GitHub token to increase API rate limits.",
+        "data": {
+          "github_token": "GitHub token (optional)"
+        }
+      }
+    }
+  },
+  "options": {
+    "step": {
+      "init": {
+        "title": "Bahmcloud Store Options",
+        "description": "Optionally set or clear your GitHub token to reduce rate limiting.",
+        "data": {
+          "github_token": "GitHub token (optional)"
+        }
+      }
+    }
+  },
   "issues": {
     "restart_required": {
       "title": "Restart required",

custom_components/bahmcloud_store/update.py

@@ -10,11 +10,21 @@ from homeassistant.helpers.dispatcher import async_dispatcher_connect
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.entity import EntityCategory
 
-from .core import DOMAIN, SIGNAL_UPDATED, BCSCore
+from .const import DOMAIN
+from .core import SIGNAL_UPDATED, BCSCore
 
 _LOGGER = logging.getLogger(__name__)
 
 
+def _get_core(hass: HomeAssistant) -> BCSCore | None:
+    data = hass.data.get(DOMAIN)
+    if isinstance(data, dict):
+        c = data.get("_core")
+        return c if isinstance(c, BCSCore) else None
+    # Backwards compatibility (older versions used hass.data[DOMAIN] = core)
+    return data if isinstance(data, BCSCore) else None
+
+
 def _pretty_repo_name(core: BCSCore, repo_id: str) -> str:
     """Return a human-friendly name for a repo update entity."""
     try:
@@ -146,7 +156,7 @@ async def async_setup_platform(
     discovery_info=None,
 ):
     """Set up BCS update entities."""
-    core: BCSCore | None = hass.data.get(DOMAIN)
+    core: BCSCore | None = _get_core(hass)
     if not core:
         _LOGGER.debug("BCS core not available, skipping update platform setup")
         return
@@ -160,3 +170,12 @@ async def async_setup_platform(
         _sync_entities(core, entities, async_add_entities)
 
     async_dispatcher_connect(hass, SIGNAL_UPDATED, _handle_update)
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up BCS update entities from a config entry."""
+    await async_setup_platform(hass, {}, async_add_entities, None)

custom_components/bahmcloud_store/views.py

@@ -215,7 +215,12 @@ class BCSApiView(HomeAssistantView):
 
     async def get(self, request: web.Request) -> web.Response:
         return web.json_response(
-            {"ok": True, "version": self.core.version, "repos": self.core.list_repos_public()}
+            {
+                "ok": True,
+                "version": self.core.version,
+                "settings": self.core.get_settings_public(),
+                "repos": self.core.list_repos_public(),
+            }
         )
 
     async def post(self, request: web.Request) -> web.Response:
@@ -248,6 +253,40 @@ class BCSApiView(HomeAssistantView):
         return web.json_response({"ok": False, "message": "Unknown operation"}, status=400)
 
 
+class BCSSettingsView(HomeAssistantView):
+    """Persistent UI settings (e.g. toggles)."""
+
+    url = "/api/bcs/settings"
+    name = "api:bcs_settings"
+    requires_auth = True
+
+    def __init__(self, core: Any) -> None:
+        self.core: BCSCore = core
+
+    async def get(self, request: web.Request) -> web.Response:
+        return web.json_response({"ok": True, "settings": self.core.get_settings_public()})
+
+    async def post(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+        except Exception:
+            data = {}
+
+        updates: dict[str, Any] = {}
+        if "hacs_enabled" in data:
+            updates["hacs_enabled"] = bool(data.get("hacs_enabled"))
+        if "favorite_repo_ids" in data:
+            raw = data.get("favorite_repo_ids") or []
+            updates["favorite_repo_ids"] = raw if isinstance(raw, list) else []
+
+        try:
+            settings = await self.core.set_settings(updates)
+            return web.json_response({"ok": True, "settings": settings})
+        except Exception as e:
+            _LOGGER.exception("BCS set settings failed: %s", e)
+            return web.json_response({"ok": False, "message": str(e) or "Failed"}, status=500)
+
+
 class BCSCustomRepoView(HomeAssistantView):
     url = "/api/bcs/custom_repo"
     name = "api:bcs_custom_repo"
@@ -313,6 +352,41 @@ class BCSVersionsView(HomeAssistantView):
             return web.json_response({"ok": False, "message": str(e) or "List versions failed"}, status=500)
 
 
+class BCSReleaseNotesView(HomeAssistantView):
+    url = "/api/bcs/release_notes"
+    name = "api:bcs_release_notes"
+    requires_auth = True
+
+    def __init__(self, core: Any) -> None:
+        self.core: BCSCore = core
+
+    async def get(self, request: web.Request) -> web.Response:
+        repo_id = request.query.get("repo_id")
+        if not repo_id:
+            return web.json_response({"ok": False, "message": "Missing repo_id"}, status=400)
+
+        ref = request.query.get("ref")
+        ref = str(ref).strip() if ref is not None else None
+
+        try:
+            notes = await self.core.fetch_release_notes_markdown(repo_id, ref=ref)
+            if not notes or not str(notes).strip():
+                return web.json_response(
+                    {"ok": False, "message": "Release notes not found for this version."},
+                    status=404,
+                )
+
+            notes_str = str(notes)
+            html = _render_markdown_server_side(notes_str)
+            return web.json_response(
+                {"ok": True, "ref": ref, "release_notes": notes_str, "html": html},
+                status=200,
+            )
+        except Exception as e:
+            _LOGGER.exception("BCS release notes failed: %s", e)
+            return web.json_response({"ok": False, "message": str(e) or "Release notes failed"}, status=500)
+
+
 class BCSInstallView(HomeAssistantView):
     url = "/api/bcs/install"
     name = "api:bcs_install"
@@ -489,6 +563,7 @@ class BCSRepoDetailView(HomeAssistantView):
                     "installed_version": inst.get("installed_version"),
                     "installed_manifest_version": inst.get("installed_manifest_version"),
                     "installed_domains": domains,
+                    "favorite": self.core.is_favorite_repo(repo.id),
                 }
             }, status=200)
         except Exception as e: