diff --git a/secrets/security.secrets.example b/secrets/security.secrets.example
new file mode 100644
index 0000000..6b8d52f
--- /dev/null
+++ b/secrets/security.secrets.example
@@ -0,0 +1,78 @@
+# security Stack — Secrets Reference
+# Source: security.env
+#
+# Add SECRET values to Woodpecker at:
+#   https://woodpecker.bryanmail.net
+#   homelab/compose-files → Settings → Secrets
+#
+# ⚠️  HIGH RISK: This stack runs Authentik (SSO for all other services),
+#     CrowdSec (intrusion prevention), and the Traefik bouncer.
+#     If this stack fails, authentication breaks across the entire homelab.
+#     Migrate carefully and test thoroughly.
+
+# ── SECRETS (add to Woodpecker) ───────────────────────────────────────────────
+
+# Woodpecker secret name:  security_pg_pass
+# Used for:               CrowdSec PostgreSQL connection password
+# Env var in .env:        PG_PASS / CROWDSEC_PGDSN (embedded in DSN)
+security_pg_pass=
+
+# Woodpecker secret name:  security_authentik_secret_key
+# Used for:               Authentik session signing and crypto key
+# Env var in .env:        AUTHENTIK_SECRET_KEY
+security_authentik_secret_key=
+
+# Woodpecker secret name:  security_authentik_pg_password
+# Used for:               Authentik PostgreSQL connection password
+# Env var in .env:        AUTHENTIK_POSTGRESQL__PASSWORD
+security_authentik_pg_password=
+
+# Woodpecker secret name:  security_crowdsec_pgdsn
+# Used for:               CrowdSec full PostgreSQL DSN (contains password)
+#                         NOTE: Store the full DSN string including credentials
+# Env var in .env:        CROWDSEC_PGDSN
+security_crowdsec_pgdsn=
+
+# Woodpecker secret name:  security_bouncer_key_traefik
+# Used for:               CrowdSec bouncer API key for Traefik integration
+# Env var in .env:        BOUNCER_KEY_TRAEFIK
+security_bouncer_key_traefik=
+
+# Woodpecker secret name:  security_crowdsec_api_key
+# Used for:               CrowdSec local API key
+# Env var in .env:        CROWDSEC_API_KEY
+security_crowdsec_api_key=
+
+# Woodpecker secret name:  security_crowdsec_password
+# Used for:               CrowdSec admin password
+# Env var in .env:        CROWDSEC_PASSWORD
+security_crowdsec_password=
+
+# ── NON-SECRETS (safe in compose file or .env) ────────────────────────────────
+
+# AUTHENTIK_ERROR_REPORTING__ENABLED        Boolean flag
+# AUTHENTIK_EMAIL__HOST                     SMTP host
+# AUTHENTIK_EMAIL__PORT                     SMTP port
+# AUTHENTIK_EMAIL__USERNAME                 SMTP username (empty)
+# AUTHENTIK_EMAIL__USE_TLS/SSL              Boolean flags
+# AUTHENTIK_EMAIL__TIMEOUT                  Timeout value
+# AUTHENTIK_EMAIL__FROM                     From address
+# COMPOSE_PORT_HTTP/HTTPS                   Internal ports
+# AUTHENTIK_POSTGRESQL__HOST                PostgreSQL hostname
+# AUTHENTIK_POSTGRESQL__NAME                Database name (authentik)
+# AUTHENTIK_POSTGRESQL__USER                Database username (Authentik)
+# AUTHENTIK_POSTGRESQL__PORT                PostgreSQL port
+# AUTHENTIK_POSTGRESQL__DEFAULT_SCHEMA      Schema name (public)
+# NOTE: AUTHENTIK_EMAIL__PASSWORD is empty — not a secret here
+
+# ── Woodpecker provision-secrets case entry ───────────────────────────────────
+#
+#   security)
+#     create_or_update_secret "security_pg_pass"                "$SECURITY_PG_PASS"
+#     create_or_update_secret "security_authentik_secret_key"   "$SECURITY_AUTHENTIK_SECRET_KEY"
+#     create_or_update_secret "security_authentik_pg_password"  "$SECURITY_AUTHENTIK_PG_PASSWORD"
+#     create_or_update_secret "security_crowdsec_pgdsn"         "$SECURITY_CROWDSEC_PGDSN"
+#     create_or_update_secret "security_bouncer_key_traefik"    "$SECURITY_BOUNCER_KEY_TRAEFIK"
+#     create_or_update_secret "security_crowdsec_api_key"       "$SECURITY_CROWDSEC_API_KEY"
+#     create_or_update_secret "security_crowdsec_password"      "$SECURITY_CROWDSEC_PASSWORD"
+#     ;;