docs: CLAUDE.md light expansion (repo purpose, deploy contract, pointers)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-07-03 — docs: CLAUDE.md light expansion
+
+The minimal REUSE-rollout stub expanded to a proper (still ~30-line) CLAUDE.md: what the repo is
+(one dir per app, two template files, Hungarian customer text), the push-to-main = deploy contract
+(controller sync ≤15 min / manual trigger), legacy `templates.json` warning, and pointers
+(REUSE.md, README format spec, the `felhom-build-deploy` skill). No template changes.
+
 ## 2026-07-03 — docs: REUSE.md introduced
 
 Cross-repo reuse-map rollout (docs-only). New `REUSE.md`: catalog conventions verified against all

CLAUDE.md

@@ -1,8 +1,29 @@
 # CLAUDE.md — `app-catalog-felhom.eu`
 
-> Minimal for now (created with the REUSE.md rollout; a full CLAUDE.md refresh is a separate task).
+> Loads when Claude Code touches this repo. Current state: `CONTEXT.md` + `CHANGELOG.md` top.
-> Cross-repo orientation lives in the workspace-root `e:\git\CLAUDE.md`; catalog format spec in `README.md`.
+> Cross-repo orientation: workspace-root `e:\git\CLAUDE.md`.
 
-- See `REUSE.md` before adding or editing an app (conventions, healthcheck families, traps).
+## What this repo is
-- Update `REUSE.md` if you added/changed/deprecated a catalog-wide convention (same commit).
+
-- Update `CHANGELOG.md` (newest on top) and overwrite `REPORT.md` with every pushed change, per workspace convention.
+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.

CONTEXT.md

@@ -2,4 +2,5 @@
 
 > Created with the REUSE.md rollout (2026-07-03). History: `CHANGELOG.md`; format spec: `README.md`.
 
+- **2026-07-03 — CLAUDE.md expanded** (repo purpose, push-to-main deploy contract, pointers); still intentionally light.
 - **2026-07-03 — `REUSE.md` exists at the repo root** (catalog conventions, healthcheck families, canonical example app = paperless-ngx, traps); maintenance rule active: update it in the same commit that changes a catalog-wide convention.

REPORT.md

@@ -1,34 +1,12 @@
-# REPORT — docs: REUSE.md introduced (cross-repo reuse map)
+# REPORT — docs: CLAUDE.md light expansion
 
-**Date:** 2026-07-03 · **Class:** docs-only (no template change, no deploy effect)
+**Date:** 2026-07-03 · **Class:** docs-only (no template changes, no deploy effect)
-**Baseline:** `main` @ `bb81cd414afcb89e28ac60f405133f40195e6c43`
+**Baseline:** `main` @ `c5a3d1b15b` (unchanged)
 
-## What was done
+The minimal REUSE-rollout CLAUDE.md stub expanded (diffstat: +26/−5, ~30 lines total): repo purpose
+(one dir per app, `docker-compose.yml` + `.felhom.yml`, Hungarian customer text), the push-to-main =
+deploy contract (controller git-sync ≤15 min, manual trigger via "Sablonok frissítése" /
+`POST /api/sync`, `app.yaml` never overwritten), the legacy `templates.json` warning, and pointers
+(REUSE.md conventions, README format spec, `felhom-build-deploy` skill).
 
-- **`REUSE.md`** created at the repo root (58 lines, light §2/§5-focused variant per spec):
+Consolidated cross-repo report: `felhom.eu/REPORT.md`.
-  the canonical example app (**paperless-ngx** — copy its structure), `.felhom.yml` required-field
-  set (verified across all 53 apps), deploy_fields conventions, the five Docker-healthcheck families
-  (BusyBox wget / curl / Node / Python / DB sidecars) each with a cited example, the memory
-  request/limit convention (`mem_limit` = sum of compose limits; limits enforced, no reservations),
-  the new-app checklist, and traps (gokapi entrypoint hack; legacy `templates.json` +
-  `scripts/generate-customer.sh`; uptime-kuma's image-specific healthcheck binary).
-- **`CLAUDE.md`** created (minimal — this repo had none): the REUSE.md pointer + same-commit
-  maintenance rule + the workspace CHANGELOG/REPORT convention. A full CLAUDE.md is a separate task.
-- `CHANGELOG.md` entry + `CONTEXT.md` created (one-liner).
-
-## Verification
-
-`python felhom.eu/scripts/reuse_refs_check.py e:/git/app-catalog-felhom.eu` →
-`OK [app-catalog-felhom.eu]: 10 cited paths, all exist`. Sweep: 53 apps scanned (all 53 descriptors
-share the same top-level key set; optional extras verified per file).
-
-## Observations (NOT acted on) — README drift, recorded in REUSE.md §6
-
-- README lists `templates/filebrowser/` (doesn't exist); omits `templates/recipe-importer/` (does).
-- README field-type table omits `subdomain` (all 53 apps use it) and `secret_input` (romm); lists
-  `boolean` which nothing uses.
-- README says smtp_mapping = "Vaultwarden, Mealie"; six apps carry it (calcom, gitea, mealie,
-  nextcloud, rallly, vaultwarden).
-- Healthcheck URL style drift (localhost vs 127.0.0.1, `curl -f` vs `-sf`, two Node one-liner styles).
-
-Cross-repo summary + full sweep counts: `felhom.eu/REPORT.md`.