From d292e7c48d141f6f4a4dc3225af364b5c06b4bb5 Mon Sep 17 00:00:00 2001
From: "A. F. Dudley" <a.frederick.dudley@gmail.com>
Date: Tue, 3 Feb 2026 01:14:25 -0500
Subject: [PATCH] Add k8s-kind architecture documentation to CLAUDE.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0626ac93..50776741 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,6 +83,47 @@ laconic-so deployment --dir deployment start
 - `urbit-stack` - Fake Urbit ship for testing
 - `zenith-desk-stack` - Desk deployment stack
 
+## 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