document secrets strategy: .env for tags, .env.secrets for sensitive values

Add Secrets section to README explaining the separation. Add clarifying
comment to .env template and demo files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AlexF4Dev

README.md

@@ -4,6 +4,8 @@ A simplified [Argo CD](https://argo-cd.readthedocs.io/en/stable/)-style reconcil
 
 Image tags live in a `.env` file alongside `docker-compose.yaml` — Docker Compose [loads it automatically](https://docs.docker.com/compose/environment-variables/set-environment-variables/#substitute-with-an-env-file). CI updates `.env` with simple `source`/`sed` (no `yq` needed).
 
+> **Note:** The `.env` file is committed to git and contains only image tags — never secrets. See [Secrets](#secrets) for how to handle sensitive values.
+
 ## Structure
 
 ```
@@ -78,6 +80,28 @@ gh workflow run "CI: Deploy (Demo)"
 
 CI runs automatically on push to main and PRs with 5 parallel validation jobs.
 
+## Secrets
+
+The `.env` file is for image tags only and is committed to git. Keep secrets separate:
+
+```yaml
+# docker-compose.yaml
+services:
+  backend:
+    image: "ghcr.io/myorg/backend:${BACKEND_TAG}"
+    env_file:
+      - .env.secrets  # API keys, DB passwords — gitignored, not managed by CI
+    environment:
+      - NODE_ENV=production
+```
+
+```bash
+# .gitignore
+.env.secrets
+```
+
+This way CI manages `.env` (tags) and your secrets stay in `.env.secrets` (or are injected via the host environment, a secrets manager, etc.). The two files serve different purposes and have different lifecycles.
+
 ## Key Patterns
 
 - **Two-layer change detection** — Semantic tag comparison + GitHub `paths` filter

demo/projects/demo-app/.env

@@ -1,2 +1,3 @@
+# Image tags — managed by CI. Not for secrets (use .env.secrets or env_file).
 BACKEND_TAG=0.24.0
 FRONTEND_TAG=0.23.0

templates/gitops-ci/.env

@@ -1,2 +1,3 @@
+# Image tags — managed by CI. Not for secrets (use .env.secrets or env_file).
 BACKEND_TAG=0.0.0
 FRONTEND_TAG=0.0.0