docs: add foundation docs and cluster configuration templates

- README: cluster architecture, quick start, use cases
- USAGE: stack topology, custom CLI reference
- TROUBLESHOOTING: operational safety rules
- .env.example: configuration template
- Makefile: build shortcuts

.env.example

@@ -0,0 +1,70 @@
+# .env.example
+# Copy to .env and fill in. The real .env is gitignored — never commit it.
+# Leave any value empty and vsource will fetch it from Vault at cluster/<KEY>.
+
+# ── Cluster Configuration ──────────────────────────────────────────────────────
+# Base domain for external services (Authentik, MinIO, Forgejo, etc.)
+#   Example: riotpiao.homelab.com
+CLUSTER_DOMAIN=riotpiao.homelab.com
+
+# Internal Kubernetes DNS names (svc.cluster.local)
+# Only change these if your cluster domain differs
+POSTGRES_HOST=ddb-cluster-rw.ddb.svc.cluster.local
+MINIO_ENDPOINT=minio.storage.svc.cluster.local:9000
+KAFKA_BOOTSTRAP=kmsvc-kafka-bootstrap.sqs.svc.cluster.local:9092
+REDIS_ADDR=kmsvc-redis-master.sqs.svc.cluster.local:6379
+
+# ── Authentik ──────────────────────────────────────────────────────────────────
+# Signing/encryption key. SET ONCE — rotating invalidates all sessions and tokens.
+#   openssl rand -base64 60 | tr -d '\n'
+AUTHENTIK_SECRET_KEY=
+
+# Initial password for the built-in admin 'akadmin'. Change after first login.
+#   openssl rand -base64 24
+AUTHENTIK_BOOTSTRAP_PASSWORD=
+
+# Initial API token for 'akadmin' (automation / blueprints).
+#   openssl rand -hex 32
+AUTHENTIK_BOOTSTRAP_TOKEN=
+
+# Password for the bundled PostgreSQL 'authentik' user.
+#   openssl rand -base64 24
+AUTHENTIK_PG_PASSWORD=
+
+# ── MinIO ──────────────────────────────────────────────────────────────────────
+MINIO_ROOT_USER=
+MINIO_ROOT_PASSWORD=
+
+# ── Grafana ────────────────────────────────────────────────────────────────────
+GRAFANA_ADMIN_PASSWORD=
+
+# ── Forgejo ────────────────────────────────────────────────────────────────────
+FORGEJO_ADMIN_PASSWORD=
+
+# ── OIDC client secrets (required) ────────────────────────────────────────────
+# These must be pre-generated and stored in Vault before running setup_talos_iam.sh.
+#   talos put cluster/GRAFANA_OIDC_CLIENT_SECRET GRAFANA_OIDC_CLIENT_SECRET="$(openssl rand -hex 32)"
+GRAFANA_OIDC_CLIENT_SECRET=
+MINIO_OIDC_CLIENT_SECRET=
+AUTHENTIK_FORGEJO_CLIENT_SECRET=
+AUTHENTIK_ARGOCD_CLIENT_SECRET=
+AUTHENTIK_OLLAMA_CLIENT_SECRET=
+AUTHENTIK_TEMPORAL_CLIENT_SECRET=
+AUTHENTIK_KMSVC_CLIENT_SECRET=
+AUTHENTIK_LONGHORN_CLIENT_SECRET=
+AUTHENTIK_PORTAINER_CLIENT_SECRET=
+
+# ── OIDC client IDs (optional) ────────────────────────────────────────────────
+# Leave empty to use the provider name as client_id (the safe default).
+# Only set if you need a custom client_id (e.g. after rotating a compromised credential).
+#   talos put cluster/AUTHENTIK_ARGOCD_CLIENT_ID AUTHENTIK_ARGOCD_CLIENT_ID="my-custom-id"
+GRAFANA_OIDC_CLIENT_ID=
+MINIO_OIDC_CLIENT_ID=
+AUTHENTIK_FORGEJO_CLIENT_ID=
+AUTHENTIK_ARGOCD_CLIENT_ID=
+AUTHENTIK_OLLAMA_CLIENT_ID=
+AUTHENTIK_TEMPORAL_CLIENT_ID=
+
+# ── CI/CD ──────────────────────────────────────────────────────────────────────
+# Forgejo Personal Access Token (from rock user) for pushing images to registry
+FORGEJO_RIOTPIAO_PAT=