update 33.1 50

CLAUDE.md

@@ -51,20 +51,19 @@ spr/
 │   └── amar/              # Amar room config
 │       ├── config.json
 │       ├── data/
-│       ├── artery/        # Amar-specific (merged into output)
-│       │   └── shunts/amar/
-│       ├── atlas/         # Amar-specific books
-│       │   └── books/
-│       ├── station/       # Amar-specific tools config
-│       │   └── tools/datagen/
+│       ├── soleprint/     # Room overlay — merged over soleprint/ on build
+│       │   ├── artery/    #   room shunts, pulses
+│       │   │   └── shunts/amar/
+│       │   ├── atlas/     #   room books
+│       │   │   └── books/
+│       │   ├── station/   #   room tool configs
+│       │   │   └── tools/datagen/
+│       │   └── nginx/
+│       ├── ctrl/          # Room lifecycle scripts (copied into gen/<room>/)
 │       ├── link/          # Bridge to managed app
-│       ├── soleprint/     # Soleprint docker config
-│       ├── databrowse/
-│       ├── tester/
-│       ├── monitors/
-│       └── models/
+│       └── amar/          # The managed app itself
 │
-├── ctrl/                  # Build/run scripts
+├── ctrl/                  # Build/run scripts (see Build & Run)
 │
 └── gen/                   # Built instances (gitignored)
     ├── standalone/
@@ -100,26 +99,38 @@ Each room in `cfg/` has:
 - `config.json` - Framework branding/terminology
 - `data/` - Data files (veins.json, shunts.json, etc.)
 
-Room-specific system configs (merged into output):
-- `artery/` - Room-specific shunts, pulses
-- `atlas/` - Room-specific books
-- `station/` - Room-specific tool configs (datagen, tester tests, etc.)
+Room-specific system configs live under `cfg/<room>/soleprint/` and are merged over
+the core `soleprint/` tree at build time:
+- `soleprint/artery/` - Room-specific shunts, pulses
+- `soleprint/atlas/` - Room-specific books
+- `soleprint/station/` - Room-specific tool configs (datagen generators, tester tests)
+
+A room's own lifecycle scripts live in `cfg/<room>/ctrl/` and land in
+`gen/<room>/ctrl/` — that is what `make start <room>` dispatches to.
 
 ## Build & Run
 
+`make` is the front door — one target per `ctrl/` script, with the subcommand as an
+argument (`make cluster up`, not `make cluster-up`). The logic lives in the scripts,
+never in the Makefile. `make help` lists every target.
+
 ```bash
-# Build
-python build.py                    # -> gen/standalone/
-python build.py --cfg amar         # -> gen/amar/
-python build.py --all              # -> all rooms
+make                          # = make help
+make build [room|all|models]  # -> gen/<room>/   (default: standalone)
+make start [room] [-d]        # dispatches to gen/<room>/ctrl/start.sh
+make stop  [room]
+make cluster [up|down|status] # the shared `spr` kind cluster
+make component [list|sync|watch|publish|diff]
+make deploy [--build|--sync-only]
+```
 
-# Run bare-metal
-cd gen/standalone && python run.py
+Every script stays runnable on its own — the standalone rule holds:
 
-# Using ctrl scripts
-./ctrl/build.sh [room]
-./ctrl/start.sh [room] [-d]
-./ctrl/stop.sh [room]
+```bash
+python build.py --cfg amar         # -> gen/amar/
+cd gen/standalone && python run.py # bare-metal
+./ctrl/kind-up.sh                  # still works directly
+cd gen/<room> && ./ctrl/start.sh   # each room owns its lifecycle scripts
 ```
 
 ## Adding a New Room
@@ -129,12 +140,12 @@ mkdir -p cfg/newroom/data
 cp cfg/standalone/config.json cfg/newroom/
 cp -r cfg/standalone/data/* cfg/newroom/data/
 
-# Add room-specific configs as needed:
-# cfg/newroom/artery/shunts/...
-# cfg/newroom/atlas/books/...
-# cfg/newroom/station/tools/...
+# Add room-specific configs as needed (note the soleprint/ overlay level):
+# cfg/newroom/soleprint/artery/shunts/...
+# cfg/newroom/soleprint/atlas/books/...
+# cfg/newroom/soleprint/station/tools/datagen/<name>.py
 
-python build.py --cfg newroom
+make build newroom
 ```
 
 ## Ports