From 15cdf7b0907a699d831119e13f3f4d95355b7840 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Fri, 3 Jul 2026 11:26:12 +0200 Subject: [PATCH] docs: CLAUDE.md light expansion (repo purpose, deploy contract, pointers) Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6 --- CHANGELOG.md | 7 +++++++ CLAUDE.md | 31 ++++++++++++++++++++++++++----- CONTEXT.md | 1 + REPORT.md | 40 +++++++++------------------------------- 4 files changed, 43 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f9a1956..5c686d0 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CLAUDE.md b/CLAUDE.md index e9b8c30..56206d1 100644 --- a/CLAUDE.md +++ b/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). -> Cross-repo orientation lives in the workspace-root `e:\git\CLAUDE.md`; catalog format spec in `README.md`. +> Loads when Claude Code touches this repo. Current state: `CONTEXT.md` + `CHANGELOG.md` top. +> Cross-repo orientation: workspace-root `e:\git\CLAUDE.md`. -- See `REUSE.md` before adding or editing an app (conventions, healthcheck families, traps). -- 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. +## What this repo is + +The Felhom **app catalog**: one directory per app under `templates//`, 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. diff --git a/CONTEXT.md b/CONTEXT.md index 90a8055..2ddde52 100644 --- a/CONTEXT.md +++ b/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. diff --git a/REPORT.md b/REPORT.md index e73a38a..6d3c155 100644 --- a/REPORT.md +++ b/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) -**Baseline:** `main` @ `bb81cd414afcb89e28ac60f405133f40195e6c43` +**Date:** 2026-07-03 · **Class:** docs-only (no template changes, no deploy effect) +**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): - 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`. +Consolidated cross-repo report: `felhom.eu/REPORT.md`.