# 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.

> TL;DR: 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

- **Index (`store.yaml`)**: your curated list of repositories. Example:
  ```yaml
  refresh_seconds: 300
  repos:
    - name: Easy Proxmox
      url: https://git.bahmcloud.de/bahmcloud/easy_proxmox
      category: Infrastructure
  ```
- **Sources**:
  - **BCS Official** → entries from your index (`store.yaml`)
  - **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 your 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)
- **Category** filter
- **Source** filter (BCS/HACS/Custom)
- **Sort** (name, updated, etc.)
- **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.

**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.
2. Select **Restore…**.
3. Pick one of the **last backups** (up to retention limit).
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). 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)

**To add a custom repo** (typical flows):
- From the Store UI (if available), or
- via API (see developer docs), or
- by editing your local custom repo storage (advanced).

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 `store.yaml` (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

If you enable HACS, keep your `store.yaml` light and curated.

---

## 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.
- **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.