# CLAUDE.md — `app-catalog-felhom.eu`

> Loads when Claude Code touches this repo. Current state: `CONTEXT.md` + `CHANGELOG.md` top.
> Cross-repo orientation: workspace-root `/mnt/5_hdd/felhom.eu/git/CLAUDE.md`.

## What this repo is

The Felhom **app catalog**: one directory per app under `templates/<app>/`, each holding exactly
`docker-compose.yml` + `.felhom.yml` (deploy fields, resources, healthcheck probe, app_info — all
customer-facing text in Hungarian). The felhom-controller git-syncs these to every customer box;
`.felhom.yml` drives the deploy wizard. `templates.json` + `scripts/generate-customer.sh` are LEGACY
(Portainer-era) — new apps don't touch them.

## Deploy contract

**Push to `main` = deploy.** The controller's sync picks changes up within 15 minutes (or trigger via
the dashboard "Sablonok frissítése" button / `POST /api/sync`). Only the two template files sync;
deployed `app.yaml` (customer secrets) is never overwritten. Full deploy details: the
`felhom-build-deploy` skill.

## Conventions

- **See `REUSE.md` before adding or editing an app** — canonical example app (paperless-ngx),
  required `.felhom.yml` fields, healthcheck family per image type, memory-limit rules, traps.
- Update `REUSE.md` in the same commit that changes a catalog-wide convention.
- `README.md` is the format spec — update its app tables when adding an app.
- Update `CHANGELOG.md` (newest on top) and overwrite `REPORT.md` with every pushed change.
- No secrets in any committed file; secrets are generated at deploy time via `deploy_fields`
  `generate:` specs.
- **Never `:latest` or untagged images in templates** — pin a concrete version tag; an app deployed
  anywhere in the fleet is pinned to the digest it is currently running (a pin must never cause a
  version jump). Digest pins (`@sha256:`) also count. Gate: `python scripts/check-image-pins.py`
  (run after any compose change; exit 1 on any floating/missing tag).
- **A pinned tag can still rot away upstream** — the pin gate is syntactic and cannot see that.
  Second gate: `python3 scripts/check-image-resolvable.py` (exit 0 resolve / 1 GONE / 2 inconclusive),
  run at the start of every catalog campaign and before any publish train that vouches the catalog.
  Needs network + `docker`; unauthenticated Docker Hub throttles a full sweep, so `docker login`
  first or expect exit 2. It reports a throttle as INCONCLUSIVE, never as a dead image.
- **Taking an app out of circulation — use `lifecycle:`, never a directory move.** `.felhom.yml`
  gains an optional `lifecycle:` field: `available` (default; absent/empty means this), `hidden`
  (not offered for new installs, no explanation owed), `abandoned` (upstream stopped developing it —
  not offered for new installs, and every box already running it shows a permanent "Nem karbantartott"
  notice). **Deployed instances keep working in full either way** — the state affects what is
  OFFERED, never what already runs, and the controller REFUSES a deploy of a non-available template
  server-side. An unknown value degrades to `available` with one WARN, so a typo can never brick a
  template. This supersedes the short-lived `retired/` directory move, which was wrong: removing a
  template orphans every customer already running it.