diff --git a/CLAUDE.md b/CLAUDE.md
index 23c5b6f..8b93889 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,12 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## ⚠️ CRITICAL: Flux CD Deployment
+
+**This repository is deployed via Flux CD.** All manifests use Flux variable substitution syntax (e.g., `${VARIABLE_NAME}`).
+
+**DO NOT replace Flux variables with hardcoded values.** Flux substitutes these variables at deployment time from ConfigMaps or Secrets.
+
 ## Project Overview
 
 This repository contains Kubernetes manifests for deploying IRC-related applications (The Lounge web client and ZNC bouncer) using Kustomize. The infrastructure is deployed to a Kubernetes cluster with Flux CD and uses Gitea Actions for CI/CD validation and security scanning.
diff --git a/README.md b/README.md
index 2f02438..657a881 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,20 @@
 # irc
 
-Some useful apps for IRC
\ No newline at end of file
+Kubernetes manifests for IRC applications, deployed via Flux CD.
+
+## Applications
+
+- **The Lounge** - Modern web IRC client
+- **ZNC** - IRC bouncer
+
+## Deployment
+
+This repository is deployed to Kubernetes using **Flux CD** with variable substitution. Configuration variables (e.g., hostnames) are provided via ConfigMaps at deployment time.
+
+## CI/CD
+
+Automated validation and security scanning via Gitea Actions:
+- YAML linting and Kustomize validation
+- Kubernetes schema validation (kubeconform)
+- Security scanning (Trivy, Checkov)
+- Best practices analysis (kube-score, Polaris)
\ No newline at end of file