From dafbb9f6d199eee9297c8f7220aee6edbf8e273a Mon Sep 17 00:00:00 2001
From: sHa <sha@shadoll.dev>
Date: Fri, 20 Mar 2026 16:27:18 +0200
Subject: [PATCH] feat: Add AGENTS.md for guidance on Helm charts and automated
 version updates

---
 AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..569544b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a collection of Helm charts for self-hosted applications on Kubernetes, designed for use with FluxCD GitOps. Charts: **jellyfin** (media server + PostgreSQL), **home-assistant** (home automation + PostgreSQL), **esphome** (IoT device dashboard).
+
+## Common Commands
+
+```bash
+# Lint a chart
+helm lint ./jellyfin
+
+# Template a chart (render without installing)
+helm template my-release ./jellyfin -f my-values.yaml
+
+# Install/upgrade a chart
+helm install <release> ./<chart> -f my-values.yaml
+helm upgrade <release> ./<chart> -f my-values.yaml
+
+# Run the automated version update script (checks upstream for new image tags)
+./scripts/update-charts.sh
+```
+
+## Architecture
+
+Each chart follows the same structure: `Chart.yaml`, `values.yaml`, and `templates/` (deployment, service, ingress, plus chart-specific resources like PVCs or init jobs).
+
+### Automated Version Updates
+
+Charts use custom `Chart.yaml` annotations to enable automated upstream version tracking:
+- `version-source`: specifies where to check (e.g., `github-release:jellyfin/jellyfin` or `dockerhub-tags:...`)
+- `version-pattern`: sed pattern to clean the fetched tag (e.g., strip `v` prefix)
+
+`scripts/update-charts.sh` iterates all charts, fetches the latest upstream version, and bumps `appVersion` and `version` (patch increment) in `Chart.yaml` when an update is found. This runs daily via GitHub Actions (`.github/workflows/update-charts.yml`) and optionally sends Signal notifications on updates.
+
+### Chart Conventions
+
+- Image tags default to `Chart.AppVersion` (set via `image.tag | default .Chart.AppVersion`)
+- Secrets are referenced via `existingSecret` — charts never create secrets directly
+- Persistence supports both `hostPath` and PVC modes
+- Jellyfin chart includes a `db-init-job` for PostgreSQL schema initialization
+- ESPHome uses `hostNetwork: true` for mDNS device discovery
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file