diff --git a/CLAUDE.md b/CLAUDE.md
index d14f3620..fc134ead 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,6 +44,47 @@ This project follows principles inspired by literate programming, where developm
 
 This approach treats the human-AI collaboration as a form of **conversational literate programming** where understanding emerges through dialogue before code implementation.
 
+## Architecture: k8s-kind Deployments
+
+### One Cluster Per Host
+There is **one Kind cluster per host by design**. Multiple deployments (stacks) share this cluster. Never request or expect separate clusters for different deployments on the same host.
+
+- `create_cluster()` in `helpers.py` reuses any existing cluster
+- Cluster name in deployment.yml is an identifier, not a cluster request
+- All deployments share ingress controller, etcd, certificates
+
+### External Stacks
+External stacks are detected by filesystem path existence (`Path(stack).exists()`). Required structure:
+
+```
+<repo>/
+  stack_orchestrator/data/
+    stacks/<name>/stack.yml
+    compose/docker-compose-<pod>.yml
+  deployment/spec.yml
+```
+
+Config/compose resolution: external path first, then internal fallback.
+
+### Deployment Lifecycle
+- `deploy create`: Initializes deployment dir, generates cluster-id, processes spec.yml
+- `deployment start`: Creates/reuses cluster, deploys K8s resources
+- `deployment restart`: Git pulls stack repo, syncs spec, redeploys (preserves data)
+- `deployment stop`: Removes K8s resources (cluster persists)
+
+### Secret Generation
+`$generate:type:length$` tokens in spec.yml config section:
+- Processed during `deploy create`
+- Stored in K8s Secret `<deployment>-generated-secrets`
+- Injected via `envFrom` with `secretRef`
+- Non-secret config goes to `config.env`
+
+### Key Files
+- `spec.yml`: Deployment specification (in stack repo)
+- `deployment.yml`: Cluster-id, stack-source path (generated)
+- `config.env`: Non-secret environment variables (generated)
+- `kind-config.yml`: Kind cluster configuration (generated)
+
 ## Insights and Observations
 
 ### Design Principles