diff --git a/secrets/homeassistant.secrets.example b/secrets/homeassistant.secrets.example
new file mode 100644
index 0000000..cece7fd
--- /dev/null
+++ b/secrets/homeassistant.secrets.example
@@ -0,0 +1,40 @@
+# homeassistant Stack — Secrets Reference
+# Source: homeassistant.env
+#
+# Add SECRET values to Woodpecker at:
+#   https://woodpecker.bryanmail.net
+#   homelab/compose-files → Settings → Secrets
+
+# ── SECRETS (add to Woodpecker) ───────────────────────────────────────────────
+
+# Woodpecker secret name:  homeassistant_frigate_rtsp_password
+# Used for:               Frigate NVR RTSP camera stream password
+# Env var in .env:        FRIGATE_RTSP_PASSWORD
+homeassistant_frigate_rtsp_password=
+
+# Woodpecker secret name:  homeassistant_immich_api_key
+# Used for:               Immich API key for FrImmich face sync integration
+# Env var in .env:        IMMICH_API_KEY
+homeassistant_immich_api_key=
+
+# ── NON-SECRETS (safe in compose file or .env) ────────────────────────────────
+
+# HASS_HOST                  Home Assistant Traefik hostname
+# FRIGATE_HOST               Frigate Traefik hostname
+# ZIGBEE_HOST                Zigbee2MQTT Traefik hostname
+# ESPHOME_HOST               ESPHome Traefik hostname
+# FRIMMICH_HOST              FrImmich Traefik hostname
+# IMMICH_API_URL             Immich internal API URL
+# FRIGATE_FACES_DIR          Container path for face images
+# FRIGATE_API_URL            Frigate internal API URL
+# SYNC_SCHEDULE_INTERVAL_HOURS  FrImmich sync interval
+# LOG_LEVEL                  Log level (INFO)
+# MAX_FACES_PER_PERSON       FrImmich limit
+# SKIP_EXISTING_FACES        FrImmich boolean flag
+
+# ── Woodpecker provision-secrets case entry ───────────────────────────────────
+#
+#   homeassistant)
+#     create_or_update_secret "homeassistant_frigate_rtsp_password" "$HOMEASSISTANT_FRIGATE_RTSP_PASSWORD"
+#     create_or_update_secret "homeassistant_immich_api_key"        "$HOMEASSISTANT_IMMICH_API_KEY"
+#     ;;