CHANGELOG.md aktualisiert

.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,41 @@
+# 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.
+
+### 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,119 @@
+## Bahmcloud Store Start Prompt
+
+You are working in the `Bahmcloud Store` repository.
+
+Project identity:
+- This is a Home Assistant custom integration named `bahmcloud_store`.
+- The product goal is a provider-neutral store for Home Assistant custom integrations, similar in spirit to HACS, but not limited to GitHub.
+- Current real provider implementation is strongest for GitHub, GitLab, and Gitea-compatible providers. Unknown providers currently fall through the Gitea-style code paths, so do not assume every arbitrary Git provider works without verification.
+
+Working rules:
+- Never push, commit, tag, or create a release without explicit user approval.
+- Always document every change in `.idea/changes.md` with the current date and a detailed description of what changed, why it changed, and any verification done.
+- If a new release is created, update `CHANGELOG.md` with all relevant changes since the last released version.
+- Prefer changing the real active code paths, not legacy or duplicate files.
+- When docs and code disagree, trust the current code first, then update docs to match verified behavior.
+- Do not remove user changes or perform destructive git actions unless the user explicitly asks for them.
+
+Repository facts to keep in mind:
+- Main integration path: `custom_components/bahmcloud_store/`
+- Entry point: `__init__.py`
+- Main runtime/service layer: `core.py`
+- HTTP API layer: `views.py`
+- Provider detection and remote version/readme fetching: `providers.py`
+- Repo metadata loading (`bcs.yaml`, `hacs.yaml`, `hacs.json`): `metadata.py`
+- Persistent storage: `storage.py`
+- Update entities: `update.py`
+- Repairs restart flow: `repairs.py`
+- Frontend panel actually loaded by Home Assistant: `panel/panel.js`
+- Panel registration uses `/api/bahmcloud_store_static/panel.js?v=109`; if frontend assets change in a real release, bump the version query to break HA browser cache.
+
+Current architecture summary:
+- Setup is config-entry only. YAML configuration is intentionally unsupported and only logs a warning if present.
+- Only one integration instance is allowed.
+- The official store index URL is fixed in `const.py`:
+  `https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml`
+- The store index format currently used by the active code is a YAML mapping with:
+  - `refresh_seconds`
+  - `repos`
+  - each repo entry contains at least `url`, optionally `name` and `category`
+- Refresh flow:
+  - integration initializes storage and caches
+  - after `homeassistant_started`, a delayed refresh runs
+  - periodic refresh also runs on an interval from the store index
+  - refresh merges official index repos, optional HACS repos, and user custom repos
+  - cached enrichment is applied first, installed repos are refreshed eagerly, and the rest are enriched in the background
+- Optional HACS support exists behind the `hacs_enabled` setting and currently loads the official HACS integration list from `data-v2.hacs.xyz`. That path is GitHub-only metadata, not a general provider abstraction.
+- Install/update flow:
+  - picks a ref from selected version, latest version, or default branch
+  - downloads a ZIP from the provider-specific archive endpoint
+  - extracts the repository
+  - finds `custom_components`
+  - installs every integration folder inside `custom_components/*` that contains `manifest.json`
+  - stores the installed ref and manifest version in HA storage
+  - creates backups before overwriting existing domains
+  - marks restart required through Repairs
+- Backup/restore behavior:
+  - backups live under `/config/.bcs_backups/<domain>/<timestamp>/`
+  - restore updates stored installed-version info so the UI and update entities reflect the restored state
+  - retention is currently 5 backups per domain
+- Installed-state reconciliation exists:
+  - if folders are deleted from `/config/custom_components`, stale installed entries are removed from storage
+  - BCS also tries to self-reconcile as installed when it was deployed externally
+
+Public/API contract to preserve unless intentionally changed:
+- `GET /api/bcs`
+- `POST /api/bcs?action=refresh`
+- `GET /api/bcs/settings`
+- `POST /api/bcs/settings`
+- `GET /api/bcs/readme?repo_id=...`
+- `GET /api/bcs/versions?repo_id=...`
+- `GET /api/bcs/repo?repo_id=...`
+- `POST /api/bcs/install?repo_id=...&version=...`
+- `POST /api/bcs/update?repo_id=...&version=...`
+- `POST /api/bcs/uninstall?repo_id=...`
+- `GET /api/bcs/backups?repo_id=...`
+- `POST /api/bcs/restore?repo_id=...&backup_id=...`
+- `POST /api/bcs/restart`
+- `DELETE /api/bcs/custom_repo?id=...`
+
+Storage model:
+- Home Assistant storage key: `bcs_store`
+- Stored sections:
+  - `custom_repos`
+  - `installed_repos`
+  - `settings`
+  - `hacs_cache`
+  - `repo_cache`
+
+Frontend/UI facts:
+- The active HA panel script is `custom_components/bahmcloud_store/panel/panel.js`.
+- The richer UI is implemented there: source filtering, HACS toggle, repo detail loading, version selection, backups restore modal, restart action, and history handling.
+- `panel/app.js`, `panel/index.html`, and `panel/styles.css` look like older standalone or legacy panel assets. Treat them as secondary unless you confirm they are still used for a real path.
+
+Code-analysis findings that should influence future work:
+- `store.py` represents an older store implementation with a different data model (`packages`, `source_path`, older API routes). It does not appear to be the active runtime path for the current integration flow.
+- `custom_repo_view.py` duplicates logic that already exists in `views.py` and looks legacy/unreferenced.
+- README files describe the project direction correctly at a high level, but some wording overstates provider generality. The actual code is provider-neutral in intent, but concretely implemented around GitHub, GitLab, and Gitea-style endpoints.
+- The end-user and full READMEs contain some stale or inconsistent details compared with the current UI and code. Verify behavior in source before using README text as specification.
+- There are visible encoding/mojibake issues in some documentation and older UI assets. Preserve valid UTF-8 when editing.
+
+Project constraints to respect in future edits:
+- Keep async I/O non-blocking in Home Assistant.
+- Avoid startup-heavy network work before HA is fully started.
+- Preserve repo-cache and HACS-cache behavior unless intentionally redesigning refresh logic.
+- Preserve backup-before-overwrite safety for install/update/restore flows.
+- Preserve update-entity behavior for installed repos.
+- Keep the integration UI-admin-only and config-entry-based.
+
+Recommended workflow for future tasks:
+1. Read `README.md`, `README_DEVELOPER.md`, and relevant source files.
+2. Verify whether the requested change belongs in active code or in legacy files.
+3. Implement the change in the active runtime path.
+4. Update documentation if behavior changed.
+5. Append a detailed dated entry to `.idea/changes.md`.
+6. If and only if a release is being prepared with user approval, fold release-worthy changes into `CHANGELOG.md`.
+
+Current release baseline:
+- `manifest.json` version is `0.7.3`
+- Latest documented release in `CHANGELOG.md` is `0.7.3` dated `2026-03-23`

.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,29 @@ Sections:
 
 ---
 
+## 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

custom_components/bahmcloud_store/__init__.py

@@ -59,6 +59,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         BCSSettingsView,
         BCSReadmeView,
         BCSVersionsView,
+        BCSReleaseNotesView,
         BCSRepoDetailView,
         BCSCustomRepoView,
         BCSInstallView,
@@ -74,6 +75,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     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))
@@ -88,7 +90,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> 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=109",
+        module_url="/api/bahmcloud_store_static/panel.js?v=110",
         sidebar_title="Bahmcloud Store",
         sidebar_icon="mdi:store",
         require_admin=True,

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__)
@@ -181,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)
 
@@ -324,6 +433,12 @@ class BCSCore:
         # 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
 
@@ -808,13 +923,21 @@ class BCSCore:
             _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, *, limit: int = 20) -> 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 []
 
         # Prefer cached version lists to avoid hammering provider APIs (notably GitHub unauthenticated
-        # rate limits). We refresh on-demand when the user opens the selector.
+        # 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:
@@ -823,8 +946,17 @@ class BCSCore:
                 cached_ts = int(cached.get("versions_ts", 0) or 0)
 
         now = int(time.time())
-        if isinstance(cached, dict) and cached.get("versions") and (now - cached_ts) < VERSIONS_CACHE_TTL_SECONDS:
-            return list(cached.get("versions") or [])
+        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(
@@ -1035,6 +1167,23 @@ class BCSCore:
             default_branch=repo.default_branch,
         )
 
+    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:
+            return None
+
+        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,
+            github_token=self.config.github_token,
+        )
+
     def _pick_ref_for_install(self, repo: RepoItem) -> str:
         if repo.latest_version and str(repo.latest_version).strip():
             return str(repo.latest_version).strip()
@@ -1665,4 +1814,4 @@ class BCSCore:
         return await self.install_repo(repo_id, version=version)
 
     async def request_restart(self) -> None:
-        await self.hass.services.async_call("homeassistant", "restart", {}, blocking=False)
+        await self.hass.services.async_call("homeassistant", "restart", {}, blocking=False)

custom_components/bahmcloud_store/manifest.json

@@ -1,11 +1,11 @@
 {
   "domain": "bahmcloud_store",
   "name": "Bahmcloud Store",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "documentation": "https://git.bahmcloud.de/bahmcloud/bahmcloud_store",
   "config_flow": true,
   "platforms": ["update"],
   "requirements": [],
   "codeowners": ["@bahmcloud"],
   "iot_class": "local_polling"
-}
+}

custom_components/bahmcloud_store/panel/panel.js

@@ -56,6 +56,10 @@ 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;
@@ -442,6 +446,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)) {
@@ -452,6 +460,7 @@ class BahmcloudStorePanel extends HTMLElement {
     this._loadRepoDetails(repoId);
     this._loadReadme(repoId);
     this._loadVersions(repoId);
+    this._loadReleaseNotes(repoId);
   }
 
 
@@ -499,6 +508,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;
@@ -1250,6 +1294,31 @@ 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>`;
@@ -1303,6 +1372,7 @@ class BahmcloudStorePanel extends HTMLElement {
             </div>
 
             ${versionSelect}
+            ${releaseNotesBlock}
 
             <div class="row" style="margin-top:14px; gap:10px; flex-wrap:wrap;">
               ${installBtn}
@@ -1342,6 +1412,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);
       });
     }
 
@@ -1380,7 +1451,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) {
@@ -1392,6 +1478,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() {
@@ -1554,4 +1654,4 @@ class BahmcloudStorePanel extends HTMLElement {
   }
 }
 
-customElements.define("bahmcloud-store-panel", BahmcloudStorePanel);
+customElements.define("bahmcloud-store-panel", BahmcloudStorePanel);

custom_components/bahmcloud_store/providers.py

@@ -537,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.
     """
 
@@ -575,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):
@@ -597,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):
@@ -676,4 +678,78 @@ async def fetch_repo_versions(
 
     except Exception:
         _LOGGER.debug("fetch_repo_versions failed for %s", repo_url, exc_info=True)
-        return out
+        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/views.py

@@ -349,6 +349,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"