init rig

gen/<room>/ is the docker build context and soleprint/Dockerfile is `COPY . .`,
so anything reaching gen/ reaches an image layer — and registry.mcrn.ar is
public-read. station/tools/tester/.env has been gitignored since the last
incident, but .gitignore does not bind shutil: copy_path() called
shutil.copytree() with no ignore=, so the key was copied into every built room.
Verified extractable from soleprint_localtest-soleprint:latest (built 8 days
ago) at /app/station/tools/tester/.env.

ctrl/deploy.sh's --exclude='.env' is why this looked handled; it only covers the
rsync path, not the build-and-push path.

Two layers now:
  - copy_path()/merge_into() filter .env, __pycache__, *.pyc, .git, node_modules
    and virtualenvs out of bulk directory copies. Single-file copies named by a
    caller are untouched, so cfg/<room>/.env.example still ships.
  - soleprint/.dockerignore repeats the rule at the docker boundary and is
    copied into the context beside the Dockerfile. Follows the convention
    soleprint/atlas/.dockerignore already set (.env, .env.*, !.env.example).

Runtime is unaffected: no Dockerfile COPYs a .env, and the room compose files
supply it with `env_file: - .env`, read from the host at run time.

The key itself still needs rotating — it remains in git history.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1,27 @@
+# Copied verbatim from rig/.gitattributes, and deliberately duplicated rather
+# than shared: rig/ must carry its own so it survives being handed over on its
+# own, and spr had none at all despite shipping ctrl/*.sh and generating
+# gen/<room>/ctrl/*.sh.
+#
+# Line endings are normalised to LF in the repository and on checkout, on every
+# platform. Without this, a checkout on Windows/WSL rewrites files to CRLF and
+# every one of them shows up as modified without anyone having touched it.
+#
+# For the scripts it is not cosmetic: a shell script with CRLF fails on Linux
+# with `bad interpreter: /usr/bin/env bash^M`, which reads as a broken installer
+# rather than a line-ending problem — the worst possible first impression on a
+# machine where nothing has been proven yet.
+* text=auto eol=lf
+
+*.sh   text eol=lf
+*.py   text eol=lf
+*.env  text eol=lf
+*.yaml text eol=lf
+*.yml  text eol=lf
+
+# Never touch binaries.
+*.png binary
+*.jpg binary
+*.zip binary
+*.tar binary
+*.gz  binary

.gitignore

@@ -34,3 +34,13 @@ cfg/amar/
 cfg/dlt/
 # Add new rooms here as they are created
 # cfg/<room>/
+
+# Client rigs. A rig is a copy of rig/ renamed after the environment it models,
+# so its k8s files spell out a real architecture — exactly the thing that must
+# not land here. They are versioned in their own repo.
+#
+# Anchored at the ROOT on purpose: a copy is a SIBLING of rig/, so a rule inside
+# rig/.gitignore cannot see it. The negation must name the full path for the same
+# reason — `*-rig/` is unanchored and matches at any depth, including rig/sample-rig.
+*-rig/
+!rig/sample-rig/

Makefile

@@ -33,6 +33,12 @@ ifneq ($(ARGS),)
 # then fails with "No rule to make target 'sample'", because make reads every
 # word on the line as something it has been asked to build.
 $(eval $(ARGS):;@:)
+# ...and as PHONY, because some of those words name real directories. `cfg`,
+# `ctrl`, `docs`, `gen` and `init` all exist at this level, and make considers a
+# target that is an existing directory already built — so `make build ctrl` ran
+# the build and then printed "make: 'ctrl' is up to date". The empty rule above
+# is not enough on its own; only .PHONY stops make consulting the filesystem.
+.PHONY: $(ARGS)
 endif
 
 .DEFAULT_GOAL := help

build.py

@@ -80,6 +80,30 @@ def _rmtree_resilient(path: Path):
     )
 
 
+# Never swept into a built room, wherever they appear in a source tree.
+#
+# This is a SECURITY boundary, not tidiness. gen/<room>/ is the docker build
+# context, soleprint/Dockerfile is `COPY . .`, and there is no .dockerignore —
+# so anything that reaches gen/ reaches an image layer, and registry.mcrn.ar is
+# public-read. That is how station/tools/tester/.env, gitignored since the last
+# incident, still ended up baked into soleprint_localtest-soleprint:latest with
+# its API key intact. .gitignore does not bind shutil.
+#
+# Applied to bulk directory copies only. A caller naming a single file is making
+# an explicit request (cfg/<room>/.env.example is the one that matters) and is
+# left alone.
+ALWAYS_IGNORE = {".git", "__pycache__", "node_modules", ".venv", "venv", ".env"}
+ALWAYS_IGNORE_SUFFIXES = (".pyc", ".pyo")
+
+
+def is_ignored(name: str) -> bool:
+    return name in ALWAYS_IGNORE or name.endswith(ALWAYS_IGNORE_SUFFIXES)
+
+
+def _copytree_ignore(directory, files):
+    return {f for f in files if is_ignored(f)}
+
+
 def copy_path(source: Path, target: Path, quiet: bool = False):
     """Copy file or directory, resolving symlinks."""
     if target.is_symlink():
@@ -91,7 +115,7 @@ def copy_path(source: Path, target: Path, quiet: bool = False):
             target.unlink()
 
     if source.is_dir():
-        shutil.copytree(source, target, symlinks=False)
+        shutil.copytree(source, target, symlinks=False, ignore=_copytree_ignore)
         if not quiet:
             log.info(f"  {target.name}/")
     else:
@@ -111,6 +135,8 @@ def merge_into(source: Path, target: Path):
     for item in source.rglob("*"):
         if item.is_file():
             rel = item.relative_to(source)
+            if any(is_ignored(part) for part in rel.parts):
+                continue
             dest = target / rel
             dest.parent.mkdir(parents=True, exist_ok=True)
             shutil.copy2(item, dest)
@@ -687,6 +713,7 @@ def build_soleprint(output_dir: Path, room: str):
         "index.html",
         "requirements.txt",
         "Dockerfile",
+        ".dockerignore",
     ]:
         if (soleprint / name).exists():
             copy_path(soleprint / name, output_dir / name)

rig/.gitattributes

@@ -0,0 +1,22 @@
+# Line endings are normalised to LF in the repository and on checkout, on every
+# platform. Without this, a checkout on Windows/WSL rewrites files to CRLF and
+# every one of them shows up as modified without anyone having touched it.
+#
+# For the scripts it is not cosmetic: a shell script with CRLF fails on Linux
+# with `bad interpreter: /usr/bin/env bash^M`, which reads as a broken installer
+# rather than a line-ending problem — the worst possible first impression on a
+# machine where nothing has been proven yet.
+* text=auto eol=lf
+
+*.sh   text eol=lf
+*.py   text eol=lf
+*.env  text eol=lf
+*.yaml text eol=lf
+*.yml  text eol=lf
+
+# Never touch binaries.
+*.png binary
+*.jpg binary
+*.zip binary
+*.tar binary
+*.gz  binary

rig/.gitignore

@@ -0,0 +1,20 @@
+# def/ — the "default" scratch bucket: always gitignored, never versioned
+def
+
+# local env (commit the .env.example, never the .env)
+.env
+.env.local
+ctrl/.env
+
+# generated: the .dot is a build artifact rendered from arch/*.json, never hand-edited.
+# The .svg IS committed — onboarding material should render in a repo browser.
+arch/*.dot
+ctrl/Tiltfile.gen
+
+# binaries pulled by `make deps-bundle` for the air-gapped wizard image
+vendor
+
+# Client rigs are NOT ignored here. A copy is a SIBLING of this directory
+# (spr/acme-rig), so a rule in this file cannot see it — the rules live in
+# spr/.gitignore, anchored at spr's root, where `*-rig/` matches the siblings and
+# `!rig/sample-rig/` keeps the committed stand-in.

rig/BOOTSTRAP.md

@@ -0,0 +1,278 @@
+# From a machine with nothing on it to a project you can work in
+
+The README says the prerequisite is Docker and nothing else. This is what that
+actually looks like end to end: a bare Linux box, and a new project running under
+Tilt at the end of it.
+
+rig lives inside soleprint, at `spr/rig` — it is soleprint's cluster half, and
+a client copy is a sibling (`spr/acme-rig`). Paths below are relative to
+soleprint's checkout.
+
+It spans three repos because the work does. **rig** prepares the machine — the
+pinned toolchain, the cluster, the port arithmetic. **all** owns the shape a
+project takes, in `all/projects/templates/conventions.md` and the `broad`
+scaffold beside it. **ppl** owns everything after local, and is where this
+document stops.
+
+Read it once before running anything. Three of the steps below need root and one
+needs a logout, so knowing about them in advance is cheaper than meeting them
+halfway through.
+
+
+## Docker, and the two sysctls Tilt depends on
+
+rig installs a toolchain; it does not install Docker. That line is not modesty —
+Docker is a daemon, a group membership and usually a logout, and a script that
+did it would have to be trusted with root on a machine it knows nothing about.
+
+```bash
+sudo apt-get install -y docker.io && sudo usermod -aG docker "$USER"
+```
+
+Then log out and back in, and check `docker info` answers. Until it does, nothing
+below works and everything below reports the same failure.
+
+While you have root, raise the inotify limits:
+
+```bash
+echo -e 'fs.inotify.max_user_watches=524288\nfs.inotify.max_user_instances=512' \
+  | sudo tee /etc/sysctl.d/99-rig.conf
+sudo sysctl --system
+```
+
+kind and Tilt both watch large trees, and WSL ships 8192 watches and 128
+instances — far too low. The failure mode is the reason this is here at step
+zero rather than mentioned later: Tilt does not error, it simply stops noticing
+that files changed, and you lose an afternoon to a hot reload that silently
+isn't.
+
+
+## Read the docs before installing anything
+
+```bash
+cd spr/rig
+make docs
+```
+
+`ctrl/docs.sh` runs a throwaway `nginx:alpine` over a read-only bind mount of
+`docs/` and prints the URL. That is deliberate: the docs are the instructions for
+building everything else, so they cannot live in the cluster and cannot need
+`python3 -m http.server` either — a minimal Debian has no python. What it has,
+by definition, is Docker.
+
+The port is this environment's `HTTP_PORT + 4`. Nothing is installed and nothing
+persists; ctrl-c ends it.
+
+
+## Ask what is wrong with this machine
+
+```bash
+make station
+cp ctrl/.env.example ctrl/.env
+```
+
+`station.sh` reports and instructs, and fixes nothing. It runs bare rather than
+in a container because host detection only ever reads `/proc` and `/etc` — no
+dependency beyond coreutils.
+
+Read the whole output, but the `ports` block is the one to read carefully. Every
+port rig binds derives from this directory's name, so the answer is specific to
+this copy, and a clash here surfaces as an opaque `failed to bind host port` in
+the middle of cluster creation if you skip it.
+
+Copy the `.env` even though station only warns about it. It is gitignored, it is
+where a machine-local override goes, and `ports.sh persist` expects it to exist.
+
+
+## Install the toolchain — through the container
+
+This is the step where "nothing installed" stops being rhetorical.
+
+`make deps` runs `ctrl/wizard.sh install` directly on the host, and the wizard
+fetches with `curl`. A stock `debian:trixie-slim` has no curl — detection runs
+fine, then the first download dies with `curl: command not found` and an exit
+code of 127. That is the bootstrap paradox `ctrl/Dockerfile.wizard` exists
+to kill — the wizard carries its own toolchain so the host needs only Docker —
+but building the image and running it are two different things, and only the
+build has a Makefile target today. **On a genuinely bare machine, run it by
+hand:**
+
+```bash
+make wizard                          # builds rig-wizard:wizard
+mkdir -p ~/.local/bin
+docker run --rm \
+  -v /:/host:ro \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v "$HOME/.local/bin:/out/bin" \
+  -e HOST_UID="$(id -u)" -e HOST_GID="$(id -g)" \
+  rig-wizard:wizard install dev
+```
+
+The image name follows the directory, like everything else here: in `spr/rig`
+it is `rig-wizard`, in a copy called `spr/acme-rig` it is `acme-rig-wizard`. The
+tag is `wizard` (or `full`, below), not `latest`.
+
+None of the four arguments are guessable, so:
+
+- **`/:/host:ro`** — the wizard reads the *host's* `/etc/os-release` and
+  `/etc/wsl.conf`, not the container's. `HOST_ROOT=/host` is already baked into
+  the image; this is what it points at. Read-only, and it is the only reason
+  detection inside a container tells you anything about the machine.
+- **the docker socket** — how detection reaches the daemon it is reporting on,
+  and how it counts kind clusters already running.
+- **`/out/bin`** — the image's `OUT_BIN`. Whatever you mount here is where the
+  four binaries land.
+- **`HOST_UID` / `HOST_GID`** — the wizard runs as root so it can reach that
+  socket, which means everything it writes into a mounted volume is root-owned
+  and useless to you. These drive the `chown` back. Omit them and the install
+  looks like it worked.
+
+`dev` is kubectl, jq, kind and tilt. `core` is kubectl and jq alone — no cluster
+tooling — which is the right answer on a managed or corporate-issued machine and
+is why the split exists.
+
+Then put them on PATH, which the wizard will remind you about because it cannot
+edit your shell for you:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"     # and add the same line to ~/.bashrc
+```
+
+If something else on this machine already provides `kubectl`, the wizard says so
+by name rather than shadowing it quietly. `OUT_BIN=$PWD/def/bin` installs
+somewhere private instead.
+
+**Two variants worth knowing before you need them.** `make wizard full` bakes
+every pinned binary into the image at build time (`DEPS_SOURCE=baked`), so
+`docker save` gives you the entire installer as one file to carry into an
+air-gapped network. And `DEPS_SOURCE=artifactory` with `DEPS_ARTIFACTORY_URL`
+pulls from a generic internal repo, which is usually the only thing a locked-down
+client allows.
+
+From here on this machine has curl, so **`make deps` is the short form** for
+every later run and every later copy of this directory. The container path is
+the first-time path.
+
+
+## Prove the machine before blaming the project
+
+```bash
+make setup
+make cluster up
+kubectl get nodes
+```
+
+`make setup` re-runs every check as a group. It is idempotent and it deliberately
+does not abort on the first failure — a setup script that dies at step two hides
+the fact that steps four and five were also going to fail. Run now, it should be
+`ok` and `done` all the way down, and that is the point: it is the scoreboard,
+not the installer.
+
+`make cluster up` builds the default `minimal` profile — one node, no addons,
+boots fast. You do not need it to develop anything, but you do want to know that
+kind, the kubeconfig context and the derived port block work *before* a new
+project has any problems of its own to confuse them with. `make cluster down`
+when you are done looking.
+
+Before starting a second cluster, and it will not be long:
+
+```bash
+make cluster list
+```
+
+Available memory, per-cluster usage and each cluster's port block. On a 16 GiB
+box four single-node clusters are comfortable and six push into swap, so this is
+worth reading before rather than after. `make cluster free <names>` stops
+clusters without deleting them; `docker start` brings them back untouched.
+
+
+## Scaffold the project
+
+The canonical layout is [`all/projects/templates/conventions.md`](../all/projects/templates/conventions.md).
+Read it — it is short, opinionated, and exists precisely so nobody
+reverse-engineers a layout from whichever repo they happened to open. What
+follows is only the mechanical part.
+
+```bash
+SLUG=<slug>                                    # short, lowercase, no separators
+cp -r ~/wdir/all/projects/templates/broad ~/wdir/"$SLUG"
+cd ~/wdir/"$SLUG"
+grep -rl '<slug>' ctrl | xargs sed -i "s/<slug>/$SLUG/g"
+cp ctrl/k8s/.env.example ctrl/k8s/.env
+git init && git add -A && git commit -m "scaffold $SLUG from broad"
+```
+
+`<slug>` is the only placeholder and it lives only under `ctrl/` — cluster name,
+namespace, ConfigMap name, and the `NAME=` in `kind-up.sh` / `kind-down.sh`. One
+sed does all of it.
+
+The slug is the folder name, lowercase and short — `mpr`, `unt`, `nvi`. The
+cluster takes that name and the context becomes `kind-<slug>`, derived by the
+scaffold's Makefile from the directory, so there is nothing to edit for either.
+
+**Pick the Tilt port deliberately.** `ctrl/k8s/.env.example` ships a value that
+is already in use, so copying it unchanged puts two projects on one port:
+
+```bash
+grep -h '^TILT_PORT=' ~/wdir/*/ctrl/k8s/.env 2>/dev/null | sort
+```
+
+Choose a free one in `10300–10399` — the range ALL reserves in
+`projects/index.json` under `policy` — avoiding `10350`, which is Tilt's own
+default. Currently taken: `nvi` 10330, `unt` 10340, `mpr` 10360, `mlv` 10370,
+`eth` 10380, `lng` 10390. This is the Tilt *web UI* port, not a service port;
+each project owns its own service ports separately. The scaffold ships it blank
+on purpose, so there is nothing to collide with until you choose.
+
+The scaffold's `ctrl/k8s/` is the same shape as every other project here, and it
+builds as shipped:
+
+```
+kind-config.yaml       one node; gateway NodePort 30080 -> hostPort 8080
+base/                  namespace, configmap, app (Deployment + Service)
+overlays/dev/          promotes the app Service to NodePort 30080
+```
+
+Check it before `kind` spends minutes on anything — this renders the whole tree
+without a cluster and catches a broken patch immediately:
+
+```bash
+kubectl kustomize ctrl/k8s/overlays/dev
+```
+
+The workload is an nginx placeholder so a fresh copy reaches something that
+answers; replace it. Keep `30080` in step between the overlay patch and
+`kind-config.yaml`'s `containerPort` — the hostPort is this project's to pick.
+Reachability is a plain kind port mapping: no ingress controller and no MetalLB.
+Caddy maps `<slug>.local.ar` onto the host port (`~/wdir/ppl/local/Caddyfile`),
+with `*.local.ar` resolving to 127.0.0.1 through dnsmasq. That is the whole chain.
+
+**The one file the scaffold still does not ship is `ctrl/Tiltfile`** — `make
+tilt-up` runs `cd ctrl && tilt up`, and there is nothing to run until you write
+one. Copy it from a live project; `unt` and `nvi` are closest to the plain shape.
+
+
+## Run it
+
+```bash
+make kind-up      # idempotent create, then selects the context
+make tilt-up      # context + your assigned port
+```
+
+`tilt-up` passes `--context kind-<slug>` every time, which is the point of going
+through `make` at all: tilt cannot deploy into whichever cluster you last looked
+at.
+
+`make tilt-down` and `make kind-down` close the loop, and `make kind-reset` is
+delete-and-recreate for when a cluster wedges.
+
+
+## Register it
+
+The project exists; now it is findable. Add an entry to
+`~/wdir/all/projects/index.json` and write its `projects/<slug>.md` beside the
+others. Structured fields in the index, prose in the markdown.
+
+Putting it on the CI server and deploying it is `ppl`'s half, and it starts at
+`~/wdir/ppl/ctrl/init-repo.sh` — gitea remote, then Woodpecker. That is a
+different document.

rig/Makefile

@@ -0,0 +1,123 @@
+# Thin control Makefile — one target per ctrl/ script, and the subcommand is an
+# argument rather than a second target: `make cluster down`, not `make cluster-down`.
+#
+# The logic lives in the scripts, never here. Each target maps to exactly one
+# bash file, and that file holds the variants:
+#
+#   make cluster up      ->  ctrl/cluster.sh up
+#   make newbox destroy  ->  ctrl/newbox.sh destroy
+#
+# Config layers, weakest first: ctrl/versions.env (pinned toolchain) <
+# ctrl/env.d/<profile>.env (cluster shape) < ctrl/.env (local, gitignored) <
+# the environment. So `make cluster up PROFILE=client` beats everything.
+#
+# Start with:  make setup    (then: make cluster up && make docs)
+
+# Identity follows the FOLDER NAME, so this directory can be copied elsewhere,
+# renamed, and run as a separate environment with no edits. ctrl/.env overrides
+# it when you want a name that differs from the directory.
+SLUG      := $(shell echo '$(notdir $(CURDIR))' | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/^-*//; s/-*$$//')
+CLUSTER   := $(or $(shell sed -n 's/^CLUSTER=//p' ctrl/.env 2>/dev/null),$(SLUG))
+KCTX      := --context kind-$(CLUSTER)
+TILT_PORT := $(shell sed -n 's/^TILT_PORT=//p' ctrl/.env 2>/dev/null)
+WIZARD    := $(SLUG)-wizard
+
+# Words after the target become the script's subcommand. Make would otherwise
+# treat them as goals of their own, so each gets a no-op rule.
+ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+ifneq ($(ARGS),)
+$(eval $(ARGS):;@:)
+# ...and as PHONY, because some of those words name real directories. `cfg`,
+# `ctrl`, `docs`, `gen` and `init` all exist at this level, and make considers a
+# target that is an existing directory already built — so `make build ctrl` ran
+# the build and then printed "make: 'ctrl' is up to date". The empty rule above
+# is not enough on its own; only .PHONY stops make consulting the filesystem.
+.PHONY: $(ARGS)
+endif
+
+.PHONY: help setup station deps wizard cluster registry addons ports \
+        newbox dockerhost docs tilt \
+        kind-up kind-down kind-reset tilt-up tilt-down
+
+help:                          ## list targets
+	@grep -hE '^[a-z][a-z-]*:.*?##' $(MAKEFILE_LIST) | sed 's/:.*##/\t/' | expand -t16
+
+# ── setup ──────────────────────────────────────────────────────────────────
+
+setup:                         ## prepare this machine  [core] [--share-docker] [--cluster]
+	bash ctrl/setup.sh $(ARGS)
+
+station:                       ## is this workstation ready? reports, never fixes
+	bash ctrl/station.sh
+
+deps:                          ## install the toolchain  [core|dev]  (default dev)
+	bash ctrl/wizard.sh install $(or $(ARGS),dev)
+
+wizard:                        ## build the installer image  [full]
+	docker build -f ctrl/Dockerfile.wizard \
+	  --target $(if $(filter full,$(ARGS)),wizard-full,wizard) \
+	  -t $(WIZARD):$(if $(filter full,$(ARGS)),full,wizard) .
+
+# ── cluster ────────────────────────────────────────────────────────────────
+
+cluster:                       ## this env + the machine  [up|down|reset|list|free]
+	bash ctrl/cluster.sh $(or $(ARGS),up)
+
+registry:                      ## registry wiring  [up|down|status]    (default status)
+	bash ctrl/registry.sh $(or $(ARGS),status)
+
+addons:                        ## profile addons  [install|list]       (default list)
+	bash ctrl/addons.sh $(or $(ARGS),list)
+
+ports:                         ## this environment's port block  [show|persist]
+	bash ctrl/ports.sh $(or $(ARGS),show)
+
+# ── host ───────────────────────────────────────────────────────────────────
+
+newbox:                        ## throwaway environment  [create|status|shell|destroy]
+	bash ctrl/newbox.sh $(or $(ARGS),status)
+
+dockerhost:                    ## share Docker between distros  [status|share|unshare]
+	$(if $(filter share unshare,$(ARGS)),sudo ,)bash ctrl/dockerhost.sh $(or $(ARGS),status)
+
+# ── docs + dev loop ────────────────────────────────────────────────────────
+
+docs:                          ## documentation  [serve|graphs]        (default serve)
+	bash ctrl/docs.sh $(or $(ARGS),serve)
+
+# --port is only passed when TILT_PORT is actually set. It comes from ctrl/.env,
+# which does NOT carry it by default — ports are derived at runtime in
+# lib/config.sh unless `make ports persist` has written them. Without the guard
+# tilt receives a bare `--port` with no value and fails on the flag rather than
+# on anything real. `make ports show` prints the derived block.
+tilt:                          ## dev loop  [up|down]                  (default up)
+	cd ctrl && tilt $(or $(ARGS),up) $(KCTX) $(if $(filter down,$(ARGS)),,$(if $(TILT_PORT),--port $(TILT_PORT)))
+
+# ── the shape every other project uses ─────────────────────────────────────
+# Aliases, not a second implementation: each one calls the same script the
+# canonical target does.
+#
+# The header above argues for `make cluster down` over `make cluster-down`, and
+# that still holds *within* this file. But rig is one repo among several on the
+# same machine, and every other one answers to kind-up / tilt-up. Muscle memory
+# spanning six projects beats internal tidiness in one, so both spellings work.
+#
+# `cluster list` and `cluster free` have no hyphenated twin on purpose — they
+# are rig's own, with nothing to be consistent with.
+
+kind-up:                       ## alias for `cluster up`
+	bash ctrl/cluster.sh up
+
+kind-down:                     ## alias for `cluster down`
+	bash ctrl/cluster.sh down
+
+kind-reset:                    ## alias for `cluster reset`
+	bash ctrl/cluster.sh reset
+
+# These two match the other projects' spelling, but rig has no Tiltfile — there
+# is nothing to run yet, and they fail the same way `make tilt` does.
+tilt-up:                       ## alias for `tilt up`   (rig has no Tiltfile yet)
+	cd ctrl && tilt up $(KCTX) $(if $(TILT_PORT),--port $(TILT_PORT))
+
+tilt-down:                     ## alias for `tilt down` (rig has no Tiltfile yet)
+	cd ctrl && tilt down $(KCTX)

rig/README.md

@@ -0,0 +1,117 @@
+# rig
+
+A runnable local model of a large, regulated estate — legacy and new side by
+side. Its job is onboarding and exploration, not a production replica: most
+services are deliberately mocked, because what has to be faithful is the
+topology, not the workloads.
+
+## Prerequisite
+
+**Docker.** Nothing else — no curl, no jq, no python, no apt repositories.
+
+## Read the docs first
+
+```bash
+make docs      # serves on localhost, prints the URL
+```
+
+They run before anything is installed, which matters because they are the
+instructions for everything else. No cluster and no toolchain required.
+
+## Then
+
+```bash
+make station        # report host and config problems; changes nothing
+make deps          # install the toolchain (add `core` on a managed machine)
+make cluster up    # build the cluster for the active profile
+```
+
+`make help` lists every target.
+
+On a machine where Docker really is the only thing installed, `make deps` has
+nothing to download with — see [BOOTSTRAP.md](BOOTSTRAP.md), which runs the
+toolchain through the wizard container and carries on to scaffolding and running
+a new project.
+
+## One directory is one environment
+
+Copy this directory, rename it, run it. Cluster name, kubectl context, image
+tags and the host port block all derive from the directory name, so copies never
+collide and neither one's teardown can touch the other.
+
+rig lives inside soleprint, at `spr/rig` — it is soleprint's cluster half, and a
+copy is a **sibling**: `spr/acme-rig`. That is why the ignore rules for client
+rigs sit in `spr/.gitignore` rather than here; a rule in this directory cannot
+see a directory beside it.
+
+## Profiles
+
+A profile is the shape of the cluster: how many nodes, which addons, whether the
+apiserver audits. They live in `ctrl/env.d/`, and the active one is `PROFILE`.
+
+| Profile | For |
+| --- | --- |
+| `minimal` | the default. One node, no addons, boots fast. |
+| `client` | the regulated-estate shape — multi-node, audit on, registry mirror. |
+| `offline` | air-gapped: everything from a preloaded local registry. |
+| `data` | the dependency containers a soleprint room asks for. |
+
+```bash
+PROFILE=data make cluster up
+PROFILE=data make addons install
+make addons                       # what the active profile wants, and what exists
+```
+
+A profile names a **cluster shape** — a file in `ctrl/k8s/` — rather than
+restating node count and audit as variables:
+
+| shape | nodes | audit | used by |
+| --- | --- | --- | --- |
+| `kind-config.yaml.tpl` | 1 | off | `minimal`, `data` |
+| `kind-config.audit.yaml.tpl` | 1 | on | `offline` |
+| `kind-config.client.yaml.tpl` | 3 | on | `client` |
+
+Both numbers are read back out of the chosen file, so the YAML is the only place
+that decides and there is nothing to drift. The layout under `ctrl/k8s/` is the
+same as every other project here — a kind config, a kustomize `base/`, an
+`overlays/dev/` — see [`ctrl/k8s/README.md`](ctrl/k8s/README.md).
+
+## Addons
+
+Each addon is its own idempotent script in `ctrl/addons/`, and a profile names
+the ones it wants in `ADDONS`. Adding one is adding a file — there is no
+dispatcher to edit.
+
+**There is no ingress controller, deliberately.** They pin a narrow window of
+Kubernetes versions, so depending on one would constrain which k8s a rig can be
+built with — and running a trailing-edge control plane to model a legacy estate
+is the whole point. Services are reached through MetalLB and
+`type: LoadBalancer`, which carries no such constraint and is also what a real
+cluster does.
+
+| Addon | Does |
+| --- | --- |
+| `metallb` | gives `type: LoadBalancer` an address it can actually reach |
+| `cert-manager` | a local CA, so TLS works offline |
+| `metrics-server` | makes `kubectl top` work on kind |
+| `postgres` | database, in the `data` namespace |
+| `redis` | cache and broker |
+| `airflow` | scheduled pipelines; needs postgres and redis |
+
+The last three are the cluster half of **soleprint's cabinets**. A room declares
+what it needs once, in `cfg/<room>/data/cabinets.json`; soleprint's `build.py`
+composes those services into `docker-compose.yml` for a laptop, and these
+install the same ones here. The names match on purpose — each cabinet carries a
+`rig_addon` field pointing at `ctrl/addons/<name>.sh`.
+
+Plain manifests rather than helm charts, like every other addon: a chart repo is
+a network dependency, and the `offline` profile exists precisely so there is a
+path with none. Images are pinned in `ctrl/versions.env` and can be preloaded.
+
+Passwords are generated on first install and kept across re-runs, so re-running
+an addon never rotates a credential out from under something already connected:
+
+```bash
+kubectl -n data get secret postgres -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d
+kubectl -n data port-forward svc/airflow 8080:8080
+```

rig/ctrl/.env.example

@@ -0,0 +1,50 @@
+# Machine-local config. Copy to ctrl/.env (gitignored) and edit.
+# Cluster SHAPE lives in ctrl/env.d/<profile>.env — not here.
+# The architecture MODEL lives in arch/<name>.json — not here either.
+
+# Which profile in ctrl/env.d/ to build. minimal | client | offline
+PROFILE=minimal
+
+# Cluster name; the kubectl context becomes kind-<CLUSTER>.
+# LEAVE THIS UNSET unless you need a name that differs from the directory —
+# it defaults to this folder's name, which is what makes the folder copyable:
+# copy it, rename it, and you get a separate environment with no edits.
+# CLUSTER=
+
+# Host ports. LEAVE UNSET — they derive from the directory name so several
+# environments coexist without negotiating (see ctrl/ports.sh). `make ports`
+# shows this environment's block; `make ports persist` writes it here so it stops
+# being derived and becomes fixed. Set a value only to override.
+# HTTP_PORT=
+# HTTPS_PORT=
+# TILT_PORT=
+# REGISTRY_PORT=
+
+# Where the application manifests live. The real ones are expected to be
+# versioned separately from this installer — they change on a different cadence,
+# by different people. Repoint this at their repo and rig stops owning them:
+#   MANIFESTS_DIR=../platform-manifests/overlays/dev
+MANIFESTS_DIR=ctrl/k8s/overlays/dev
+
+# Where the wizard fetches the pinned binaries from.
+#   upstream    GitHub releases / dl.k8s.io  (needs internet)
+#   artifactory a generic repo — what a locked-down client usually allows
+#   baked       already inside the wizard image; no network at all
+DEPS_SOURCE=upstream
+DEPS_ARTIFACTORY_URL=
+
+# --- Registry -------------------------------------------------------------
+# Mode comes from the profile (REGISTRY_MODE). These are the secrets it needs.
+# Required for mirror/remote:
+REGISTRY_REMOTE_URL=
+REGISTRY_USER=
+REGISTRY_PASSWORD=
+
+# Corporate root CA, if Artifactory is fronted by an internal CA (it usually is).
+# Trust has to reach THREE places and nothing does it for you: the host docker
+# daemon, every kind node's containerd, and any in-cluster client. registry.sh
+# handles the first two; station.sh reports when it's configured but not trusted.
+# Symptom when missing: x509: certificate signed by unknown authority
+REGISTRY_CA_FILE=
+
+# (The local registry's host port is part of the derived block above.)

rig/ctrl/Dockerfile.wizard

@@ -0,0 +1,46 @@
+# The installation wizard. It does NOT run the cluster — it installs a toolchain
+# onto the host and gets out of the way.
+#
+# This exists to kill a bootstrap paradox: a plain bash installer needs curl, jq
+# and sha256sum to already be present, and a minimal Debian has none of them.
+# The wizard carries its own toolchain, so the only host prerequisite is Docker.
+#
+# Two variants from one file:
+#   docker build -f ctrl/Dockerfile.wizard --target wizard      -t <slug>-wizard        .
+#   docker build -f ctrl/Dockerfile.wizard --target wizard-full -t <slug>-wizard:full   .
+#
+# wizard-full bakes every pinned binary in at build time. `docker save` it and
+# you have the whole installer as one file to carry into an air-gapped network.
+
+FROM debian:trixie-slim AS wizard
+
+# ca-certificates + curl: fetch and verify. graphviz + python3: render diagrams
+# and validate the arch model, so the host never needs an apt package.
+#
+# docker-cli, NOT docker.io: we only ever talk to the host's daemon through the
+# mounted socket, and under --no-install-recommends the docker.io package ships
+# docker-init without the actual `docker` binary.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates curl jq graphviz python3 docker-cli \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work
+COPY ctrl/versions.env /work/ctrl/versions.env
+COPY ctrl/wizard.sh    /work/ctrl/wizard.sh
+RUN chmod +x /work/ctrl/wizard.sh
+
+# Defaults; every one is overridable with -e at run time.
+ENV DEPS_SOURCE=upstream \
+    OUT_BIN=/out/bin \
+    HOST_ROOT=/host
+
+ENTRYPOINT ["/work/ctrl/wizard.sh"]
+CMD ["install"]
+
+
+# ---------------------------------------------------------------------------
+# wizard-full — same wizard, binaries baked in, works with no network at all.
+FROM wizard AS wizard-full
+RUN /work/ctrl/wizard.sh fetch --to /opt/rig/bin
+ENV DEPS_SOURCE=baked \
+    BAKED_BIN=/opt/rig/bin

rig/ctrl/addons.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Install the addons the active profile asked for, in the order listed.
+# Each addon is its own idempotent script in ctrl/addons/ — adding one is adding
+# a file, not editing a dispatcher.
+#
+# Usage: addons.sh install | list
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+install() {
+    if [ -z "${ADDONS// /}" ]; then
+        echo "no addons in profile '$PROFILE_NAME'"
+        return
+    fi
+    local a
+    for a in $ADDONS; do
+        if [ ! -f "addons/${a}.sh" ]; then
+            echo "no such addon: addons/${a}.sh" >&2
+            exit 1
+        fi
+        echo "addon: $a"
+        bash "addons/${a}.sh"
+    done
+}
+
+list() {
+    echo "profile '$PROFILE_NAME' wants: ${ADDONS:-none}"
+    echo "available:"
+    ls addons/*.sh 2>/dev/null | xargs -n1 basename | sed 's/\.sh$//' | sed 's/^/  /'
+}
+
+case "${1:-list}" in
+    install) install ;;
+    list)    list ;;
+    *)       echo "usage: $0 [install|list]" >&2; exit 1 ;;
+esac

rig/ctrl/addons/airflow.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Apache Airflow — the cluster half of soleprint's airflow cabinet.
+#
+# Airflow needs a metadata database before it will start at all, so this refuses
+# rather than rolls a pod that will CrashLoopBackOff while the real problem
+# (postgres missing from ADDONS) stays invisible in the logs.
+#
+# One pod on `standalone`, matching the compose cabinet: migration, admin user,
+# scheduler and webserver in a single container. The official chart's five
+# deployments model an installation; a room switching this on wants pipelines.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+NS="${DATA_NAMESPACE:-data}"
+
+if ! $K get deployment -n "$NS" postgres >/dev/null 2>&1; then
+    echo "  ! airflow needs the postgres addon, and it is not installed" >&2
+    echo "    add it before airflow in the profile's ADDONS:" >&2
+    echo "      ADDONS=\"... postgres airflow\"" >&2
+    exit 1
+fi
+
+# Reuse the credential postgres generated rather than storing a second copy.
+db_user=$($K get secret -n "$NS" postgres -o jsonpath='{.data.POSTGRES_USER}' | base64 -d)
+db_pass=$($K get secret -n "$NS" postgres -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d)
+db_name=$($K get secret -n "$NS" postgres -o jsonpath='{.data.POSTGRES_DB}' | base64 -d)
+
+if $K get secret -n "$NS" airflow >/dev/null 2>&1; then
+    echo "  secret exists, keeping the current admin password and fernet key"
+else
+    admin_password=$(head -c 18 /dev/urandom | base64 | tr -d '/+=' | head -c 24)
+    # Airflow requires a 32-byte urlsafe-base64 key; without a fixed one every
+    # restart invalidates every stored connection.
+    fernet_key=$(head -c 32 /dev/urandom | base64 | tr '+/' '-_')
+    $K create secret generic airflow -n "$NS" \
+        --from-literal=ADMIN_USER="${AIRFLOW_ADMIN_USER:-admin}" \
+        --from-literal=ADMIN_PASSWORD="$admin_password" \
+        --from-literal=FERNET_KEY="$fernet_key" \
+        --from-literal=SQL_ALCHEMY_CONN="postgresql+psycopg2://${db_user}:${db_pass}@postgres:5432/${db_name}" \
+        >/dev/null
+    echo "  generated an admin password (read it back with the command below)"
+fi
+
+echo "  applying manifests"
+$K apply -n "$NS" -f - >/dev/null <<YAML
+apiVersion: v1
+kind: Service
+metadata:
+  name: airflow
+spec:
+  selector:
+    app: airflow
+  ports:
+    - port: 8080
+      targetPort: 8080
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: airflow
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: airflow
+  template:
+    metadata:
+      labels:
+        app: airflow
+    spec:
+      containers:
+        - name: airflow
+          image: ${AIRFLOW_IMAGE}
+          args: ["standalone"]
+          env:
+            - name: AIRFLOW__CORE__EXECUTOR
+              value: LocalExecutor
+            - name: AIRFLOW__CORE__LOAD_EXAMPLES
+              value: "false"
+            - name: AIRFLOW__DATABASE__SQL_ALCHEMY_CONN
+              valueFrom:
+                secretKeyRef: {name: airflow, key: SQL_ALCHEMY_CONN}
+            - name: AIRFLOW__CORE__FERNET_KEY
+              valueFrom:
+                secretKeyRef: {name: airflow, key: FERNET_KEY}
+            - name: _AIRFLOW_WWW_USER_USERNAME
+              valueFrom:
+                secretKeyRef: {name: airflow, key: ADMIN_USER}
+            - name: _AIRFLOW_WWW_USER_PASSWORD
+              valueFrom:
+                secretKeyRef: {name: airflow, key: ADMIN_PASSWORD}
+          ports:
+            - containerPort: 8080
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+            # First boot runs the whole migration before it serves anything.
+            initialDelaySeconds: 60
+            periodSeconds: 15
+            failureThreshold: 20
+YAML
+
+echo "  waiting for airflow (the first boot migrates the database, so this is slow)..."
+$K rollout status deployment/airflow -n "$NS" --timeout=600s
+
+echo "  in-cluster: http://airflow.${NS}.svc.cluster.local:8080"
+echo "  reach it:   kubectl --context ${KUBECONTEXT} -n ${NS} port-forward svc/airflow 8080:8080"
+echo "  password:   kubectl --context ${KUBECONTEXT} -n ${NS} get secret airflow -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d"

rig/ctrl/addons/cert-manager.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# cert-manager plus a self-signed cluster issuer.
+#
+# In a regulated estate almost everything is TLS, so the interesting question
+# during onboarding is "does this service present a cert my client trusts" — not
+# "can I reach a public ACME server". A local CA answers that offline, which is
+# also what makes the air-gapped profile usable.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+
+if $K get deployment -n cert-manager cert-manager >/dev/null 2>&1; then
+    echo "  already installed"
+else
+    $K apply -f "https://github.com/cert-manager/cert-manager/releases/download/${CERT_MANAGER_VERSION}/cert-manager.yaml"
+fi
+
+echo "  waiting for cert-manager..."
+$K wait --namespace cert-manager \
+    --for=condition=ready pod --selector=app.kubernetes.io/instance=cert-manager \
+    --timeout=240s
+
+# A self-signed root, then a CA issuer chained off it. Workloads reference
+# ClusterIssuer/local-ca and get a cert from a CA you can actually distribute.
+echo "  creating local CA issuer"
+$K apply -f - <<'YAML' >/dev/null
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: selfsigned-root
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: local-ca
+  namespace: cert-manager
+spec:
+  isCA: true
+  commonName: rig-local-ca
+  secretName: local-ca-key-pair
+  duration: 87600h
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  issuerRef:
+    name: selfsigned-root
+    kind: ClusterIssuer
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: local-ca
+spec:
+  ca:
+    secretName: local-ca-key-pair
+YAML
+
+echo "  export the CA for your browser/client with:"
+echo "    kubectl --context ${KUBECONTEXT} -n cert-manager get secret local-ca-key-pair -o jsonpath='{.data.tls\\.crt}' | base64 -d"

rig/ctrl/addons/metallb.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# MetalLB — makes `Service type: LoadBalancer` actually get an address.
+#
+# Why it matters here: real manifests use LoadBalancer, because a real cluster
+# has one. On a bare kind cluster those Services sit at EXTERNAL-IP <pending>
+# forever with no error anywhere — the deployment looks fine and simply is not
+# reachable. Without this, every such Service has to be edited to NodePort,
+# which means the local manifests stop matching the ones being modelled.
+#
+# The address pool is derived from the kind Docker network at install time, not
+# hardcoded: Docker picks that subnet, it differs between machines, and a pool
+# outside it is silently unroutable.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+
+# ── work out an address range ──────────────────────────────────────────────
+# kind hands node addresses out from the bottom of the subnet, so the top is
+# free. Taking a slice there avoids collisions with current and future nodes.
+subnet=$(docker network inspect kind \
+         -f '{{range .IPAM.Config}}{{.Subnet}} {{end}}' 2>/dev/null \
+         | tr ' ' '\n' | grep -E '^[0-9]+\.' | head -1)
+
+if [ -z "$subnet" ]; then
+    echo "  ! could not read the kind Docker network subnet" >&2
+    echo "    (is the cluster up? MetalLB needs the network to exist first)" >&2
+    exit 1
+fi
+
+base="${subnet%/*}"; prefix="${subnet#*/}"
+o1=$(echo "$base" | cut -d. -f1); o2=$(echo "$base" | cut -d. -f2)
+o3=$(echo "$base" | cut -d. -f3)
+
+case "$prefix" in
+    16) pool_start="${o1}.${o2}.255.200"; pool_end="${o1}.${o2}.255.250" ;;
+    24) pool_start="${o1}.${o2}.${o3}.200"; pool_end="${o1}.${o2}.${o3}.250" ;;
+    *)
+        # Guessing a range inside an unexpected prefix risks handing out
+        # addresses that belong to something else. Say so instead.
+        echo "  ! kind network is $subnet — only /16 and /24 are handled" >&2
+        echo "    set the pool by hand in ctrl/addons/metallb.sh" >&2
+        exit 1
+        ;;
+esac
+
+echo "  kind network $subnet → pool ${pool_start}-${pool_end}"
+
+# ── install ────────────────────────────────────────────────────────────────
+
+if $K get deployment -n metallb-system controller >/dev/null 2>&1; then
+    echo "  already installed"
+else
+    $K apply -f "https://raw.githubusercontent.com/metallb/metallb/${METALLB_VERSION}/config/manifests/metallb-native.yaml"
+fi
+
+# `kubectl wait` on a selector errors out immediately when nothing matches yet,
+# and right after apply the ReplicaSet has not created the pod — so it loses a
+# race it looks like it should win. `rollout status` waits for the Deployment
+# itself and handles the not-yet-created case.
+echo "  waiting for the controller..."
+$K rollout status deployment/controller -n metallb-system --timeout=240s
+$K rollout status daemonset/speaker -n metallb-system --timeout=240s
+
+# The webhook rejects IPAddressPools until it is actually serving, and it comes
+# up a moment after the pod is Ready — so retry rather than fail the whole run
+# on a race that resolves itself in seconds.
+echo "  configuring the address pool"
+for attempt in 1 2 3 4 5 6 7 8 9 10; do
+    if $K apply -f - >/dev/null 2>&1 <<YAML
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: default
+  namespace: metallb-system
+spec:
+  addresses:
+    - ${pool_start}-${pool_end}
+---
+# Layer 2 mode: one node answers ARP for each address. No BGP peer needed, which
+# is what makes this work on a laptop.
+apiVersion: metallb.io/v1beta1
+kind: L2Advertisement
+metadata:
+  name: default
+  namespace: metallb-system
+spec:
+  ipAddressPools:
+    - default
+YAML
+    then
+        echo "  pool ready: ${pool_start}-${pool_end}"
+        exit 0
+    fi
+    sleep 3
+done
+
+echo "  ! the pool was rejected after 10 attempts — is the webhook up?" >&2
+$K get pods -n metallb-system >&2
+exit 1

rig/ctrl/addons/metrics-server.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# metrics-server — makes `kubectl top` work.
+#
+# kind nodes serve kubelet metrics over a self-signed cert, so the standard
+# manifest never becomes ready without --kubelet-insecure-tls. That is fine here
+# (it is a local cluster) and is the single most common reason metrics-server
+# sits at 0/1 on kind.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+
+if ! $K get deployment -n kube-system metrics-server >/dev/null 2>&1; then
+    $K apply -f "https://github.com/kubernetes-sigs/metrics-server/releases/download/${METRICS_SERVER_VERSION}/components.yaml"
+fi
+
+$K patch deployment metrics-server -n kube-system --type=json \
+    -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]' \
+    >/dev/null 2>&1 || true
+
+echo "  waiting for metrics-server..."
+$K rollout status deployment/metrics-server -n kube-system --timeout=180s

rig/ctrl/addons/postgres.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# PostgreSQL — the cluster half of soleprint's postgres cabinet.
+#
+# A room declares the dependency once, in cfg/<room>/data/cabinets.json. On a
+# laptop `build.py` composes it into docker-compose.yml; here it becomes a pod,
+# so the same declaration works either way and nothing has to be remembered
+# twice.
+#
+# Plain manifests rather than a helm chart, matching the other addons: a chart
+# repo is a network dependency, and the offline profile exists precisely so
+# there is a path with none. The image is pinned in ctrl/versions.env and can be
+# preloaded into a local registry like every other image here.
+#
+# One replica on a PVC. This models a dependency for local work, not a
+# highly-available database, and pretending otherwise on a kind node would be a
+# more elaborate lie rather than a more useful one.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+NS="${DATA_NAMESPACE:-data}"
+
+$K get namespace "$NS" >/dev/null 2>&1 || $K create namespace "$NS"
+
+# The password is generated once and then left alone, so re-running this does
+# not rotate the credential out from under whatever is already connected.
+if $K get secret -n "$NS" postgres >/dev/null 2>&1; then
+    echo "  secret exists, keeping the current password"
+else
+    password=$(head -c 18 /dev/urandom | base64 | tr -d '/+=' | head -c 24)
+    $K create secret generic postgres -n "$NS" \
+        --from-literal=POSTGRES_DB="${POSTGRES_DB:-soleprint}" \
+        --from-literal=POSTGRES_USER="${POSTGRES_USER:-soleprint}" \
+        --from-literal=POSTGRES_PASSWORD="$password" >/dev/null
+    echo "  generated a password (read it back with the command printed below)"
+fi
+
+echo "  applying manifests"
+$K apply -n "$NS" -f - >/dev/null <<YAML
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: postgres-data
+spec:
+  accessModes: [ReadWriteOnce]
+  resources:
+    requests:
+      storage: ${POSTGRES_STORAGE:-2Gi}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+spec:
+  selector:
+    app: postgres
+  ports:
+    - port: 5432
+      targetPort: 5432
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: postgres
+spec:
+  replicas: 1
+  # One volume, one writer. Rolling would start a second pod against the same
+  # PVC before the first exits, and Postgres refuses to share a data directory.
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: postgres
+  template:
+    metadata:
+      labels:
+        app: postgres
+    spec:
+      containers:
+        - name: postgres
+          image: ${POSTGRES_IMAGE}
+          envFrom:
+            - secretRef:
+                name: postgres
+          env:
+            # The image initialises into the volume root otherwise, and a
+            # lost+found from the PVC makes it refuse to initdb.
+            - name: PGDATA
+              value: /var/lib/postgresql/data/pgdata
+          ports:
+            - containerPort: 5432
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
+          readinessProbe:
+            exec:
+              command: ["sh", "-c", "pg_isready -U \$POSTGRES_USER -d \$POSTGRES_DB"]
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          livenessProbe:
+            exec:
+              command: ["sh", "-c", "pg_isready -U \$POSTGRES_USER -d \$POSTGRES_DB"]
+            initialDelaySeconds: 30
+            periodSeconds: 15
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: postgres-data
+YAML
+
+echo "  waiting for postgres..."
+$K rollout status deployment/postgres -n "$NS" --timeout=240s
+
+echo "  in-cluster: postgres.${NS}.svc.cluster.local:5432"
+echo "  password:   kubectl --context ${KUBECONTEXT} -n ${NS} get secret postgres -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d"

rig/ctrl/addons/redis.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Redis — the cluster half of soleprint's redis cabinet.
+#
+# Cache, and the broker anything queue-shaped runs on. No persistence: a broker
+# that loses its queue on restart is the honest local model, and a PVC here buys
+# nothing but a volume to clean up.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+source ./lib/config.sh
+load_config
+
+K="kubectl --context ${KUBECONTEXT}"
+NS="${DATA_NAMESPACE:-data}"
+
+$K get namespace "$NS" >/dev/null 2>&1 || $K create namespace "$NS"
+
+echo "  applying manifests"
+$K apply -n "$NS" -f - >/dev/null <<YAML
+apiVersion: v1
+kind: Service
+metadata:
+  name: redis
+spec:
+  selector:
+    app: redis
+  ports:
+    - port: 6379
+      targetPort: 6379
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: redis
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: redis
+  template:
+    metadata:
+      labels:
+        app: redis
+    spec:
+      containers:
+        - name: redis
+          image: ${REDIS_IMAGE}
+          ports:
+            - containerPort: 6379
+          readinessProbe:
+            exec:
+              command: ["redis-cli", "ping"]
+            initialDelaySeconds: 3
+            periodSeconds: 5
+YAML
+
+echo "  waiting for redis..."
+$K rollout status deployment/redis -n "$NS" --timeout=180s
+
+echo "  in-cluster: redis://redis.${NS}.svc.cluster.local:6379/0"

rig/ctrl/cluster.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Cluster lifecycle, plus what else is running on this machine.
+#
+# `list` and `free` live here rather than in a separate script because a
+# near-identical second name (cluster / clusters) is a trap — you reach for one
+# and get the other. One target, one file, unambiguous subcommands.
+#
+# "Idempotent" here means CONVERGENT, not "exits early if the cluster exists".
+# That distinction matters: an interrupted first run can leave a cluster created
+# but not finished, and returning early on the re-run would strand it there.
+# The create step is conditional; every step after it always runs, and each one
+# is individually idempotent.
+#
+# Usage: cluster.sh up | down | reset | list | free
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+up() {
+    if kind get clusters 2>/dev/null | grep -qx "$CLUSTER"; then
+        echo "cluster '$CLUSTER' exists — converging"
+    else
+        # Say what this profile locks in BEFORE spending minutes building it:
+        # the audit policy is an apiserver flag and cannot be changed later.
+        echo "creating cluster '$CLUSTER' from profile '$PROFILE_NAME'"
+        echo "  shape       ctrl/k8s/$KIND_CONFIG"
+        echo "  nodes       $NODES"
+        echo "  image       $NODE_IMAGE"
+        echo "  audit       $AUDIT"
+        echo "  ingress     $INGRESS_MODE"
+        echo "  registry    $REGISTRY_MODE"
+        echo "  (audit is fixed at creation — 'make cluster reset' to change it)"
+        echo
+
+        render_kind_config | kind create cluster --config -
+    fi
+
+    # The cluster can exist while its context does not — a reset or a switched
+    # KUBECONFIG loses it, and then nothing works despite a healthy cluster.
+    if ! kubectl config get-contexts -o name 2>/dev/null | grep -qx "$KUBECONTEXT"; then
+        echo "context '$KUBECONTEXT' missing from kubeconfig — re-exporting"
+        kind export kubeconfig --name "$CLUSTER"
+    fi
+    kubectl config use-context "$KUBECONTEXT" >/dev/null
+
+    bash registry.sh up
+
+    if [ -n "${ADDONS// /}" ]; then
+        bash addons.sh install
+    fi
+
+    echo
+    echo "cluster '$CLUSTER' ready (context $KUBECONTEXT)"
+}
+
+down() {
+    # The registry is a standalone container outside the cluster; take it down
+    # first so a reset doesn't leave it orphaned and holding a port.
+    bash registry.sh down || true
+
+    if kind get clusters 2>/dev/null | grep -qx "$CLUSTER"; then
+        echo "deleting cluster '$CLUSTER'..."
+        kind delete cluster --name "$CLUSTER"
+    else
+        echo "no cluster '$CLUSTER' to delete"
+    fi
+}
+
+# The escape hatch for a wedged cluster, and the only way to change a
+# creation-time setting such as the audit policy.
+reset() {
+    down
+    echo
+    up
+}
+
+# ── the whole machine ──────────────────────────────────────────────────────
+# Every cluster is a running container tree whether or not you are using it, and
+# an idle one is the usual reason a new one will not fit.
+
+list() {
+    local total avail
+    total=$(awk '/^MemTotal:/{printf "%.1f", $2/1024/1024}' /proc/meminfo)
+    avail=$(awk '/^MemAvailable:/{printf "%.1f", $2/1024/1024}' /proc/meminfo)
+    echo "memory: ${avail} GB available of ${total} GB"
+    echo
+
+    local names; names=$(kind get clusters 2>/dev/null || true)
+    if [ -z "$names" ]; then
+        echo "no clusters"
+        return
+    fi
+
+    printf "%-16s %-10s %8s %6s  %-13s %s\n" CLUSTER STATE MEM NODES PORTS ""
+    local c nodes state mem base
+    for c in $names; do
+        nodes=$(docker ps -a --filter "label=io.x-k8s.kind.cluster=$c" --format '{{.Names}}' | wc -l)
+        state=$(docker inspect -f '{{.State.Status}}' "${c}-control-plane" 2>/dev/null || echo unknown)
+        if [ "$state" = "running" ]; then
+            mem=$(docker stats --no-stream --format '{{.MemUsage}}' \
+                  $(docker ps --filter "label=io.x-k8s.kind.cluster=$c" -q) 2>/dev/null \
+                  | awk '{gsub(/GiB/,"");gsub(/MiB/,"e-3");s+=$1} END {printf "%.1fG", s}')
+        else
+            mem="-"
+        fi
+        # A cluster's name is its directory slug, so its port block is derivable
+        # here without reading that directory's config.
+        base=$(derive_port_base "$c")
+        printf "%-16s %-10s %8s %6s  %-13s %s\n" "$c" "$state" "$mem" "$nodes" \
+            "${base}-$((base + 3))" \
+            "$([ "$c" = "$CLUSTER" ] && echo "<- this one")"
+    done
+}
+
+# Stop the OTHER clusters to free memory. Stops, never deletes — a stopped
+# cluster restarts with `docker start`, so nothing is lost.
+free() {
+    local targets=("$@")
+    if [ ${#targets[@]} -eq 0 ]; then
+        mapfile -t targets < <(kind get clusters 2>/dev/null | grep -vx "$CLUSTER" || true)
+    fi
+    if [ ${#targets[@]} -eq 0 ]; then
+        echo "nothing to stop"
+        return
+    fi
+
+    local c ids
+    for c in "${targets[@]}"; do
+        ids=$(docker ps --filter "label=io.x-k8s.kind.cluster=$c" -q)
+        if [ -z "$ids" ]; then
+            echo "cluster '$c' is not running"
+            continue
+        fi
+        echo "stopping '$c' (restart with: docker start \$(docker ps -aq -f label=io.x-k8s.kind.cluster=$c))"
+        # shellcheck disable=SC2086
+        docker stop $ids >/dev/null
+    done
+}
+
+case "${1:-up}" in
+    up)    up ;;
+    down)  down ;;
+    reset) reset ;;
+    list)  list ;;
+    free)  shift; free "$@" ;;
+    *)     echo "usage: $0 [up|down|reset|list|free]" >&2; exit 1 ;;
+esac

rig/ctrl/dockerhost.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# Share ONE Docker daemon across WSL distros, instead of running one per distro.
+#
+# Why this exists
+# ---------------
+# WSL2 distros share a kernel and a network stack. Two dockerd instances then
+# contend over docker0 and iptables, which can disturb the daemon you actually
+# depend on. Docker Desktop avoids this by running a single daemon in a
+# dedicated distro and sharing its socket — this is the same idea, without
+# Docker Desktop.
+#
+# So a throwaway rig box does NOT install Docker. It borrows the daemon from
+# whichever distro is the designated host. That also makes the test more honest:
+# rig never installs Docker anyway — Docker is its documented prerequisite.
+#
+# How
+# ---
+# /mnt/wsl is a tmpfs with `shared` mount propagation, visible to every distro
+# in the WSL VM. The owning distro exposes its socket there; guests point
+# DOCKER_HOST at it. Two ways, with different costs:
+#
+#   share              bind-mount the existing socket onto the shared tmpfs.
+#                      Instant, and dockerd is NEVER restarted. Lasts until the
+#                      next WSL shutdown.
+#   share --persist    additionally install a systemd drop-in so dockerd listens
+#                      there itself. Survives restarts, but requires one Docker
+#                      restart now — which stops every container that has no
+#                      restart policy, since live-restore is off by default.
+#
+# The bind mount is the default precisely because the persistent version's cost
+# is paid on a machine that is already working.
+#
+# Reversibility is the whole design
+# ---------------------------------
+# `unshare` removes the bind mount (no restart) and, if present, the drop-in.
+# The original systemd unit is never edited — only an additive drop-in file is
+# ever created — so undoing is deletion, not repair. `status` always states
+# which of the three roles a distro is in, in those words.
+#
+# Nothing here runs automatically. It does nothing until invoked.
+#
+# Usage:
+#   dockerhost.sh status              # which distro owns Docker; what this one uses
+#   dockerhost.sh share               # share it (bind mount, no daemon restart)
+#   dockerhost.sh share --persist     # ...and survive WSL restarts (restarts Docker)
+#   dockerhost.sh unshare             # undo it; this distro owns its Docker again
+#   dockerhost.sh use [--persist]     # point THIS distro at the shared socket
+set -euo pipefail
+
+SHARED_DIR=/mnt/wsl/shared-docker
+SHARED_SOCK="$SHARED_DIR/docker.sock"
+OWNER_FILE="$SHARED_DIR/OWNER"
+DROPIN=/etc/systemd/system/docker.service.d/10-rig-shared-socket.conf
+PROFILE_D=/etc/profile.d/rig-docker-host.sh
+
+distro_name() { echo "${WSL_DISTRO_NAME:-$(hostname)}"; }
+
+require_wsl() {
+    grep -qi microsoft /proc/version 2>/dev/null && return 0
+    echo "dockerhost is WSL-only: it relies on /mnt/wsl being shared between distros." >&2
+    exit 1
+}
+
+# ── status ─────────────────────────────────────────────────────────────────
+
+status() {
+    require_wsl
+    echo "distro       $(distro_name)"
+
+    if [ -f "$DROPIN" ] || mountpoint -q "$SHARED_SOCK" 2>/dev/null; then
+        echo "role         SHARING — this distro's Docker is offered to other distros"
+    elif [ -n "${DOCKER_HOST:-}" ] && [ "${DOCKER_HOST}" = "unix://$SHARED_SOCK" ]; then
+        echo "role         BORROWING — using another distro's Docker"
+    else
+        echo "role         standalone — this WSL installation has the main host Docker"
+    fi
+
+    echo
+    if [ -S "$SHARED_SOCK" ]; then
+        echo "shared sock  $SHARED_SOCK (present)"
+        [ -f "$OWNER_FILE" ] && sed 's/^/  /' "$OWNER_FILE"
+    else
+        echo "shared sock  none — no distro is sharing right now"
+    fi
+
+    echo
+    echo "DOCKER_HOST  ${DOCKER_HOST:-(unset — using /var/run/docker.sock)}"
+    if command -v docker >/dev/null 2>&1; then
+        echo "docker       $(docker version --format '{{.Server.Version}}' 2>/dev/null || echo unreachable)"
+    else
+        echo "docker       cli not installed"
+    fi
+}
+
+# ── share / unshare (run on the host distro) ───────────────────────────────
+
+# Default: expose the EXISTING socket by bind-mounting it onto the shared tmpfs.
+# /mnt/wsl has `shared` propagation, so the mount is visible in other distros.
+#
+# The point of doing it this way is that dockerd is never restarted. Restarting
+# it stops every container that has no restart policy (live-restore is off by
+# default), which on a working machine means quietly killing whatever you had
+# running. Not a trade worth making just to expose a socket.
+#
+# Cost: a bind mount does not survive a WSL VM shutdown. `--persist` adds the
+# systemd drop-in as well, which does survive but needs that one restart.
+share_bind() {
+    mkdir -p "$SHARED_DIR"
+    chmod 0755 "$SHARED_DIR"
+
+    if mountpoint -q "$SHARED_SOCK" 2>/dev/null; then
+        echo "already bind-mounted at $SHARED_SOCK"
+    else
+        [ -S /var/run/docker.sock ] || { echo "no /var/run/docker.sock here" >&2; exit 1; }
+        # The target must exist as a file for a bind mount onto it.
+        [ -e "$SHARED_SOCK" ] || : > "$SHARED_SOCK"
+        mount --bind /var/run/docker.sock "$SHARED_SOCK"
+        echo "bind-mounted /var/run/docker.sock -> $SHARED_SOCK (no daemon restart)"
+    fi
+
+    cat > "$OWNER_FILE" <<EOF
+owner distro: $(distro_name)
+docker gid:   $(getent group docker | cut -d: -f3)
+socket:       $SHARED_SOCK
+method:       bind-mount (until the next WSL shutdown)
+EOF
+}
+
+share() {
+    require_wsl
+    [ "$(id -u)" -eq 0 ] || { echo "run with sudo: sudo bash ctrl/dockerhost.sh share" >&2; exit 1; }
+
+    share_bind
+
+    if [ "${1:-}" != "--persist" ]; then
+        echo
+        echo "This lasts until the next WSL shutdown. To make it survive, re-run with"
+        echo "--persist — but note that adds a systemd drop-in and RESTARTS Docker,"
+        echo "which stops any container that has no restart policy."
+        return 0
+    fi
+
+    if [ -f "$DROPIN" ]; then
+        echo "drop-in already present — sharing persists across restarts."
+        return 0
+    fi
+
+    echo
+    echo "--persist: installing a systemd drop-in and restarting Docker."
+    echo "Containers without a restart policy will stop and will NOT come back."
+    docker ps --format '  {{.Names}}  restart={{.HostConfig.RestartPolicy.Name}}' 2>/dev/null \
+        || docker ps --format '  {{.Names}}' 2>/dev/null || true
+    echo
+
+    local exec_line
+    exec_line=$(systemctl cat docker.service | grep -m1 '^ExecStart=')
+    if [ -z "$exec_line" ]; then
+        echo "could not read docker.service ExecStart — refusing to guess" >&2
+        exit 1
+    fi
+
+    mkdir -p "$(dirname "$DROPIN")" "$SHARED_DIR"
+    # Additive only: blank the inherited ExecStart, then restate it verbatim
+    # with one extra -H. Nothing about the original unit is edited.
+    cat > "$DROPIN" <<EOF
+# Added by rig (ctrl/dockerhost.sh share).
+#
+# Adds a SECOND listening socket on the WSL-shared tmpfs so other distros can
+# use this daemon instead of running their own. The original socket is
+# untouched, so this distro behaves exactly as before.
+#
+# To undo:  sudo bash ctrl/dockerhost.sh unshare
+[Service]
+ExecStartPre=-/bin/mkdir -p $SHARED_DIR
+ExecStartPre=-/bin/chmod 0755 $SHARED_DIR
+ExecStart=
+${exec_line} -H unix://$SHARED_SOCK
+EOF
+
+    systemctl daemon-reload
+    systemctl restart docker
+
+    # Guests need a group with a MATCHING GID to use the socket; GIDs are not
+    # consistent across distros, so record ours rather than assume.
+    cat > "$OWNER_FILE" <<EOF
+owner distro: $(distro_name)
+docker gid:   $(getent group docker | cut -d: -f3)
+socket:       $SHARED_SOCK
+EOF
+
+    echo "sharing from '$(distro_name)'"
+    echo "  guests: export DOCKER_HOST=unix://$SHARED_SOCK"
+    echo "  undo:   sudo bash ctrl/dockerhost.sh unshare"
+    echo
+    echo "NOTE: /mnt/wsl is tmpfs and is cleared when the WSL VM shuts down."
+    echo "      The drop-in recreates the directory on the next Docker start."
+}
+
+unshare_() {
+    require_wsl
+    [ "$(id -u)" -eq 0 ] || { echo "run with sudo: sudo bash ctrl/dockerhost.sh unshare" >&2; exit 1; }
+
+    local did=0
+
+    # The bind mount first: undoing it needs no restart, so a plain `share`
+    # is fully reversible without disturbing anything.
+    if mountpoint -q "$SHARED_SOCK" 2>/dev/null; then
+        umount "$SHARED_SOCK"
+        rm -f "$SHARED_SOCK"
+        echo "  removed the bind mount (no restart needed)"
+        did=1
+    fi
+    rm -f "$OWNER_FILE"
+    rmdir "$SHARED_DIR" 2>/dev/null || true
+
+    if [ -f "$DROPIN" ]; then
+        rm -f "$DROPIN"
+        rmdir "$(dirname "$DROPIN")" 2>/dev/null || true
+        systemctl daemon-reload
+        systemctl restart docker
+        echo "  removed the systemd drop-in and restarted Docker"
+        did=1
+    fi
+
+    if [ "$did" -eq 0 ]; then
+        echo "not sharing — this WSL installation already has the main host Docker."
+        return 0
+    fi
+
+    echo "restored: this WSL installation has the main host Docker again."
+    echo "  (nothing else was changed; the original unit was never edited)"
+}
+
+# ── use (run on a guest distro) ────────────────────────────────────────────
+
+use() {
+    require_wsl
+    if [ ! -S "$SHARED_SOCK" ]; then
+        echo "no shared socket at $SHARED_SOCK" >&2
+        echo "Run 'sudo bash ctrl/dockerhost.sh share' in the distro that owns Docker." >&2
+        exit 1
+    fi
+
+    # Align the local docker group GID with the owner's, or the socket is
+    # unreadable here even though it is visible.
+    if [ -f "$OWNER_FILE" ] && [ "$(id -u)" -eq 0 ]; then
+        local gid; gid=$(awk '/docker gid:/ {print $3}' "$OWNER_FILE")
+        if [ -n "$gid" ]; then
+            if getent group docker >/dev/null; then
+                [ "$(getent group docker | cut -d: -f3)" = "$gid" ] || groupmod -g "$gid" docker
+            else
+                groupadd -g "$gid" docker
+            fi
+        fi
+    fi
+
+    if [ "${1:-}" = "--persist" ]; then
+        [ "$(id -u)" -eq 0 ] || { echo "--persist needs root" >&2; exit 1; }
+        echo "export DOCKER_HOST=unix://$SHARED_SOCK" > "$PROFILE_D"
+        echo "persisted in $PROFILE_D"
+    fi
+
+    echo "export DOCKER_HOST=unix://$SHARED_SOCK"
+}
+
+case "${1:-status}" in
+    status)  status ;;
+    share)   shift; share "${1:-}" ;;
+    unshare) unshare_ ;;
+    use)     shift; use "${1:-}" ;;
+    *)       echo "usage: $0 [status|share|unshare|use [--persist]]" >&2; exit 1 ;;
+esac

rig/ctrl/docs.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Documentation: render the diagrams, and serve the pages.
+#
+# The docs are the instructions for building the cluster, so they must work
+# BEFORE anything else exists. That rules out serving them from the cluster, and
+# it rules out python -m http.server too — a minimal Debian has no python3. What
+# it does have, by definition, is Docker: the single prerequisite rig already
+# demands. So a throwaway nginx container serves a read-only bind mount.
+#
+# Rendered SVGs are committed alongside their .dot sources for the same reason:
+# the pages have to read on a machine with no Graphviz installed.
+#
+# Usage: docs.sh serve | graphs
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+REPO="$(cd .. && pwd)"
+DOCS_PORT="${DOCS_PORT:-$((HTTP_PORT + 4))}"   # +4 sits inside this env's block
+
+serve() {
+    if [ ! -f "$REPO/docs/index.html" ]; then
+        echo "no docs/index.html" >&2
+        exit 1
+    fi
+    echo "docs for '$CLUSTER' on http://localhost:${DOCS_PORT}"
+    echo "  (ctrl-c to stop; nothing is installed and nothing persists)"
+    docker run --rm \
+        --name "${CLUSTER}-docs" \
+        -p "${DOCS_PORT}:80" \
+        -v "$REPO/docs:/usr/share/nginx/html:ro" \
+        nginx:alpine
+}
+
+graphs() {
+    if ! command -v dot >/dev/null 2>&1; then
+        echo "graphviz not found — install with: sudo apt install graphviz" >&2
+        echo "(only needed to re-render; the committed .svg files already work)" >&2
+        exit 1
+    fi
+    shopt -s nullglob
+    local found=0 f out
+    for f in "$REPO"/docs/graphs/*.dot; do
+        out="${f%.dot}.svg"
+        echo "  graphviz $(basename "$f") → $(basename "$out")"
+        dot -Tsvg "$f" -o "$out"
+        found=1
+    done
+    [ "$found" -eq 1 ] || echo "  no .dot files in docs/graphs/"
+}
+
+case "${1:-serve}" in
+    serve)  serve ;;
+    graphs) graphs ;;
+    *)      echo "usage: $0 [serve|graphs]" >&2; exit 1 ;;
+esac

rig/ctrl/env.d/client.env

@@ -0,0 +1,30 @@
+# client — the regulated-estate shape. Multi-node so taints, affinity and
+# topology are real; apiserver audit on; images through a pull-through cache of
+# the corporate registry.
+#
+# Costs roughly 4-6 GB. Check `make cluster list` before starting this alongside
+# other work — see the memory note in the README.
+
+PROFILE_NAME=client
+K8S_VERSION=v1_36
+KIND_CONFIG=kind-config.client.yaml.tpl
+ADDONS="metallb cert-manager metrics-server"
+REGISTRY_MODE=mirror
+INGRESS_MODE=hostport
+DNS_MODE=hosts
+
+# Ports derive from the directory name by default (see ctrl/ports.sh), so
+# several environments run side by side.
+#
+# Opt in to the real ports below only when this is the ONLY environment and
+# nothing else owns :80. They fail to bind otherwise, and docker reports it as an
+# opaque "failed to bind host port 0.0.0.0:80/tcp: address already in use"
+# halfway through cluster creation. `make station` checks before you spend the
+# time. Uncommenting also means only one environment can exist at a time.
+# HTTP_PORT=80
+# HTTPS_PORT=443
+
+# Set these in ctrl/.env (gitignored), not here:
+#   REGISTRY_REMOTE_URL=https://artifactory.corp.example/artifactory/api/docker/docker-virtual
+#   REGISTRY_USER / REGISTRY_PASSWORD
+#   REGISTRY_CA_FILE=/path/to/corp-root-ca.crt

rig/ctrl/env.d/data.env

@@ -0,0 +1,42 @@
+# data — a cluster with the dependency containers a soleprint room asks for.
+#
+# The point of this profile is that a room declares what it needs once, in
+# cfg/<room>/data/cabinets.json, and gets it on either target: `build.py`
+# composes those services into docker-compose.yml for a laptop, and the addons
+# below install the same ones here. The names match deliberately —
+# soleprint/station/cabinets/<name>/cabinet.json carries a `rig_addon` field
+# pointing at ctrl/addons/<name>.sh.
+#
+# Everything lands in the `data` namespace (DATA_NAMESPACE to move it), so
+# `make cluster reset` on the app namespace leaves the databases alone.
+#
+# Costs roughly 2-3 GB with airflow, under 1 without. Airflow's first boot runs
+# the whole metadata migration, so expect a few minutes before it is ready.
+
+PROFILE_NAME=data
+K8S_VERSION=v1_36
+KIND_CONFIG=kind-config.yaml.tpl
+# Order matters: addons.sh installs in the order listed, and airflow refuses to
+# start without a metadata database, so postgres comes first.
+ADDONS="metallb postgres redis airflow"
+# local, not none — see minimal.env: `none` has no outward-push guard.
+REGISTRY_MODE=local
+INGRESS_MODE=hostport
+DNS_MODE=hosts
+
+# Namespace for the dependency containers.
+DATA_NAMESPACE=data
+
+# Postgres identity. The password is not here: postgres.sh generates one on
+# first install and keeps it across re-runs, so re-running the addon never
+# rotates the credential out from under whatever is already connected.
+POSTGRES_DB=soleprint
+POSTGRES_USER=soleprint
+POSTGRES_STORAGE=2Gi
+
+AIRFLOW_ADMIN_USER=admin
+
+# Ports derive from the directory name by default — see ctrl/ports.sh. Reach
+# the databases with port-forward rather than binding more host ports:
+#   kubectl -n data port-forward svc/postgres 5432:5432
+#   kubectl -n data port-forward svc/airflow 8080:8080

rig/ctrl/env.d/minimal.env

@@ -0,0 +1,21 @@
+# minimal — the default. One node, no addons, no registry.
+# Assumes nothing and boots fast. Start here; move to client.env when you need
+# the regulated behaviours.
+#
+
+PROFILE_NAME=minimal
+K8S_VERSION=v1_36
+KIND_CONFIG=kind-config.yaml.tpl
+ADDONS=""
+# local, not none: `none` leaves the cluster with no registry to push to, and an
+# unqualified image name then means docker.io/library/<name>. In a regulated
+# estate that is a disclosure risk, not a convenience trade — so the default
+# carries the guard even though it costs one container.
+REGISTRY_MODE=local
+INGRESS_MODE=hostport
+DNS_MODE=hosts
+
+# Ports are deliberately NOT set here. They derive from the directory name so
+# several environments coexist — see ctrl/ports.sh, and `make ports` to see the
+# block this one gets. A fixed default here would collide with whatever else the
+# machine happens to be running; 8080 in particular is rarely free.

rig/ctrl/env.d/offline.env

@@ -0,0 +1,18 @@
+# offline — air-gapped. Everything comes from a local registry that was loaded
+# ahead of time; nothing reaches the internet. Pair with the wizard-full image
+# (DEPS_SOURCE=baked) so the toolchain install is offline too.
+#
+# The heavier addons are left out to keep first boot viable.
+
+PROFILE_NAME=offline
+K8S_VERSION=v1_36
+KIND_CONFIG=kind-config.audit.yaml.tpl
+ADDONS="metallb"
+REGISTRY_MODE=local
+INGRESS_MODE=hostport
+DNS_MODE=hosts
+
+# Derived from the directory name by default — see ctrl/ports.sh.
+# Uncomment for the real ports, but only if this is the only environment.
+# HTTP_PORT=80
+# HTTPS_PORT=443

rig/ctrl/hosts.tmpl

@@ -0,0 +1,15 @@
+# /etc/hosts block for this environment. Rendered by newbox.sh; ${CLUSTER} and
+# ${HTTP_PORT} are substituted.
+#
+# Hostnames are a convenience, not a requirement — every service is reachable at
+# localhost:<port> without any of this, which is why DNS is not touched by
+# default. Add entries here as the model grows.
+#
+# On Windows the same block has to go in
+# C:\Windows\System32\drivers\etc\hosts for a browser to resolve these. That
+# file does NOT support wildcards, so every name must be listed explicitly.
+# newbox.sh prints the block for you to paste rather than editing it.
+
+127.0.0.1  ${CLUSTER}.local
+127.0.0.1  api.${CLUSTER}.local
+127.0.0.1  docs.${CLUSTER}.local

rig/ctrl/k8s/README.md

@@ -0,0 +1,71 @@
+# `ctrl/k8s` — cluster shape, and what runs on it
+
+Same layout as every other project here (`unt`, `nvi`, `eth`, `mpr`, and
+soleprint's generated rooms): a kind config, a kustomize `base/`, and an
+`overlays/dev/` that patches it. See ALL `projects/templates/conventions.md`.
+
+```
+kind-config*.yaml.tpl   the cluster itself — nodes, ports, audit
+base/                   the components, as plain manifests
+overlays/dev/           how this rig differs from the base
+audit-policy.yaml       mounted into the apiserver by the audit shapes
+```
+
+## Why the cluster config is a template
+
+Every other project checks in a literal `kind-config.yaml`, because there is
+exactly one `unt` and one `nvi`. A rig is copied and renamed to make a second
+environment, and both the cluster name and the host port block follow the
+directory name — so a literal would make every copy collide on both.
+
+`ctrl/cluster.sh` renders it with `sed`, substituting `${CLUSTER}`,
+`${NODE_IMAGE}`, `${HTTP_PORT}` and `${HOST_WORKDIR}`. Not `envsubst`: that is
+`gettext-base`, which a minimal Debian does not have, and Docker being the only
+prerequisite is the one promise rig makes.
+
+**The chosen file is the source of truth for node count and audit.**
+`lib/config.sh` reads both back out of it, so a profile names a shape and does
+not restate what the YAML already says.
+
+| file | nodes | audit | profiles |
+| --- | --- | --- | --- |
+| `kind-config.yaml.tpl` | 1 | off | `minimal`, `data` |
+| `kind-config.audit.yaml.tpl` | 1 | on | `offline` |
+| `kind-config.client.yaml.tpl` | 3 | on | `client` |
+
+A profile picks one with `KIND_CONFIG` in `ctrl/env.d/<profile>.env`. Adding a
+shape is adding a file — there is no dispatcher to edit.
+
+Audit is an apiserver flag and therefore fixed at creation: changing it is
+`make cluster reset`, not a re-apply.
+
+## `base/` — replace these
+
+**The two components in `base/` are examples, not the system.** They exist so
+the real manifests have a shape to be written against.
+
+The real ones are expected to be versioned **separately from the installer** —
+they change on a different cadence, by different people, under different review.
+Point `MANIFESTS_DIR` in `ctrl/.env` at their overlay and rig stops owning them:
+
+```
+MANIFESTS_DIR=../platform-manifests/overlays/dev
+```
+
+Until then it defaults to `ctrl/k8s/overlays/dev`.
+
+### The three states a component can be in
+
+Switching between them should be a one-line change, never a rewrite. The DNS
+name stays the same in every case, so callers never know the difference:
+
+| state | what exists | when |
+| --- | --- | --- |
+| **real** | an image built from source, hot-reloaded | the one thing you are working on |
+| **mock** | a stub returning canned responses (`example-mock.yaml`) | everything else — most of the estate |
+| **remote** | no pod at all, just a Service (`example-remote.yaml`) | when the real system is reachable and you want it |
+
+Most components should be **mock**. What has to be faithful is the topology —
+names, ports, dependency order, who can reach whom, how it fails. The workloads
+are noise, and mocking them is what makes several copies of a large estate fit
+on one laptop.

rig/ctrl/k8s/audit-policy.yaml

@@ -0,0 +1,44 @@
+# Apiserver audit policy. Mounted into the control plane at creation when a
+# profile sets AUDIT=on — an apiserver flag, so it cannot be added to a running
+# cluster without recreating it.
+#
+# Deliberately modest: enough to make "who changed what, and when" answerable
+# during onboarding without filling the disk. Read the log with:
+#   docker exec <cluster>-control-plane cat /var/log/kubernetes/audit.log
+apiVersion: audit.k8s.io/v1
+kind: Policy
+
+# Never log the request body for these — they contain credentials.
+omitStages:
+  - RequestReceived
+
+rules:
+  # Secrets/configmaps: record that access happened, never the contents.
+  - level: Metadata
+    resources:
+      - group: ""
+        resources: ["secrets", "configmaps"]
+
+  # Authn/authz decisions — the part an auditor actually asks about.
+  - level: Metadata
+    nonResourceURLs:
+      - /apis*
+      - /api*
+
+  # Mutations to workloads and policy: full request, so a diff is reconstructable.
+  - level: Request
+    verbs: ["create", "update", "patch", "delete"]
+    resources:
+      - group: ""
+        resources: ["pods", "services", "serviceaccounts", "namespaces"]
+      - group: "apps"
+      - group: "networking.k8s.io"
+      - group: "rbac.authorization.k8s.io"
+
+  # Everything else that changes state: metadata only.
+  - level: Metadata
+    verbs: ["create", "update", "patch", "delete"]
+
+  # Reads are dropped entirely — otherwise controller polling drowns the log.
+  - level: None
+    verbs: ["get", "list", "watch"]

rig/ctrl/k8s/base/example-mock.yaml

@@ -0,0 +1,104 @@
+# EXAMPLE — a mocked component. Copy, rename, replace.
+#
+# A stub that answers on the right name and port with canned responses. No image
+# to build: the script is mounted from the ConfigMap, so changing the behaviour
+# is a kubectl apply, not a rebuild.
+#
+# Deliberately boring and readable. This is onboarding material — someone should
+# be able to read the generated object and recognise what it is.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: example-service-stub
+data:
+  # Canned responses by path. Add entries as the contract becomes clear;
+  # anything unmatched returns 404 so a missing route is visible, not silent.
+  routes.json: |
+    {
+      "/health":     {"status": 200, "body": {"status": "ok"}},
+      "/v1/example": {"status": 200, "body": {"items": [], "mocked": true}}
+    }
+  serve.py: |
+    import json, os
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    ROUTES = json.load(open("/etc/stub/routes.json"))
+    NAME = os.environ.get("STUB_NAME", "stub")
+
+    class H(BaseHTTPRequestHandler):
+        def do_GET(self):
+            r = ROUTES.get(self.path)
+            if r is None:
+                self.send_response(404)
+                self.end_headers()
+                # Say which stub rejected it — with everything mocked, "404"
+                # alone tells you nothing about where the call actually landed.
+                self.wfile.write(json.dumps(
+                    {"error": "no canned route", "stub": NAME, "path": self.path}
+                ).encode())
+                return
+            body = json.dumps(r["body"]).encode()
+            self.send_response(r["status"])
+            self.send_header("Content-Type", "application/json")
+            self.send_header("X-Mocked-By", NAME)
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, fmt, *args):
+            print("%s %s" % (NAME, fmt % args), flush=True)
+
+    HTTPServer(("0.0.0.0", 8080), H).serve_forever()
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example-service
+  labels:
+    app: example-service
+    rig.component/impl: mock      # so `kubectl get deploy -L rig.component/impl`
+                                  # shows at a glance what is real and what is not
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: example-service
+  template:
+    metadata:
+      labels:
+        app: example-service
+    spec:
+      containers:
+        - name: stub
+          image: python:3.12-slim
+          command: ["python3", "/etc/stub/serve.py"]
+          env:
+            - name: STUB_NAME
+              value: example-service
+          ports:
+            - containerPort: 8080
+          volumeMounts:
+            - name: stub
+              mountPath: /etc/stub
+          readinessProbe:
+            httpGet: { path: /health, port: 8080 }
+            initialDelaySeconds: 2
+          # Small enough that a whole estate of these fits alongside the real
+          # thing you are working on.
+          resources:
+            requests: { memory: 32Mi, cpu: 10m }
+            limits:   { memory: 64Mi }
+      volumes:
+        - name: stub
+          configMap:
+            name: example-service-stub
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: example-service
+spec:
+  selector:
+    app: example-service
+  ports:
+    - port: 80
+      targetPort: 8080

rig/ctrl/k8s/base/example-remote.yaml

@@ -0,0 +1,46 @@
+# EXAMPLE — a component that is NOT simulated, pointed at the real system.
+#
+# This is the payoff of keeping the topology honest: there is no pod here at
+# all, yet `example-remote.<namespace>.svc.cluster.local` resolves exactly as it
+# does when the same component is mocked. Callers are identical in both cases,
+# so moving a dependency from mocked to real is a one-line change and nothing
+# downstream is touched.
+#
+# Use this when the real system is reachable and you want it in the loop.
+# Note that reachability depends on where you are running: systems restricted to
+# a managed workspace will not resolve from a laptop at all, which is the whole
+# reason most components should stay mocked.
+apiVersion: v1
+kind: Service
+metadata:
+  name: example-remote
+  labels:
+    rig.component/impl: remote
+spec:
+  type: ExternalName
+  externalName: real-system.internal.example.com
+---
+# If the real system has no DNS name — only an IP, which is common for legacy
+# hosts — ExternalName cannot express it. Use a bare Service plus manual
+# Endpoints instead, and delete the block above.
+#
+# apiVersion: v1
+# kind: Service
+# metadata:
+#   name: example-remote
+#   labels:
+#     rig.component/impl: remote
+# spec:
+#   ports:
+#     - port: 80
+#       targetPort: 8080
+# ---
+# apiVersion: v1
+# kind: Endpoints
+# metadata:
+#   name: example-remote      # must match the Service name exactly
+# subsets:
+#   - addresses:
+#       - ip: 10.0.0.42
+#     ports:
+#       - port: 8080

rig/ctrl/k8s/base/kustomization.yaml

@@ -0,0 +1,11 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+# The namespace every component lands in. The overlay overrides it, so a rig
+# modelling two estates can apply the same base twice under different names.
+namespace: rig
+
+resources:
+  - namespace.yaml
+  - example-mock.yaml
+  - example-remote.yaml

rig/ctrl/k8s/base/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: rig

rig/ctrl/k8s/kind-config.audit.yaml.tpl

@@ -0,0 +1,57 @@
+# Cluster shape: one node, apiserver audit ON. Used by the `offline` profile.
+#
+# Audit is an apiserver flag, so it is fixed when the cluster is created —
+# changing it means `make cluster reset`, not a re-apply. That is why it is a
+# property of the cluster file rather than something switched at runtime.
+#
+# k8s >= 1.31 uses kubeadm v1beta4, where extraArgs is a LIST of name/value
+# pairs. The older map form is silently ignored — it does not error, audit
+# simply never turns on.
+#
+# Substituted by ctrl/cluster.sh: CLUSTER, NODE_IMAGE, HTTP_PORT, HOST_WORKDIR
+# (named without the ${...} braces so this line survives the substitution)
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+name: ${CLUSTER}
+
+containerdConfigPatches:
+  - |-
+    [plugins."io.containerd.grpc.v1.cri".registry]
+      config_path = "/etc/containerd/certs.d"
+
+kubeadmConfigPatches:
+  - |
+    kind: ClusterConfiguration
+    apiServer:
+      extraArgs:
+        - name: audit-policy-file
+          value: /etc/kubernetes/audit/policy.yaml
+        - name: audit-log-path
+          value: /var/log/kubernetes/audit.log
+        - name: audit-log-maxage
+          value: "7"
+      extraVolumes:
+        - name: audit-policy
+          hostPath: /etc/kubernetes/audit
+          mountPath: /etc/kubernetes/audit
+          readOnly: true
+        - name: audit-log
+          hostPath: /var/log/kubernetes
+          mountPath: /var/log/kubernetes
+          readOnly: false
+
+nodes:
+  - role: control-plane
+    image: ${NODE_IMAGE}
+    # hostPath is resolved by the HOST dockerd, so this must be a host path even
+    # when cluster.sh runs inside the wizard container. HOST_WORKDIR says where
+    # this rig lives on the host; bare on a host it is just the repo root.
+    extraMounts:
+      - hostPath: ${HOST_WORKDIR}/ctrl/k8s/audit-policy.yaml
+        containerPath: /etc/kubernetes/audit/policy.yaml
+        readOnly: true
+    extraPortMappings:
+      - containerPort: 30080
+        hostPort: ${HTTP_PORT}
+        listenAddress: "0.0.0.0"
+        protocol: TCP

rig/ctrl/k8s/kind-config.client.yaml.tpl

@@ -0,0 +1,55 @@
+# Cluster shape: three nodes, apiserver audit ON. Used by the `client` profile —
+# the regulated-estate shape.
+#
+# Multi-node so taints, affinity and topology spread are real rather than
+# vacuously satisfied by a single node. It costs roughly 4-6 GB; run
+# `make cluster list` before starting this alongside other work.
+#
+# Substituted by ctrl/cluster.sh: CLUSTER, NODE_IMAGE, HTTP_PORT, HOST_WORKDIR
+# (named without the ${...} braces so this line survives the substitution)
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+name: ${CLUSTER}
+
+containerdConfigPatches:
+  - |-
+    [plugins."io.containerd.grpc.v1.cri".registry]
+      config_path = "/etc/containerd/certs.d"
+
+kubeadmConfigPatches:
+  - |
+    kind: ClusterConfiguration
+    apiServer:
+      extraArgs:
+        - name: audit-policy-file
+          value: /etc/kubernetes/audit/policy.yaml
+        - name: audit-log-path
+          value: /var/log/kubernetes/audit.log
+        - name: audit-log-maxage
+          value: "7"
+      extraVolumes:
+        - name: audit-policy
+          hostPath: /etc/kubernetes/audit
+          mountPath: /etc/kubernetes/audit
+          readOnly: true
+        - name: audit-log
+          hostPath: /var/log/kubernetes
+          mountPath: /var/log/kubernetes
+          readOnly: false
+
+nodes:
+  - role: control-plane
+    image: ${NODE_IMAGE}
+    extraMounts:
+      - hostPath: ${HOST_WORKDIR}/ctrl/k8s/audit-policy.yaml
+        containerPath: /etc/kubernetes/audit/policy.yaml
+        readOnly: true
+    extraPortMappings:
+      - containerPort: 30080
+        hostPort: ${HTTP_PORT}
+        listenAddress: "0.0.0.0"
+        protocol: TCP
+  - role: worker
+    image: ${NODE_IMAGE}
+  - role: worker
+    image: ${NODE_IMAGE}

rig/ctrl/k8s/kind-config.yaml.tpl

@@ -0,0 +1,36 @@
+# Cluster shape: one node, no audit. Used by the `minimal` and `data` profiles.
+#
+# A TEMPLATE rather than a plain kind-config.yaml because a rig is copied and
+# renamed to make a second environment, and both the cluster name and the host
+# port follow the directory. A checked-in literal would make every copy collide
+# on both. ctrl/cluster.sh renders it with sed — not envsubst, which is
+# gettext-base and absent from a minimal Debian, and rig's whole premise is that
+# Docker is the only prerequisite.
+#
+# Substituted by ctrl/cluster.sh: CLUSTER, NODE_IMAGE, HTTP_PORT, HOST_WORKDIR
+# (named without the ${...} braces so this line survives the substitution)
+# Node count and audit are READ BACK from this file by lib/config.sh, so this
+# YAML is the source of truth for both — there is no second place to update.
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+name: ${CLUSTER}
+
+# Point containerd at a certs.d directory. registry.sh drops per-host hosts.toml
+# files in there afterwards, so switching registry mode never requires
+# recreating the cluster.
+containerdConfigPatches:
+  - |-
+    [plugins."io.containerd.grpc.v1.cri".registry]
+      config_path = "/etc/containerd/certs.d"
+
+nodes:
+  - role: control-plane
+    image: ${NODE_IMAGE}
+    # One NodePort bridged to the host; an in-cluster gateway owns it. There is
+    # deliberately no ingress controller — they pin a narrow window of k8s
+    # versions, and running a trailing-edge control plane is the point.
+    extraPortMappings:
+      - containerPort: 30080
+        hostPort: ${HTTP_PORT}
+        listenAddress: "0.0.0.0"
+        protocol: TCP

rig/ctrl/k8s/overlays/dev/kustomization.yaml

@@ -0,0 +1,22 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+# The dev overlay is where a rig says how its estate differs from the base —
+# which components are real, which are mocked, which point at a live system.
+# Kept empty on purpose: the base already boots, and an overlay full of examples
+# is harder to read than one that starts blank.
+#
+# The shape a patch takes, for when the first one is needed:
+#
+# patches:
+#   - target: {kind: Service, name: example-service}
+#     patch: |
+#       - op: replace
+#         path: /spec/type
+#         value: NodePort
+#       - op: add
+#         path: /spec/ports/0/nodePort
+#         value: 30080

rig/ctrl/lib/config.sh

@@ -0,0 +1,148 @@
+# Shared config loading. Sourced, never executed.
+#
+# The ecosystem convention is that scripts are standalone with no shared log
+# library — that still holds. This file is not a logging lib; it is the single
+# definition of how the config layers compose, which every script has to agree
+# on exactly. Precedence, weakest first:
+#
+#   ctrl/versions.env      pinned toolchain + image digests   (committed)
+#   ctrl/env.d/<profile>   cluster shape                      (committed)
+#   ctrl/.env              machine-local values and secrets   (gitignored)
+#   the caller's env       `make cluster up PROFILE=client`   (always wins)
+#
+# That last rule is why this is more than a few `source` lines: .env sets
+# PROFILE, so without snapshotting it would silently override the PROFILE the
+# user just typed on the command line.
+#
+# Run from ctrl/.
+
+# Values a user can reasonably override per-invocation. Anything set in the
+# environment when load_config runs is restored after the files are read.
+# NODES and AUDIT are deliberately NOT here: they are properties of the chosen
+# ctrl/k8s/kind-config*.yaml.tpl and are read back out of it below, so there is
+# one place that decides the shape of the cluster rather than two that can drift.
+CONFIG_OVERRIDABLE="PROFILE CLUSTER K8S_VERSION KIND_CONFIG ADDONS
+                    REGISTRY_MODE INGRESS_MODE DNS_MODE TILT_PORT
+                    SOURCE ARCH DEPS_SOURCE HTTP_PORT HTTPS_PORT"
+
+# The containing folder's name, reduced to something kind accepts as a cluster
+# name (a DNS label: lowercase alphanumerics and dashes). Run from ctrl/, so the
+# repo root is the parent.
+default_cluster_name() {
+    local n
+    n=$(basename "$(cd .. && pwd)")
+    n=$(echo "$n" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-')
+    n=$(echo "$n" | sed 's/^-*//; s/-*$//')
+    echo "${n:-rig}"
+}
+
+# Base of this environment's 10-port block. cksum is used rather than $RANDOM or
+# bash hashing because it is POSIX and returns the same value on every machine,
+# which is what makes the block reproducible instead of merely unique.
+derive_port_base() {
+    local h; h=$(printf '%s' "$1" | cksum | awk '{print $1}')
+    echo $((20000 + (h % 200) * 10))
+}
+
+load_config() {
+    local k saved=""
+    for k in $CONFIG_OVERRIDABLE; do
+        # ${!k+x} distinguishes "set but empty" from "unset" — an explicit
+        # FOO= on the command line is a real choice and must survive.
+        if [ -n "${!k+x}" ]; then
+            saved+="$k=$(printf '%q' "${!k}")"$'\n'
+        fi
+    done
+
+    set -a
+    source ./versions.env
+    [ -f ./.env ] && source ./.env
+    set +a
+
+    # Re-apply overrides now so PROFILE is the caller's before we pick the file.
+    _config_restore "$saved"
+
+    local profile="${PROFILE:-minimal}"
+    if [ ! -f "./env.d/${profile}.env" ]; then
+        echo "no such profile: env.d/${profile}.env" >&2
+        echo "available: $(ls env.d/*.env 2>/dev/null | xargs -n1 basename | sed 's/\.env$//' | tr '\n' ' ')" >&2
+        exit 1
+    fi
+
+    set -a
+    source "./env.d/${profile}.env"
+    [ -f ./.env ] && source ./.env
+    set +a
+
+    _config_restore "$saved"
+
+    # Identity follows the FOLDER, so copying this directory somewhere else and
+    # renaming it yields a distinct environment with no further edits. Without
+    # this, two copies would share one cluster and `make cluster down` in either
+    # would destroy the other's.
+    CLUSTER="${CLUSTER:-$(default_cluster_name)}"
+    KUBECONTEXT="kind-${CLUSTER}"
+
+    # Host ports are a single shared namespace, so unlike the cluster name they
+    # cannot just follow the directory — they have to be spread out. Anything
+    # already set (ctrl/.env, a profile, the command line) wins; only the gaps
+    # are filled. See ports.sh for the reasoning.
+    local base; base=$(derive_port_base "$CLUSTER")
+    HTTP_PORT="${HTTP_PORT:-$base}"
+    HTTPS_PORT="${HTTPS_PORT:-$((base + 1))}"
+    TILT_PORT="${TILT_PORT:-$((base + 2))}"
+    REGISTRY_PORT="${REGISTRY_PORT:-$((base + 3))}"
+
+    # Profiles name a k8s minor (v1_36); versions.env holds the pinned digest.
+    local var="NODE_IMAGE_${K8S_VERSION}"
+    NODE_IMAGE="${!var:-}"
+    if [ -z "$NODE_IMAGE" ]; then
+        echo "K8S_VERSION='${K8S_VERSION}' has no NODE_IMAGE_${K8S_VERSION} in versions.env" >&2
+        exit 1
+    fi
+
+    # The cluster's shape is a file in ctrl/k8s/, named by the profile. Adding a
+    # shape is adding a file; there is no dispatcher to edit.
+    KIND_CONFIG="${KIND_CONFIG:-kind-config.yaml.tpl}"
+    KIND_CONFIG_PATH="./k8s/${KIND_CONFIG}"
+    if [ ! -f "$KIND_CONFIG_PATH" ]; then
+        echo "no such cluster shape: ctrl/k8s/${KIND_CONFIG}" >&2
+        echo "available: $(ls k8s/kind-config*.yaml.tpl 2>/dev/null | xargs -n1 basename | tr '\n' ' ')" >&2
+        exit 1
+    fi
+
+    # Read the shape back out of the YAML rather than trusting a profile to
+    # restate it. station.sh sizes the memory warning on NODES, and cluster.sh
+    # prints AUDIT before spending minutes building something that cannot be
+    # changed afterwards — both would mislead if the numbers drifted.
+    NODES=$(grep -c '^  - role:' "$KIND_CONFIG_PATH")
+    if grep -q 'audit-policy-file' "$KIND_CONFIG_PATH"; then AUDIT=on; else AUDIT=off; fi
+}
+
+# Render a cluster shape to stdout. sed rather than envsubst: envsubst is
+# gettext-base, absent from a minimal Debian, and Docker is meant to be the only
+# prerequisite. The variable list is explicit so a template cannot quietly start
+# depending on something the caller does not set.
+#
+# hostPath entries are resolved by the HOST dockerd, so HOST_WORKDIR must stay a
+# host path even when this runs inside the wizard container.
+render_kind_config() {
+    local host_workdir="${HOST_WORKDIR:-$(cd .. && pwd)}"
+    sed -e "s|\${CLUSTER}|${CLUSTER}|g" \
+        -e "s|\${NODE_IMAGE}|${NODE_IMAGE}|g" \
+        -e "s|\${HTTP_PORT}|${HTTP_PORT}|g" \
+        -e "s|\${HOST_WORKDIR}|${host_workdir}|g" \
+        "$KIND_CONFIG_PATH"
+}
+
+_config_restore() {
+    local line
+    while IFS= read -r line; do
+        if [ -n "$line" ]; then
+            eval "export $line"
+        fi
+    done <<< "$1"
+    # A while loop returns its last body command's status; the trailing empty
+    # line would otherwise make this return 1 and trip `set -e` in the caller.
+    return 0
+}

rig/ctrl/newbox.sh

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Create a disposable Linux environment to validate the installer from a
+# genuinely clean slate — one that can be thrown away without touching the
+# environment you actually work in.
+#
+# This is the ONLY host-aware file in the tree. Everything else needs just a
+# Linux with Docker, which is what keeps other host types a later addition
+# rather than a rewrite.
+#
+# On WSL it creates a second distro. There is no .bat and no PowerShell script:
+# wsl.exe is callable from inside WSL, and wslpath converts the paths it wants.
+# A machine with no WSL at all needs `wsl --install` run once by hand first —
+# scripting a reboot-requiring Windows feature install is not worth it.
+#
+# Docker: borrowed by default, never installed twice
+# --------------------------------------------------
+# WSL2 distros share one kernel and one network stack, so two dockerd instances
+# contend over docker0 and iptables and can disturb the daemon you depend on.
+# (That is why Docker Desktop runs one daemon in a dedicated distro and shares
+# its socket rather than installing one per distro.)
+#
+#   REUSE_DOCKER=1  (default)  borrow the host distro's daemon over /mnt/wsl.
+#                              Nothing is installed; nothing can conflict.
+#                              Requires `ctrl/dockerhost.sh share` once on the
+#                              distro that owns Docker.
+#   REUSE_DOCKER=0             install a second daemon in the new distro. Only
+#                              if you specifically want to test a from-scratch
+#                              Docker install, and not on a machine you need.
+#
+# Borrowing is also the more honest test: rig never installs Docker anyway — it
+# is the documented prerequisite — so a clean box does not need its own to
+# exercise everything rig actually does.
+#
+# Usage: newbox.sh create | destroy [--purge] | status | shell
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+REPO="$(cd .. && pwd)"
+
+# The distro is named after this environment, and that derived name is the ONLY
+# thing this script will ever destroy. See guard_name().
+BOX="${BOX:-${CLUSTER}box}"
+BOX_USER="${BOX_USER:-dev}"
+
+# Borrow the host distro's Docker rather than installing a second daemon.
+REUSE_DOCKER="${REUSE_DOCKER:-1}"
+SHARED_SOCK=/mnt/wsl/shared-docker/docker.sock
+
+WSL_EXE=/mnt/c/Windows/System32/wsl.exe
+
+# ── host detection ─────────────────────────────────────────────────────────
+
+require_wsl() {
+    if ! grep -qi microsoft /proc/version 2>/dev/null; then
+        cat >&2 <<'EOF'
+newbox is WSL-only for now.
+
+On native Linux you do not need it: rig already isolates environments by
+directory (own cluster, context, images and port block), so a second copy in a
+second directory is the clean slate. To validate the installer itself against a
+bare system, run the wizard against a stock Debian container instead.
+EOF
+        exit 1
+    fi
+    if [ ! -x "$WSL_EXE" ]; then
+        echo "wsl.exe not found at $WSL_EXE" >&2
+        exit 1
+    fi
+}
+
+wsl_list() { "$WSL_EXE" -l -q 2>/dev/null | tr -d '\0\r'; }
+box_exists() { wsl_list | grep -qx "$BOX"; }
+
+# `wsl --unregister` permanently deletes a distro's filesystem. The whole safety
+# story is this function: only the name derived from this directory can ever be
+# a target, so a typo or a stray argument cannot destroy the distro you work in.
+guard_name() {
+    local derived="${CLUSTER}box"
+    if [ "$BOX" != "$derived" ]; then
+        echo "refusing: BOX='$BOX' is not the name derived from this directory ('$derived')." >&2
+        echo "That guard exists because --unregister is irreversible." >&2
+        exit 1
+    fi
+    if [ -z "$CLUSTER" ] || [ "$BOX" = "box" ]; then
+        echo "refusing: empty environment name" >&2
+        exit 1
+    fi
+}
+
+# ── create ─────────────────────────────────────────────────────────────────
+
+rootfs_path() {
+    local win_home; win_home=$(wslpath "$("$WSL_EXE" -d "$(wsl_list | head -1)" -e printf '%s' "$USERPROFILE" 2>/dev/null || true)" 2>/dev/null || true)
+    # Simpler and reliable: use the current user's Windows home via /mnt/c.
+    ls -d /mnt/c/Users/*/ 2>/dev/null | grep -viE '/(All Users|Default|Default User|Public)/$' | head -1
+}
+
+build_rootfs() {
+    local tar="$1"
+    if [ -f "$tar" ]; then
+        echo "  rootfs cached: $(basename "$tar")"
+        return
+    fi
+    echo "  exporting a stock Debian rootfs (cached for next time)"
+    local cid; cid=$(docker create debian:trixie-slim)
+    docker export "$cid" > "$tar"
+    docker rm -f "$cid" >/dev/null
+}
+
+provision() {
+    echo "  provisioning (root)"
+    local hosts_block
+    hosts_block=$(CLUSTER="$CLUSTER" HTTP_PORT="$HTTP_PORT" \
+                  envsubst < ./hosts.tmpl 2>/dev/null || sed "s/\${CLUSTER}/$CLUSTER/g" ./hosts.tmpl)
+
+    # Piped as stdin rather than a second script file, the same shape as any
+    # remote provisioning heredoc. Everything here is idempotent so a failed run
+    # can simply be repeated.
+    "$WSL_EXE" -d "$BOX" -u root -- bash -s <<PROVISION
+set -euo pipefail
+
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y -qq ca-certificates curl gnupg sudo >/dev/null
+
+if [ "$REUSE_DOCKER" = "1" ]; then
+    # Borrow the host distro's daemon: CLI only, no dockerd, nothing to
+    # conflict with. The GID must match the owner's or the shared socket is
+    # unreadable here even though it is visible.
+    install -m 0755 -d /etc/apt/keyrings
+    if [ ! -f /etc/apt/keyrings/docker.asc ]; then
+        curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
+        chmod a+r /etc/apt/keyrings/docker.asc
+    fi
+    echo "deb [arch=\$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \$(. /etc/os-release && echo \$VERSION_CODENAME) stable" \
+        > /etc/apt/sources.list.d/docker.list
+    apt-get update -qq
+    apt-get install -y -qq docker-ce-cli >/dev/null
+
+    echo "export DOCKER_HOST=unix://$SHARED_SOCK" > /etc/profile.d/rig-docker-host.sh
+
+    if [ -f /mnt/wsl/shared-docker/OWNER ]; then
+        gid=\$(awk '/docker gid:/ {print \$3}' /mnt/wsl/shared-docker/OWNER)
+        if [ -n "\$gid" ]; then
+            getent group docker >/dev/null && groupmod -g "\$gid" docker || groupadd -g "\$gid" docker
+        fi
+    fi
+else
+    # A second daemon. Only when deliberately testing a from-scratch install.
+    install -m 0755 -d /etc/apt/keyrings
+    if [ ! -f /etc/apt/keyrings/docker.asc ]; then
+        curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
+        chmod a+r /etc/apt/keyrings/docker.asc
+    fi
+    echo "deb [arch=\$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \$(. /etc/os-release && echo \$VERSION_CODENAME) stable" \
+        > /etc/apt/sources.list.d/docker.list
+    apt-get update -qq
+    apt-get install -y -qq docker-ce docker-ce-cli containerd.io >/dev/null
+fi
+
+id -u "$BOX_USER" >/dev/null 2>&1 || useradd -m -s /bin/bash "$BOX_USER"
+usermod -aG sudo,docker "$BOX_USER"
+echo "$BOX_USER ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/90-$BOX_USER
+chmod 0440 /etc/sudoers.d/90-$BOX_USER
+
+# systemd is off by default in WSL, and Docker needs it. Takes effect on the
+# next start of this distro, which is why create() terminates it below.
+cat > /etc/wsl.conf <<WSLCONF
+[boot]
+systemd=true
+
+[user]
+default=$BOX_USER
+WSLCONF
+
+# The default inotify limits are low enough that file watching silently stops
+# working — no error, changes just stop being noticed. Fix it before it bites.
+cat > /etc/sysctl.d/99-rig.conf <<SYSCTL
+fs.inotify.max_user_watches=524288
+fs.inotify.max_user_instances=512
+SYSCTL
+
+if ! grep -q 'rig environment' /etc/hosts 2>/dev/null; then
+    { echo ""; echo "# rig environment"; cat <<'HOSTS'
+$hosts_block
+HOSTS
+    } >> /etc/hosts
+fi
+
+touch /etc/rig-provisioned
+PROVISION
+}
+
+create() {
+    require_wsl
+    guard_name
+
+    local winhome; winhome=$(rootfs_path)
+    [ -n "$winhome" ] || { echo "could not locate the Windows user directory" >&2; exit 1; }
+    local tar="${winhome}rig-rootfs.tar"
+    local installdir="${winhome}WSL/${BOX}"
+
+    echo "creating '$BOX'"
+    if [ "$REUSE_DOCKER" = "1" ]; then
+        echo "  docker: borrowing the host distro's daemon (nothing installed)"
+        if [ ! -S "$SHARED_SOCK" ]; then
+            echo
+            echo "  No shared socket yet. In the distro that owns Docker, run once:"
+            echo "      sudo bash ctrl/dockerhost.sh share"
+            echo "  That adds one systemd drop-in and nothing else; undo with 'unshare'."
+            echo "  Continuing — the box will be created, but Docker won't work in it"
+            echo "  until you do that."
+        fi
+    else
+        echo
+        echo "  REUSE_DOCKER=0: installing a SECOND Docker daemon."
+        echo "  WSL distros share a network stack, so this can disturb Docker in"
+        echo "  the distro you work in. Ctrl-C now if that is a bad trade today."
+        echo
+        sleep 4
+    fi
+    echo
+
+    if box_exists; then
+        echo "  distro already registered"
+    else
+        build_rootfs "$tar"
+        mkdir -p "$installdir"
+        "$WSL_EXE" --import "$BOX" "$(wslpath -w "$installdir")" "$(wslpath -w "$tar")" --version 2
+    fi
+
+    # Resumable: a partially-created box is finished rather than restarted.
+    if "$WSL_EXE" -d "$BOX" -u root -- test -f /etc/rig-provisioned 2>/dev/null; then
+        echo "  already provisioned"
+    else
+        provision
+        echo "  restarting the distro so systemd and group membership apply"
+        "$WSL_EXE" --terminate "$BOX"      # ONLY this distro; never --shutdown
+    fi
+
+    echo "  copying rig in"
+    tar c -C "$REPO" --exclude=def --exclude=.git --exclude=ctrl/.env . \
+        | "$WSL_EXE" -d "$BOX" -u "$BOX_USER" -- bash -lc "mkdir -p ~/rig && tar x -C ~/rig"
+
+    echo
+    echo "  docker: $("$WSL_EXE" -d "$BOX" -u "$BOX_USER" -- bash -lc 'systemctl is-active docker 2>/dev/null || echo inactive')"
+    echo
+    echo "next:"
+    echo "  make newbox shell        # a shell inside it"
+    echo "  then: cd ~/rig && make station && make deps && make cluster up"
+    echo
+    echo "For a browser on Windows to resolve the hostnames, paste this into"
+    echo "C:\\Windows\\System32\\drivers\\etc\\hosts (it has no wildcard support):"
+    CLUSTER="$CLUSTER" envsubst < ./hosts.tmpl 2>/dev/null | grep -v '^#' | grep -v '^$' | sed 's/^/    /'
+}
+
+# ── the rest ───────────────────────────────────────────────────────────────
+
+destroy() {
+    require_wsl
+    guard_name
+
+    if ! box_exists; then
+        echo "no distro '$BOX' to remove"
+    else
+        echo "about to PERMANENTLY delete the distro '$BOX' and its filesystem."
+        "$WSL_EXE" --terminate "$BOX" 2>/dev/null || true
+        "$WSL_EXE" --unregister "$BOX"
+        echo "  unregistered"
+    fi
+
+    local winhome; winhome=$(rootfs_path)
+    rm -rf "${winhome}WSL/${BOX}" 2>/dev/null || true
+
+    if [ "${1:-}" = "--purge" ]; then
+        rm -f "${winhome}rig-rootfs.tar"
+        echo "  cached rootfs removed"
+    fi
+}
+
+status() {
+    require_wsl
+    echo "environment  $CLUSTER"
+    echo "distro       $BOX"
+    if box_exists; then
+        echo "registered   yes"
+        echo "provisioned  $("$WSL_EXE" -d "$BOX" -u root -- test -f /etc/rig-provisioned 2>/dev/null && echo yes || echo no)"
+        echo "docker       $("$WSL_EXE" -d "$BOX" -u root -- bash -lc 'systemctl is-active docker 2>/dev/null' || echo unknown)"
+        echo "rig copied   $("$WSL_EXE" -d "$BOX" -u "$BOX_USER" -- bash -lc 'test -f ~/rig/Makefile && echo yes || echo no' 2>/dev/null)"
+    else
+        echo "registered   no"
+    fi
+    echo
+    echo "all distros (this one is never touched unless it is '$BOX'):"
+    wsl_list | sed 's/^/  /'
+}
+
+shell() {
+    require_wsl
+    box_exists || { echo "no distro '$BOX' — run 'make newbox' first" >&2; exit 1; }
+    "$WSL_EXE" -d "$BOX" -u "$BOX_USER" --cd '~'
+}
+
+case "${1:-status}" in
+    create)  create ;;
+    destroy) shift; destroy "${1:-}" ;;
+    status)  status ;;
+    shell)   shell ;;
+    *)       echo "usage: $0 [create|destroy [--purge]|status|shell]" >&2; exit 1 ;;
+esac

rig/ctrl/ports.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Give each environment its own block of host ports.
+#
+# New versions of a system mean new clusters on ONE machine, not new machines.
+# Cluster name, kubectl context, registry container and image tag already derive
+# from the directory name, so two copies never collide there — but host ports are
+# a single shared namespace and would.
+#
+# The block is derived from the directory name: stateless, stable, and requiring
+# no coordination between copies that know nothing about each other.
+#
+#   base = 20000 + (hash(slug) % 200) * 10
+#     +0 HTTP   +1 HTTPS   +2 TILT   +3 REGISTRY   (+4..9 reserved)
+#
+# 20000+ deliberately avoids the ports something is already likely to hold: 80,
+# 443, 3000, 5432, 8000, 8080.
+#
+# Derivation is a default, not a decision. On first use the resolved block is
+# written into ctrl/.env, so it becomes pinned, visible and editable rather than
+# a number that appears from nowhere. Anything already in ctrl/.env wins.
+#
+# Usage: ports.sh show | derive | persist
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+
+# derive_port_base lives in lib/config.sh so every script resolves the same block
+# without going through this one.
+derive_base() { derive_port_base "$1"; }
+
+derive() {
+    load_config
+    local base; base=$(derive_base "$CLUSTER")
+    DERIVED_HTTP=$base
+    DERIVED_HTTPS=$((base + 1))
+    DERIVED_TILT=$((base + 2))
+    DERIVED_REGISTRY=$((base + 3))
+}
+
+show() {
+    derive
+    echo "environment  $CLUSTER"
+    echo "derived base $(derive_base "$CLUSTER")"
+    echo
+    printf "  %-14s %-8s %-8s %s\n" KEY DERIVED ACTIVE SOURCE
+    _row HTTP_PORT     "$DERIVED_HTTP"
+    _row HTTPS_PORT    "$DERIVED_HTTPS"
+    _row TILT_PORT     "$DERIVED_TILT"
+    _row REGISTRY_PORT "$DERIVED_REGISTRY"
+}
+
+_row() {
+    local key="$1" derived="$2" active="${!1:-}" src="derived"
+    if [ -n "$active" ] && [ "$active" != "$derived" ]; then
+        src="override"
+    elif [ -z "$active" ]; then
+        active="$derived"
+    fi
+    printf "  %-14s %-8s %-8s %s\n" "$key" "$derived" "$active" "$src"
+}
+
+# Write the derived block into ctrl/.env, once. Existing keys are never
+# rewritten — an override stays an override.
+persist() {
+    derive
+    [ -f ./.env ] || cp ./.env.example ./.env
+
+    local wrote=0 key val
+    for key in HTTP_PORT:$DERIVED_HTTP \
+               HTTPS_PORT:$DERIVED_HTTPS \
+               TILT_PORT:$DERIVED_TILT \
+               REGISTRY_PORT:$DERIVED_REGISTRY; do
+        val="${key#*:}"; key="${key%%:*}"
+        if grep -qE "^${key}=[0-9]" ./.env 2>/dev/null; then
+            continue
+        fi
+        if [ "$wrote" -eq 0 ]; then
+            {
+                echo ""
+                echo "# Port block for this environment, derived from the directory name"
+                echo "# so copies never collide. Pinned here on first use — edit freely."
+            } >> ./.env
+            wrote=1
+        fi
+        # Replace a commented/empty placeholder if present, else append.
+        if grep -qE "^#?\s*${key}=" ./.env 2>/dev/null; then
+            sed -i "s|^#\?\s*${key}=.*|${key}=${val}|" ./.env
+        else
+            echo "${key}=${val}" >> ./.env
+        fi
+    done
+
+    [ "$wrote" -eq 1 ] && echo "pinned port block into ctrl/.env" || echo "ports already set in ctrl/.env"
+    return 0
+}
+
+case "${1:-show}" in
+    show)    show ;;
+    derive)  derive; echo "$DERIVED_HTTP $DERIVED_HTTPS $DERIVED_TILT $DERIVED_REGISTRY" ;;
+    persist) persist ;;
+    *)       echo "usage: $0 [show|derive|persist]" >&2; exit 1 ;;
+esac

rig/ctrl/registry.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# Registry plumbing. THIS is the seam — not a tool.
+#
+# Four modes, selected by REGISTRY_MODE in the active profile:
+#
+#   none     Tilt builds straight into the node. No registry at all — and so no
+#            guard against an outward push: an unqualified image name means
+#            docker.io/library/<name>, and only Tilt's kind detection stands
+#            between that and a real push. Throwaway use only; every profile
+#            here now defaults to `local` instead.
+#   local    a registry:2 container wired into the cluster.
+#   mirror   the same container, but configured as a pull-through CACHE of the
+#            corporate registry. What a locked-down client actually looks like:
+#            images originate from corp, you don't hammer it, and you keep
+#            working when the VPN drops.
+#   remote   no local container; pull straight from the corporate registry using
+#            an imagePullSecret.
+#
+# Deliberately a script rather than a tool. ctlptl collapses the `local` wiring
+# into one line, but its Registry spec only accepts name/port/image/listenAddress
+# — there is no way to set REGISTRY_PROXY_REMOTEURL, so it cannot express
+# `mirror` at all. Keeping the seam here is what keeps the corporate registry
+# swappable.
+#
+# Usage: registry.sh up | down | status
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+REG_NAME="${CLUSTER}-registry"
+REG_PORT="${REGISTRY_PORT:-5005}"
+K="kubectl --context ${KUBECONTEXT}"
+
+# ── CA trust ───────────────────────────────────────────────────────────────
+# A corporate registry is almost always fronted by an internal CA, and trust has
+# to reach three separate places. Nothing does this for you, and the symptom when
+# it's missing is an opaque:
+#   x509: certificate signed by unknown authority
+#
+#   1. the host docker daemon   — /etc/docker/certs.d/<host>/ca.crt (needs root)
+#   2. every kind node's containerd — nodes do NOT inherit host trust
+#   3. anything doing HTTPS from inside the cluster, in its own trust store
+#
+# We handle (2) here because it's ours to handle. (1) is reported by station.sh
+# since it needs root. (3) belongs to the workload.
+install_ca_into_nodes() {
+    [ -n "${REGISTRY_CA_FILE:-}" ] || return 0
+
+    if [ ! -r "$REGISTRY_CA_FILE" ]; then
+        echo "REGISTRY_CA_FILE is set but not readable: $REGISTRY_CA_FILE" >&2
+        exit 1
+    fi
+
+    echo "  distributing CA to kind nodes"
+    local node
+    for node in $(kind get nodes --name "$CLUSTER"); do
+        docker cp "$REGISTRY_CA_FILE" "$node:/usr/local/share/ca-certificates/corp-registry.crt"
+        docker exec "$node" update-ca-certificates >/dev/null 2>&1
+        docker exec "$node" systemctl restart containerd
+    done
+}
+
+# Point containerd at a registry host. The cluster config already set
+# config_path=/etc/containerd/certs.d, so this is a per-node drop-in and needs no
+# cluster recreate — which is what lets registry mode change on a live cluster.
+write_hosts_toml() {
+    local host="$1" upstream="$2" skip_verify="${3:-false}"
+    local node
+    for node in $(kind get nodes --name "$CLUSTER"); do
+        docker exec "$node" mkdir -p "/etc/containerd/certs.d/${host}"
+        docker exec -i "$node" cp /dev/stdin "/etc/containerd/certs.d/${host}/hosts.toml" <<TOML
+server = "${upstream}"
+
+[host."${upstream}"]
+  capabilities = ["pull", "resolve"]
+  skip_verify = ${skip_verify}
+TOML
+    done
+}
+
+# ── the local container (local + mirror) ───────────────────────────────────
+
+start_registry_container() {
+    if [ "$(docker inspect -f '{{.State.Running}}' "$REG_NAME" 2>/dev/null || true)" = "true" ]; then
+        echo "  registry container '$REG_NAME' already running"
+        return
+    fi
+    docker rm -f "$REG_NAME" >/dev/null 2>&1 || true
+
+    local args=(-d --restart=always --name "$REG_NAME"
+                -p "127.0.0.1:${REG_PORT}:5000")
+
+    if [ "$REGISTRY_MODE" = "mirror" ]; then
+        if [ -z "${REGISTRY_REMOTE_URL:-}" ]; then
+            echo "REGISTRY_MODE=mirror needs REGISTRY_REMOTE_URL in ctrl/.env" >&2
+            exit 1
+        fi
+        echo "  starting pull-through cache of ${REGISTRY_REMOTE_URL}"
+        args+=(-e "REGISTRY_PROXY_REMOTEURL=${REGISTRY_REMOTE_URL}")
+        [ -n "${REGISTRY_USER:-}" ]     && args+=(-e "REGISTRY_PROXY_USERNAME=${REGISTRY_USER}")
+        [ -n "${REGISTRY_PASSWORD:-}" ] && args+=(-e "REGISTRY_PROXY_PASSWORD=${REGISTRY_PASSWORD}")
+        if [ -n "${REGISTRY_CA_FILE:-}" ]; then
+            args+=(-v "$(readlink -f "$REGISTRY_CA_FILE"):/etc/ssl/certs/corp-ca.crt:ro")
+        fi
+    else
+        echo "  starting local registry"
+    fi
+
+    docker run "${args[@]}" "$REGISTRY_IMAGE" >/dev/null
+}
+
+# The registry must share a network with the nodes so they can resolve it by
+# container name; localhost inside a node is the node, not the host.
+join_kind_network() {
+    if docker inspect -f '{{json .NetworkSettings.Networks}}' "$REG_NAME" | grep -q '"kind"'; then
+        return
+    fi
+    docker network connect kind "$REG_NAME" >/dev/null 2>&1 || true
+}
+
+# The documented contract that tells tooling (Tilt, skaffold) where the local
+# registry is, so they don't have to be configured separately.
+apply_hosting_configmap() {
+    $K apply -f - <<YAML >/dev/null
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: local-registry-hosting
+  namespace: kube-public
+data:
+  localRegistryHosting.v1: |
+    host: "localhost:${REG_PORT}"
+    help: "https://kind.sigs.k8s.io/docs/user/local-registry/"
+YAML
+}
+
+# ── modes ──────────────────────────────────────────────────────────────────
+
+up() {
+    echo "registry: ${REGISTRY_MODE}"
+    case "$REGISTRY_MODE" in
+        none)
+            echo "  no registry — images are built straight into the node"
+            ;;
+
+        local|mirror)
+            start_registry_container
+            join_kind_network
+            install_ca_into_nodes
+            # Nodes reach the registry by container name on the shared network;
+            # the host reaches it on localhost:PORT. Both names must resolve.
+            write_hosts_toml "localhost:${REG_PORT}" "http://${REG_NAME}:5000"
+            if [ "$REGISTRY_MODE" = "mirror" ]; then
+                # Anything asking for docker.io transparently goes to the cache.
+                write_hosts_toml "docker.io" "http://${REG_NAME}:5000"
+            fi
+            apply_hosting_configmap
+            echo "  ready at localhost:${REG_PORT}"
+            ;;
+
+        remote)
+            if [ -z "${REGISTRY_REMOTE_URL:-}" ]; then
+                echo "REGISTRY_MODE=remote needs REGISTRY_REMOTE_URL in ctrl/.env" >&2
+                exit 1
+            fi
+            install_ca_into_nodes
+            local host="${REGISTRY_REMOTE_URL#*://}"; host="${host%%/*}"
+            if [ -n "${REGISTRY_USER:-}" ]; then
+                echo "  creating imagePullSecret for ${host}"
+                $K create secret docker-registry regcred \
+                    --docker-server="$host" \
+                    --docker-username="$REGISTRY_USER" \
+                    --docker-password="$REGISTRY_PASSWORD" \
+                    --dry-run=client -o yaml | $K apply -f - >/dev/null
+                # Attach to the default ServiceAccount so plain pods inherit it.
+                $K patch serviceaccount default \
+                    -p '{"imagePullSecrets":[{"name":"regcred"}]}' >/dev/null
+            fi
+            echo "  pulling directly from ${host}"
+            ;;
+
+        *)
+            echo "unknown REGISTRY_MODE '$REGISTRY_MODE' (expected none|local|mirror|remote)" >&2
+            exit 1
+            ;;
+    esac
+}
+
+down() {
+    if docker inspect "$REG_NAME" >/dev/null 2>&1; then
+        echo "removing registry container '$REG_NAME'"
+        docker rm -f "$REG_NAME" >/dev/null
+    fi
+}
+
+status() {
+    echo "mode      ${REGISTRY_MODE}"
+    if docker inspect "$REG_NAME" >/dev/null 2>&1; then
+        echo "container ${REG_NAME}  $(docker inspect -f '{{.State.Status}}' "$REG_NAME")"
+        echo "endpoint  localhost:${REG_PORT}"
+    else
+        echo "container none"
+    fi
+    [ -n "${REGISTRY_REMOTE_URL:-}" ] && echo "upstream  ${REGISTRY_REMOTE_URL}"
+    [ -n "${REGISTRY_CA_FILE:-}" ]    && echo "ca        ${REGISTRY_CA_FILE}"
+    return 0
+}
+
+case "${1:-status}" in
+    up)     up ;;
+    down)   down ;;
+    status) status ;;
+    *)      echo "usage: $0 [up|down|status]" >&2; exit 1 ;;
+esac

rig/ctrl/setup.sh

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# Prepare a machine to run rig, and say plainly what worked, what was already
+# done, and what is left for a human.
+#
+# This is the grouped entry point: `make setup`. Every step is idempotent and
+# independently checked, so running it twice is safe and running it on a
+# half-configured machine finishes the job rather than starting over.
+#
+# It deliberately does NOT abort on the first failure. A setup script that dies
+# at step 2 hides the fact that steps 4 and 5 were also going to fail — and on
+# an unfamiliar machine, the full picture is the whole point. Failures are
+# collected and reported together, and the exit code reflects the worst outcome.
+#
+# The same script runs inside a fresh throwaway distro (newbox), so the
+# provisioning path and the everyday path cannot drift apart.
+#
+# Usage:
+#   setup.sh                  # host checks + the dev toolchain
+#   setup.sh core             # kubectl and jq only — no cluster tooling
+#   setup.sh --share-docker   # ...and offer this distro's Docker to others
+#   setup.sh --cluster        # ...and bring the cluster up
+set -euo pipefail
+cd "$(dirname "$0")"
+
+source ./lib/config.sh
+load_config
+
+WITH_SHARE=0
+WITH_CLUSTER=0
+# Cluster tooling is not wanted everywhere: a managed or corporate-issued
+# machine may legitimately want kubectl and nothing that builds clusters.
+TIER=dev
+for a in "$@"; do
+    case "$a" in
+        core|dev)       TIER="$a" ;;
+        --share-docker) WITH_SHARE=1 ;;
+        --cluster)      WITH_CLUSTER=1 ;;
+        *) echo "unknown option: $a" >&2; exit 1 ;;
+    esac
+done
+
+if [ "$TIER" = "core" ] && [ "$WITH_CLUSTER" -eq 1 ]; then
+    echo "core tier installs no cluster tooling, so --cluster cannot work" >&2
+    exit 1
+fi
+
+# ── step framework ─────────────────────────────────────────────────────────
+# Statuses are deliberately distinct: "already" and "done" both mean success but
+# tell you very different things about the machine you are on.
+STEP_NAMES=()
+STEP_STATUS=()
+STEP_NOTE=()
+WORST=0
+
+record() {
+    STEP_NAMES+=("$1"); STEP_STATUS+=("$2"); STEP_NOTE+=("${3:-}")
+    # Only a genuine failure is a non-zero exit. "manual" means the machine is
+    # fine and you have something to do — reporting that as an error makes the
+    # whole run look broken and trains people to ignore the output.
+    [ "$2" = "fail" ] && WORST=1 || true
+    local mark
+    case "$2" in
+        already) mark="  ok  " ;;
+        done)    mark=" done " ;;
+        skip)    mark=" skip " ;;
+        manual)  mark="MANUAL" ;;
+        fail)    mark=" FAIL " ;;
+    esac
+    printf "[%s] %-22s %s\n" "$mark" "$1" "${3:-}"
+}
+
+# ── steps ──────────────────────────────────────────────────────────────────
+
+step_host() {
+    local out
+    if ! out=$(bash ./wizard.sh detect 2>&1); then
+        record host fail "detection failed"
+        return
+    fi
+    # Anything the wizard flagged with '!' needs a human; surface the count here
+    # and the detail below rather than burying it.
+    local warns; warns=$(echo "$out" | grep -c '^\s*!' || true)
+    HOST_DETAIL="$out"
+    if [ "$warns" -gt 0 ]; then
+        record host manual "$warns item(s) need attention — see below"
+    else
+        record host already "no problems detected"
+    fi
+}
+
+step_toolchain() {
+    local want="kubectl jq"
+    [ "$TIER" = "dev" ] && want="$want kind tilt"
+
+    local missing=""
+    for b in $want; do
+        command -v "$b" >/dev/null 2>&1 || missing="$missing $b"
+    done
+
+    if [ -z "$missing" ]; then
+        record toolchain already "$TIER: $want"
+        return
+    fi
+
+    if bash ./wizard.sh install "$TIER" >/tmp/rig-deps.$$ 2>&1; then
+        local still=""
+        for b in $want; do
+            [ -x "${OUT_BIN:-$HOME/.local/bin}/$b" ] || still="$still $b"
+        done
+        if [ -n "$still" ]; then
+            record toolchain fail "still missing:$still (see /tmp/rig-deps.$$)"
+        else
+            record toolchain done "$TIER, installed:$missing"
+            rm -f "/tmp/rig-deps.$$"
+        fi
+    else
+        record toolchain fail "install failed — see /tmp/rig-deps.$$"
+    fi
+}
+
+step_path() {
+    local bin="${OUT_BIN:-$HOME/.local/bin}"
+    case ":$PATH:" in
+        *":$bin:"*) ;;
+        *) record path manual "add to ~/.bashrc:  export PATH=\"$bin:\$PATH\""; return ;;
+    esac
+    if grep -qs "$bin" "$HOME/.bashrc" "$HOME/.profile" 2>/dev/null; then
+        record path already "$bin on PATH and persisted"
+    else
+        record path manual "on PATH now, but not persisted in ~/.bashrc"
+    fi
+}
+
+step_docker() {
+    if ! command -v docker >/dev/null 2>&1; then
+        record docker fail "no docker cli — this is the one prerequisite rig cannot install"
+        return
+    fi
+    if docker info >/dev/null 2>&1; then
+        record docker already "$(docker version --format '{{.Server.Version}}' 2>/dev/null)"
+    else
+        record docker fail "daemon unreachable (in the docker group? logged out and back in?)"
+    fi
+}
+
+step_share_docker() {
+    if [ "$WITH_SHARE" -ne 1 ]; then
+        record docker-share skip "not requested (--share-docker)"
+        return
+    fi
+    if ! grep -qi microsoft /proc/version 2>/dev/null; then
+        record docker-share skip "not WSL — sharing only applies between WSL distros"
+        return
+    fi
+    if [ -f /etc/systemd/system/docker.service.d/10-rig-shared-socket.conf ]; then
+        record docker-share already "this distro is offering its Docker to others"
+        return
+    fi
+    # Needs root, and asking mid-script is worse than telling the user the
+    # single command to run.
+    if [ "$(id -u)" -ne 0 ] && ! sudo -n true 2>/dev/null; then
+        record docker-share manual "run:  sudo bash ctrl/dockerhost.sh share"
+        return
+    fi
+    if sudo bash ./dockerhost.sh share >/tmp/rig-share.$$ 2>&1; then
+        record docker-share done "this distro now owns the shared Docker"
+        rm -f "/tmp/rig-share.$$"
+    else
+        record docker-share fail "see /tmp/rig-share.$$"
+    fi
+}
+
+step_ports() {
+    local busy=""
+    for entry in "HTTP:$HTTP_PORT" "HTTPS:$HTTPS_PORT" "TILT:$TILT_PORT" "REGISTRY:$REGISTRY_PORT"; do
+        local p="${entry#*:}"
+        if command -v ss >/dev/null 2>&1 && ss -ltn "sport = :$p" 2>/dev/null | grep -q LISTEN; then
+            busy="$busy ${entry%%:*}($p)"
+        fi
+    done
+    if [ -n "$busy" ]; then
+        record ports fail "in use:$busy — override in ctrl/.env or rename the directory"
+    else
+        record ports already "$HTTP_PORT-$REGISTRY_PORT free"
+    fi
+}
+
+step_cluster() {
+    if [ "$TIER" = "core" ]; then
+        record cluster skip "core tier — no cluster tooling on this machine"
+        return
+    fi
+    if [ "$WITH_CLUSTER" -ne 1 ]; then
+        record cluster skip "not requested (--cluster)"
+        return
+    fi
+    if kind get clusters 2>/dev/null | grep -qx "$CLUSTER"; then
+        record cluster already "'$CLUSTER' exists"
+        return
+    fi
+    if bash ./cluster.sh up >/tmp/rig-cluster.$$ 2>&1; then
+        record cluster done "'$CLUSTER' created"
+        rm -f "/tmp/rig-cluster.$$"
+    else
+        record cluster fail "see /tmp/rig-cluster.$$"
+    fi
+}
+
+# ── run ────────────────────────────────────────────────────────────────────
+
+echo "setting up '$CLUSTER'"
+echo
+HOST_DETAIL=""
+step_host
+step_toolchain
+step_path
+step_docker
+step_share_docker
+step_ports
+step_cluster
+
+echo
+if [ -n "$HOST_DETAIL" ]; then
+    echo "host detail"
+    echo "$HOST_DETAIL" | sed 's/^/  /'
+    echo
+fi
+
+# Repeat only what still needs action, so the tail of the output is a to-do list
+# rather than a transcript.
+outstanding=0
+for i in "${!STEP_NAMES[@]}"; do
+    case "${STEP_STATUS[$i]}" in
+        fail|manual)
+            [ "$outstanding" -eq 0 ] && echo "outstanding:"
+            outstanding=1
+            printf "  %-8s %-16s %s\n" "${STEP_STATUS[$i]}" "${STEP_NAMES[$i]}" "${STEP_NOTE[$i]}"
+            ;;
+    esac
+done
+
+if [ "$outstanding" -eq 0 ]; then
+    echo "ready. next:  make cluster up && make docs"
+else
+    echo
+    echo "(nothing was aborted — every step ran so the list above is complete)"
+fi
+
+exit "$WORST"

rig/ctrl/station.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Station check: is this workstation ready to run rig?
+#
+# Reports and instructs; never silently fixes anything. Everything it finds is
+# either already fine, or something a human has to decide on.
+#
+# Runs the wizard's host detection in a container when Docker is the only thing
+# installed, or directly when the toolchain is already present. Then adds the
+# checks that need this repo's config: profile sanity, CA trust, port clashes.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+WIZARD_IMAGE="${WIZARD_IMAGE:-$(basename "$(cd .. && pwd)")-wizard}"
+
+# Host detection. Prefer running it bare — it needs no dependencies beyond
+# coreutils — and fall back to the container only if this shell can't.
+bash ./wizard.sh detect
+
+# ── repo-level checks ──────────────────────────────────────────────────────
+
+source ./lib/config.sh
+load_config
+
+echo
+echo "config"
+echo "  profile     ${PROFILE_NAME}  (nodes=${NODES} audit=${AUDIT})"
+echo "  cluster     ${CLUSTER}  (context ${KUBECONTEXT})"
+echo "  registry    ${REGISTRY_MODE}"
+echo "  ingress     ${INGRESS_MODE}"
+
+if [ ! -f ./.env ]; then
+    echo "  ! ctrl/.env missing — copy it:  cp ctrl/.env.example ctrl/.env"
+fi
+
+# A 3-node profile on a box that's already full is the most common first
+# failure, and it presents as pods stuck Pending rather than anything obvious.
+avail=$(awk '/^MemAvailable:/{printf "%d", $2/1024/1024}' /proc/meminfo)
+need=$((NODES * 2))
+if [ "$avail" -lt "$need" ]; then
+    echo "  ! profile '${PROFILE_NAME}' wants ~${need} GB, ${avail} GB available"
+    echo "    'make cluster list' shows what else is running; 'make cluster free' stops it"
+fi
+
+# The CA reaches three places and only one of them is ours. Report the other two.
+if [ -n "${REGISTRY_CA_FILE:-}" ]; then
+    echo
+    echo "registry CA"
+    if [ ! -r "$REGISTRY_CA_FILE" ]; then
+        echo "  ! REGISTRY_CA_FILE not readable: $REGISTRY_CA_FILE"
+    else
+        echo "  file        $REGISTRY_CA_FILE"
+        host="${REGISTRY_REMOTE_URL#*://}"; host="${host%%/*}"
+        if [ -n "$host" ] && [ ! -f "/etc/docker/certs.d/${host}/ca.crt" ]; then
+            echo "  ! the HOST docker daemon does not trust it yet:"
+            echo "      sudo mkdir -p /etc/docker/certs.d/${host}"
+            echo "      sudo cp ${REGISTRY_CA_FILE} /etc/docker/certs.d/${host}/ca.crt"
+            echo "    (kind nodes are handled by registry.sh; in-cluster clients are the workload's job)"
+        fi
+    fi
+fi
+
+# Host ports this environment will try to bind. Checked before cluster creation
+# because docker reports a clash halfway through, as an opaque
+# "failed to bind host port ...: address already in use".
+echo
+echo "ports  (block derived from the directory name — see 'make ports')"
+
+port_busy() {
+    if command -v ss >/dev/null 2>&1; then
+        ss -ltn "sport = :$1" 2>/dev/null | grep -q LISTEN && return 0 || return 1
+    fi
+    # iproute2 is absent from a minimal Debian, so fall back to procfs rather
+    # than silently reporting everything as free.
+    local hex; hex=$(printf ':%04X' "$1")
+    grep -qi "^ *[0-9]*: [0-9A-F]*$hex " /proc/net/tcp /proc/net/tcp6 2>/dev/null
+}
+
+# A port held by THIS environment's own cluster is not a clash — it is the thing
+# working. Reporting it as a problem every time the cluster is up would train
+# people to ignore this section, which is the opposite of the point.
+# Extract with a second grep rather than `tr -d ':->'`: in tr, ':->' is the
+# character RANGE ':' to '>', which does not contain '-', so the trailing dash
+# survives and nothing ever matches.
+ours=$(docker ps --filter "label=io.x-k8s.kind.cluster=${CLUSTER}" \
+        --format '{{.Ports}}' 2>/dev/null | tr ',' '\n' \
+        | grep -oE ':[0-9]+->' | grep -oE '[0-9]+' || true)
+
+clash=0
+for entry in "HTTP:${HTTP_PORT}" "HTTPS:${HTTPS_PORT}" \
+             "TILT:${TILT_PORT}" "REGISTRY:${REGISTRY_PORT}"; do
+    name="${entry%%:*}"; p="${entry#*:}"
+    [ -n "$p" ] || continue
+    if ! port_busy "$p"; then
+        printf "    %-9s %-6s free\n" "$name" "$p"
+    elif echo "$ours" | grep -qx "$p"; then
+        printf "    %-9s %-6s in use by this environment's cluster\n" "$name" "$p"
+    else
+        printf "  ! %-9s %-6s IN USE by something else\n" "$name" "$p"
+        clash=1
+    fi
+done
+
+if [ "$clash" -eq 1 ]; then
+    echo "    override the clashing one in ctrl/.env, e.g.  HTTP_PORT=21080"
+    echo "    (or rename this directory — the whole block follows the name)"
+fi

rig/ctrl/versions.env

@@ -0,0 +1,54 @@
+# Pinned toolchain — the single manifest the wizard installs from.
+# Every entry is a single binary; none of them needs an apt repo.
+#   kubectl  fully static
+#   kind     libc only
+#   tilt     libc + libstdc++ + libgcc (present in base Debian)
+#   jq       upstream static build (Debian's is linked against libjq/libonig)
+#
+# Checksums are the upstream-published SHA256 of the linux/amd64 artifact.
+# To bump: change the version, then re-run `bash ctrl/versions-refresh.sh` and
+# commit the result — never hand-edit a checksum.
+
+KIND_VERSION=v0.32.0
+KIND_SHA256=50030de23cf40a18505f20426f6a8506bedf13c6e509244bd1fa9463721b0f54
+KIND_URL=https://github.com/kubernetes-sigs/kind/releases/download/${KIND_VERSION}/kind-linux-amd64
+
+KUBECTL_VERSION=v1.36.3
+KUBECTL_SHA256=ebbd080e7c2e275093b55915722043257eb24004363e20acb3c4d71919f88336
+KUBECTL_URL=https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl
+
+TILT_VERSION=0.37.6
+TILT_SHA256=e9672b8a18d43501f35dcfe98465969a7db0e436b36cf0c50c7e6f8d40de5fe6
+TILT_URL=https://github.com/tilt-dev/tilt/releases/download/v${TILT_VERSION}/tilt.${TILT_VERSION}.linux.x86_64.tar.gz
+
+JQ_VERSION=1.8.2
+JQ_SHA256=b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f
+JQ_URL=https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64
+
+# Node images shipped with KIND_VERSION above, pinned by digest so a kind upgrade
+# can never silently move the k8s version. Profiles select one via K8S_VERSION.
+# Older entries are kept deliberately: running a trailing-edge control plane is
+# part of simulating a legacy estate.
+NODE_IMAGE_v1_36=kindest/node:v1.36.1@sha256:3489c7674813ba5d8b1a9977baea8a6e553784dab7b84759d1014dbd78f7ebd5
+NODE_IMAGE_v1_35=kindest/node:v1.35.5@sha256:ce977ae6d65918d0b58a5f8b5e940429c2ce42fa3a5619ec2bbc60b949c0ac95
+NODE_IMAGE_v1_34=kindest/node:v1.34.8@sha256:02722c2dedddcfc00febf5d27fbeb9b7b2c14294c82109ff4a85d89ac9ba3256
+NODE_IMAGE_v1_33=kindest/node:v1.33.12@sha256:3f5c8443c620245e4d355cfe09e96a91ead32ceaa569d3f1ca9edf0cb2fe2ff4
+
+# Images pulled at runtime (registry, mocks). Pinned by tag; the registry mode
+# decides where they are pulled FROM.
+REGISTRY_IMAGE=registry:2
+STUB_IMAGE=python:3.12-slim
+
+# Addons, installed by ctrl/addons/<name>.sh when listed in a profile's ADDONS.
+CERT_MANAGER_VERSION=v1.21.1
+METRICS_SERVER_VERSION=v0.9.0
+METALLB_VERSION=v0.16.0
+
+# Dependency containers. These mirror soleprint's cabinets
+# (soleprint/station/cabinets/), so a room that declares postgres gets the same
+# thing whether it runs on compose or in the cluster. Pinned by tag rather than
+# digest because they are ordinary upstream images with no supply chain claim
+# attached — bump freely, and preload them for the offline profile.
+POSTGRES_IMAGE=postgres:16-alpine
+REDIS_IMAGE=redis:7-alpine
+AIRFLOW_IMAGE=apache/airflow:2.10.4

rig/ctrl/wizard.sh

@@ -0,0 +1,381 @@
+#!/usr/bin/env bash
+# The installation wizard: detect the host, install a pinned toolchain onto it,
+# then report what it could not do. It never runs the cluster and never mutates
+# the host outside the directories mounted into it.
+#
+# Usage (normally via `make station` / `make deps`, or directly):
+#   wizard.sh detect            # report host facts only, change nothing
+#   wizard.sh fetch [core|dev] [--to DIR]   # download + verify into DIR
+#   wizard.sh install [core|dev]            # detect, fetch, install, report
+#
+# Tiers: 'core' is kubectl + jq (talk to a cluster); 'dev' adds kind and tilt
+# Default is dev.
+#
+# Runs both inside the wizard container and bare on a host. Inside the
+# container, host files are read through $HOST_ROOT (mount / as :ro); bare, it
+# falls back to /.
+
+set -euo pipefail
+
+# Keep the caller's cwd so a relative --to resolves where the user expects,
+# not against ctrl/ once we've moved.
+INVOKED_FROM="$PWD"
+cd "$(dirname "$0")"
+
+source ./versions.env
+
+# Resolve a possibly-relative path against the caller's original directory.
+abspath() {
+    case "$1" in
+        /*) echo "$1" ;;
+        *)  echo "$INVOKED_FROM/$1" ;;
+    esac
+}
+
+OUT_BIN="${OUT_BIN:-$HOME/.local/bin}"
+HOST_ROOT="${HOST_ROOT:-/}"
+DEPS_SOURCE="${DEPS_SOURCE:-upstream}"
+DEPS_ARTIFACTORY_URL="${DEPS_ARTIFACTORY_URL:-}"
+BAKED_BIN="${BAKED_BIN:-/opt/rig/bin}"
+
+# Collected by detect(), printed by report_manual() at the very end.
+MANUAL=()
+
+# Host FILES (/etc/..., /mnt/c/...) must be read through the mount. Kernel-level
+# facts (kernel version, meminfo, inotify) are shared with the container, so the
+# container's own view is already the host's.
+host_file() {
+    local p="${1#/}"
+    if [ "$HOST_ROOT" != "/" ] && [ -e "$HOST_ROOT/$p" ]; then
+        echo "$HOST_ROOT/$p"
+    else
+        echo "/$p"
+    fi
+}
+
+# ── detect ─────────────────────────────────────────────────────────────────
+
+is_wsl() { grep -qi microsoft /proc/version 2>/dev/null; }
+
+detect() {
+    echo "host"
+    echo "  kernel      $(uname -r)"
+
+    local osr; osr=$(host_file /etc/os-release)
+    [ -r "$osr" ] && echo "  distro      $(sed -n 's/^PRETTY_NAME="\(.*\)"/\1/p' "$osr")"
+
+    local total_kb avail_kb
+    total_kb=$(awk '/^MemTotal:/{print $2}' /proc/meminfo)
+    avail_kb=$(awk '/^MemAvailable:/{print $2}' /proc/meminfo)
+    printf "  memory      %d GB total, %d GB available\n" \
+        $((total_kb / 1024 / 1024)) $((avail_kb / 1024 / 1024))
+
+    if [ $((avail_kb / 1024 / 1024)) -lt 4 ]; then
+        echo "  ! under 4 GB available — a multi-node profile will struggle."
+        echo "    'make cluster list' shows the others; 'make cluster free' stops them."
+    fi
+
+    detect_wsl
+    detect_docker
+    detect_inotify
+}
+
+detect_wsl() {
+    if ! is_wsl; then
+        echo "  platform    native linux"
+        return
+    fi
+
+    echo "  platform    WSL"
+
+    # systemd is off by default in WSL, and the ingress/DNS paths that use a
+    # host service need it. Enabling it requires a Windows-side restart, which
+    # cannot be issued from inside the distro.
+    local wc; wc=$(host_file /etc/wsl.conf)
+    if [ -r "$wc" ] && grep -qE '^\s*systemd\s*=\s*true' "$wc"; then
+        echo "  systemd     enabled in wsl.conf"
+    else
+        echo "  ! systemd not enabled in /etc/wsl.conf"
+        MANUAL+=("Enable systemd — add to /etc/wsl.conf:
+      [boot]
+      systemd=true
+  then from a WINDOWS terminal (not this shell):  wsl --shutdown")
+    fi
+
+    # WSL regenerates /etc/resolv.conf on every boot, which silently reverts any
+    # local DNS setup.
+    if [ -r "$wc" ] && grep -qE '^\s*generateResolvConf\s*=\s*false' "$wc"; then
+        echo "  resolv.conf pinned (generateResolvConf=false)"
+    else
+        echo "  - resolv.conf is WSL-generated; DNS_MODE=dnsmasq would be reverted on reboot"
+    fi
+
+    local wcfg
+    wcfg=$(ls "$HOST_ROOT"/mnt/c/Users/*/.wslconfig 2>/dev/null | head -1 || true)
+    if [ -n "$wcfg" ] && grep -qE '^\s*memory\s*=' "$wcfg"; then
+        echo "  wslconfig   memory set: $(grep -E '^\s*memory\s*=' "$wcfg" | tr -d ' ')"
+    else
+        MANUAL+=("Cap/raise the WSL VM memory — in %USERPROFILE%\\.wslconfig on Windows:
+      [wsl2]
+      memory=8GB
+  then from a WINDOWS terminal:  wsl --shutdown")
+    fi
+}
+
+detect_docker() {
+    # Reachability of the daemon is the real question, and the CLI is only how
+    # we ask it. Note that when this runs inside the wizard container, Docker
+    # necessarily exists on the host — otherwise nothing would be executing —
+    # so a missing CLI in here is a wizard packaging bug, not a host problem.
+    if ! command -v docker >/dev/null 2>&1; then
+        if [ -S /var/run/docker.sock ]; then
+            echo "  docker      socket present (no cli in this context)"
+        else
+            echo "  ! docker not found and no socket at /var/run/docker.sock"
+            MANUAL+=("Install Docker — the one true prerequisite:
+      sudo apt-get install -y docker.io && sudo usermod -aG docker \"\$USER\"
+  then log out and back in.")
+        fi
+        return
+    fi
+    if docker info >/dev/null 2>&1; then
+        echo "  docker      $(docker version --format '{{.Server.Version}}' 2>/dev/null)"
+        local n
+        n=$(docker ps --filter "label=io.x-k8s.kind.cluster" --format '{{.Names}}' 2>/dev/null | wc -l)
+        # Must be an `if`, not `[ ] && echo`: as the last statement in this
+        # function the latter returns 1 when the count is zero, and `set -e`
+        # then kills the caller. That is the fresh-machine case — no clusters
+        # yet — so the bug only ever shows up where it does most harm.
+        if [ "$n" -gt 0 ]; then
+            echo "  - $n kind node container(s) already running; see 'make cluster list'"
+        fi
+    else
+        echo "  ! docker cli present but the daemon is unreachable"
+        MANUAL+=("Start Docker, or add yourself to the docker group:
+      sudo usermod -aG docker \"\$USER\"   # then log out and back in")
+    fi
+}
+
+# kind and Tilt both watch large trees. WSL ships defaults (8192/128) far too low,
+# and the failure mode is silent: Tilt simply stops noticing file changes.
+detect_inotify() {
+    local w i
+    w=$(cat /proc/sys/fs/inotify/max_user_watches 2>/dev/null || echo 0)
+    i=$(cat /proc/sys/fs/inotify/max_user_instances 2>/dev/null || echo 0)
+    echo "  inotify     watches=$w instances=$i"
+
+    if [ "$w" -lt 524288 ] || [ "$i" -lt 512 ]; then
+        echo "  ! inotify limits are low — Tilt will silently stop noticing file changes"
+        MANUAL+=("Raise inotify limits (needs root on the host):
+      echo -e 'fs.inotify.max_user_watches=524288\\nfs.inotify.max_user_instances=512' \\
+        | sudo tee /etc/sysctl.d/99-rig.conf
+      sudo sysctl --system")
+    fi
+}
+
+# ── fetch ──────────────────────────────────────────────────────────────────
+
+# Resolve where a given artifact comes from, honouring DEPS_SOURCE.
+resolve_url() {
+    local upstream="$1"
+    case "$DEPS_SOURCE" in
+        upstream)    echo "$upstream" ;;
+        artifactory)
+            if [ -z "$DEPS_ARTIFACTORY_URL" ]; then
+                echo "DEPS_SOURCE=artifactory but DEPS_ARTIFACTORY_URL is empty" >&2
+                exit 1
+            fi
+            echo "${DEPS_ARTIFACTORY_URL%/}/$(basename "$upstream")"
+            ;;
+        *) echo "unsupported DEPS_SOURCE '$DEPS_SOURCE' for a download" >&2; exit 1 ;;
+    esac
+}
+
+verify() {
+    local file="$1" want="$2" name="$3" got
+    got=$(sha256sum "$file" | awk '{print $1}')
+    if [ "$got" != "$want" ]; then
+        echo "checksum mismatch for $name" >&2
+        echo "  expected $want" >&2
+        echo "  got      $got" >&2
+        exit 1
+    fi
+}
+
+# fetch_bin <name> <url> <sha256> <dest-dir>  — a bare binary
+fetch_bin() {
+    local name="$1" url="$2" sha="$3" dest="$4"
+    local tmp="$dest/.$name.tmp"
+    echo "  fetching $name"
+    curl -fsSL --retry 3 -o "$tmp" "$(resolve_url "$url")"
+    verify "$tmp" "$sha" "$name"
+    mv "$tmp" "$dest/$name"
+    chmod +x "$dest/$name"
+}
+
+# fetch_tgz <name> <url> <sha256> <dest-dir> <path-inside-archive> <strip>
+# Archive layouts differ — tilt's is flat (the binary at the root, strip=0),
+# others nest it a directory down — so the caller says which.
+fetch_tgz() {
+    local name="$1" url="$2" sha="$3" dest="$4" inner="$5" strip="$6"
+    local tmp="$dest/.$name.tgz"
+    echo "  fetching $name"
+    curl -fsSL --retry 3 -o "$tmp" "$(resolve_url "$url")"
+    verify "$tmp" "$sha" "$name"
+    # --no-same-owner: extracting as root would otherwise restore the uid/gid
+    # baked into the archive (some ship as uid 1001), leaving a binary the host
+    # user does not own.
+    tar -xzf "$tmp" -C "$dest" --strip-components="$strip" --no-same-owner "$inner"
+    rm -f "$tmp"
+    chmod +x "$dest/$name"
+}
+
+# The wizard runs as root so it can reach the docker socket, which means
+# everything it writes into a mounted volume lands root-owned and unusable from
+# the host. Hand it back to whoever owns the mount point (the host user created
+# that directory before mounting it).
+fix_ownership() {
+    local dir="$1"
+    [ -d "$dir" ] || return 0
+    local owner="${HOST_UID:-}:${HOST_GID:-}"
+    if [ "$owner" = ":" ]; then
+        owner=$(stat -c '%u:%g' "$dir")
+    fi
+    [ "$owner" = "0:0" ] && return 0
+    chown -R "$owner" "$dir" 2>/dev/null || true
+}
+
+# Two tiers, because not every machine should get cluster tooling.
+#
+#   core  kubectl, jq — talk to a cluster someone else runs. Nothing that
+#         creates one. Appropriate on a managed or corporate-issued machine
+#         where development tools are not wanted by default.
+#   dev   core plus kind and tilt — build clusters and hot-reload into them.
+#
+# The split exists because "install the toolchain" is not one decision: on a
+# managed workspace the right answer is kubectl and nothing else.
+CORE_TOOLS="kubectl jq"
+# No helm: every addon installs with `kubectl apply -f <url>`, so nothing here
+# has ever invoked it. Add it back the day something actually needs a chart.
+DEV_TOOLS="kind tilt"
+
+fetch() {
+    local dest="$OUT_BIN" tier="${TIER:-dev}"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --to)      dest="$2"; shift 2 ;;
+            core|dev)  tier="$1"; shift ;;
+            *)         echo "unknown argument: $1" >&2; exit 1 ;;
+        esac
+    done
+    dest="$(abspath "$dest")"
+    mkdir -p "$dest"
+    TIER="$tier"
+
+    if [ "$DEPS_SOURCE" = "baked" ]; then
+        echo "installing baked binaries from $BAKED_BIN"
+        cp -a "$BAKED_BIN"/. "$dest"/
+        fix_ownership "$dest"
+        return
+    fi
+
+    echo "fetching '$tier' toolchain (source: $DEPS_SOURCE)"
+    fetch_bin kubectl "$KUBECTL_URL" "$KUBECTL_SHA256" "$dest"
+    fetch_bin jq      "$JQ_URL"      "$JQ_SHA256"      "$dest"
+    if [ "$tier" = "dev" ]; then
+        fetch_bin kind "$KIND_URL" "$KIND_SHA256" "$dest"
+        fetch_tgz tilt "$TILT_URL" "$TILT_SHA256" "$dest" tilt 0
+    fi
+
+    fix_ownership "$dest"
+    # kind writes the kubeconfig as root too; hand that back as well when it's
+    # a mounted host directory rather than container-local state.
+    fix_ownership "${KUBE_DIR:-/out/kube}"
+}
+
+# ── install ────────────────────────────────────────────────────────────────
+
+report_manual() {
+    echo
+    if [ ${#MANUAL[@]} -eq 0 ]; then
+        echo "nothing left to do by hand."
+        return
+    fi
+    echo "host actions the wizard cannot perform (${#MANUAL[@]}):"
+    echo
+    local n=1
+    for m in "${MANUAL[@]}"; do
+        echo "  $n. $m"
+        echo
+        n=$((n + 1))
+    done
+}
+
+# Installing into a directory that sits early in PATH silently replaces whatever
+# the machine was already using — which on a shared or client machine can break
+# unrelated work (kubectl more than one minor away from a cluster is the common
+# one). Say so; never decide it for them.
+tier_tools() { [ "$1" = "core" ] && echo "$CORE_TOOLS" || echo "$CORE_TOOLS $DEV_TOOLS"; }
+
+warn_shadowing() {
+    local b existing shadowed="" tier="${1:-dev}"
+    for b in $(tier_tools "$tier"); do
+        [ -x "$OUT_BIN/$b" ] || continue
+        # Where would this resolve if OUT_BIN weren't in the way?
+        existing=$(PATH=$(echo "$PATH" | tr ':' '\n' | grep -vx "$OUT_BIN" | paste -sd:) \
+                   command -v "$b" 2>/dev/null || true)
+        [ -n "$existing" ] || continue
+        [ "$existing" = "$OUT_BIN/$b" ] && continue
+        shadowed+="      $b  $existing"$'\n'
+    done
+
+    [ -n "$shadowed" ] || return 0
+
+    case ":${PATH}:" in
+        *":$OUT_BIN:"*) ;;
+        *) return 0 ;;   # not on PATH yet, so nothing is being shadowed
+    esac
+
+    echo
+    echo "  ! these were already installed elsewhere and are now shadowed by $OUT_BIN:"
+    printf '%s' "$shadowed"
+    echo "    Other projects on this machine will pick up the new versions."
+    MANUAL+=("Decide which toolchain wins. To keep the previous one, remove what
+  was just installed:
+      rm -f $(for b in $(tier_tools "$tier"); do printf '%s ' "$OUT_BIN/$b"; done)
+  Or install somewhere private instead:
+      OUT_BIN=\$PWD/def/bin make deps   # then put that dir first in PATH")
+}
+
+install() {
+    local tier="${1:-dev}"
+    detect
+    echo
+    fetch "$tier"
+    echo
+    echo "installed to $OUT_BIN ($tier):"
+    for b in $(tier_tools "$tier"); do
+        [ -x "$OUT_BIN/$b" ] && echo "  $b"
+    done
+    if [ "$tier" = "core" ]; then
+        echo "  (no kind/tilt — 'make deps dev' adds them)"
+    fi
+    warn_shadowing "$tier"
+
+    case ":${PATH}:" in
+        *":$OUT_BIN:"*) ;;
+        *) MANUAL+=("Put the toolchain on your PATH — add to ~/.bashrc:
+      export PATH=\"${OUT_BIN}:\$PATH\"") ;;
+    esac
+
+    report_manual
+}
+
+# ── main ───────────────────────────────────────────────────────────────────
+
+case "${1:-install}" in
+    detect)  detect; report_manual ;;
+    fetch)   shift; fetch "$@" ;;
+    install) shift; install "${1:-dev}" ;;
+    *)       echo "usage: $0 [detect|fetch|install]" >&2; exit 1 ;;
+esac

rig/docs/graphs/01-install.dot

@@ -0,0 +1,47 @@
+digraph rig_install {
+    rankdir=LR
+    bgcolor="#0a0e17"
+    fontname="Helvetica"
+    node [fontname="Helvetica" fontsize=11 style=filled color="#1e2a4a" fontcolor="#e8eaf0" shape=box]
+    edge [fontname="Helvetica" fontsize=9 fontcolor="#8892a8" color="#4a5568"]
+
+    label="Installation — the only host prerequisite is Docker"
+    labelloc=t
+    fontsize=16
+    fontcolor="#0066ff"
+
+    subgraph cluster_host {
+        label="Your machine"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        docker  [label="Docker\n(the one prerequisite)" fillcolor="#1a1a3a" fontcolor="#0066ff" shape=octagon]
+        bin     [label="~/.local/bin\nkind · kubectl · tilt\njq" fillcolor="#121829" shape=cylinder]
+    }
+
+    subgraph cluster_wizard {
+        label="Installer container (transient)"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        wizard  [label="wizard\ncurl · jq · python · graphviz" fillcolor="#121829"]
+        detect  [label="detect host\nWSL · memory · inotify · docker" fillcolor="#121829"]
+        fetch   [label="fetch + verify\nSHA256, pinned versions" fillcolor="#121829"]
+    }
+
+    upstream [label="upstream\nreleases / corporate mirror" fillcolor="#1a3a1a" fontcolor="#00c853" shape=octagon]
+    report   [label="report what it\nCANNOT do" fillcolor="#3a1a1a" fontcolor="#ffc107"]
+
+    docker  -> wizard  [label="docker run"]
+    wizard  -> detect
+    detect  -> fetch
+    fetch   -> upstream [label="pinned + checksummed" color="#00c853"]
+    fetch   -> bin      [label="install"]
+    detect  -> report   [style=dashed label="sudo / Windows-side steps" color="#ffc107"]
+
+    // The container is gone after this; nothing depends on it at run time.
+    wizard -> gone [style=dotted label="exits"]
+    gone [label="(container discarded)" fillcolor="#0a0e17" fontcolor="#4a5568" color="#1e2a4a" style="filled,dashed"]
+}

rig/docs/graphs/01-install.svg

@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: rig_install Pages: 1 -->
+<svg width="1145pt" height="287pt"
+ viewBox="0.00 0.00 1145.00 287.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 283.29)">
+<title>rig_install</title>
+<polygon fill="#0a0e17" stroke="none" points="-4,4 -4,-283.29 1141.06,-283.29 1141.06,4 -4,4"/>
+<text xml:space="preserve" text-anchor="middle" x="568.53" y="-260.09" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#0066ff">Installation — the only host prerequisite is Docker</text>
+<g id="clust1" class="cluster">
+<title>cluster_host</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="898.49,-8 898.49,-190 1123.82,-190 1123.82,-8 898.49,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-170.8" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Your machine</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_wizard</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="8,-95 8,-175 745.5,-175 745.5,-95 8,-95"/>
+<text xml:space="preserve" text-anchor="middle" x="376.75" y="-155.8" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Installer container (transient)</text>
+</g>
+<!-- docker -->
+<g id="node1" class="node">
+<title>docker</title>
+<polygon fill="#1a1a3a" stroke="#1e2a4a" points="1115.82,-31.9 1115.82,-54.1 1054.51,-69.79 967.8,-69.79 906.49,-54.1 906.49,-31.9 967.8,-16.21 1054.51,-16.21 1115.82,-31.9"/>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-46.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#0066ff">Docker</text>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-32.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#0066ff">(the one prerequisite)</text>
+</g>
+<!-- wizard -->
+<g id="node3" class="node">
+<title>wizard</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="181.25,-139 16,-139 16,-103 181.25,-103 181.25,-139"/>
+<text xml:space="preserve" text-anchor="middle" x="98.62" y="-124.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">wizard</text>
+<text xml:space="preserve" text-anchor="middle" x="98.62" y="-110.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">curl · jq · python · graphviz</text>
+</g>
+<!-- docker&#45;&gt;wizard -->
+<g id="edge1" class="edge">
+<title>docker&#45;&gt;wizard</title>
+<path fill="none" stroke="#4a5568" d="M906.12,-45.7C757.47,-50.51 475.98,-63.12 238.25,-94 223.38,-95.93 207.7,-98.48 192.45,-101.24"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="192.13,-97.74 182.93,-103.01 193.4,-104.63 192.13,-97.74"/>
+<text xml:space="preserve" text-anchor="middle" x="506.62" y="-74.39" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">docker run</text>
+</g>
+<!-- bin -->
+<g id="node2" class="node">
+<title>bin</title>
+<path fill="#121829" stroke="#1e2a4a" d="M1069.03,-148.28C1069.03,-151.63 1043.09,-154.34 1011.15,-154.34 979.22,-154.34 953.28,-151.63 953.28,-148.28 953.28,-148.28 953.28,-93.72 953.28,-93.72 953.28,-90.37 979.22,-87.66 1011.15,-87.66 1043.09,-87.66 1069.03,-90.37 1069.03,-93.72 1069.03,-93.72 1069.03,-148.28 1069.03,-148.28"/>
+<path fill="none" stroke="#1e2a4a" d="M1069.03,-148.28C1069.03,-144.94 1043.09,-142.22 1011.15,-142.22 979.22,-142.22 953.28,-144.94 953.28,-148.28"/>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-130.8" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">~/.local/bin</text>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-117.3" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">kind · kubectl · tilt</text>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-103.8" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">jq</text>
+</g>
+<!-- detect -->
+<g id="node4" class="node">
+<title>detect</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="429,-139 238.25,-139 238.25,-103 429,-103 429,-139"/>
+<text xml:space="preserve" text-anchor="middle" x="333.62" y="-124.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">detect host</text>
+<text xml:space="preserve" text-anchor="middle" x="333.62" y="-110.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">WSL · memory · inotify · docker</text>
+</g>
+<!-- wizard&#45;&gt;detect -->
+<g id="edge2" class="edge">
+<title>wizard&#45;&gt;detect</title>
+<path fill="none" stroke="#4a5568" d="M181.44,-121C195.97,-121 211.28,-121 226.37,-121"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="226.33,-124.5 236.33,-121 226.33,-117.5 226.33,-124.5"/>
+</g>
+<!-- gone -->
+<g id="node8" class="node">
+<title>gone</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="400.5,-47 266.75,-47 266.75,-11 400.5,-11 400.5,-47"/>
+<text xml:space="preserve" text-anchor="middle" x="333.62" y="-25.3" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#4a5568">(container discarded)</text>
+</g>
+<!-- wizard&#45;&gt;gone -->
+<g id="edge7" class="edge">
+<title>wizard&#45;&gt;gone</title>
+<path fill="none" stroke="#4a5568" stroke-dasharray="1,5" d="M119.29,-102.62C138.26,-86 168.54,-62.29 199.25,-49.75 216.76,-42.6 236.49,-37.9 255.29,-34.81"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="255.67,-38.29 265.04,-33.35 254.64,-31.37 255.67,-38.29"/>
+<text xml:space="preserve" text-anchor="middle" x="209.75" y="-52.45" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">exits</text>
+</g>
+<!-- fetch -->
+<g id="node5" class="node">
+<title>fetch</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="737.5,-139 584.25,-139 584.25,-103 737.5,-103 737.5,-139"/>
+<text xml:space="preserve" text-anchor="middle" x="660.88" y="-124.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">fetch + verify</text>
+<text xml:space="preserve" text-anchor="middle" x="660.88" y="-110.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">SHA256, pinned versions</text>
+</g>
+<!-- detect&#45;&gt;fetch -->
+<g id="edge3" class="edge">
+<title>detect&#45;&gt;fetch</title>
+<path fill="none" stroke="#4a5568" d="M429.14,-121C474.43,-121 528.32,-121 572.63,-121"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="572.46,-124.5 582.46,-121 572.46,-117.5 572.46,-124.5"/>
+</g>
+<!-- report -->
+<g id="node7" class="node">
+<title>report</title>
+<polygon fill="#3a1a1a" stroke="#1e2a4a" points="706.75,-219 615,-219 615,-183 706.75,-183 706.75,-219"/>
+<text xml:space="preserve" text-anchor="middle" x="660.88" y="-204.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffc107">report what it</text>
+<text xml:space="preserve" text-anchor="middle" x="660.88" y="-190.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffc107">CANNOT do</text>
+</g>
+<!-- detect&#45;&gt;report -->
+<g id="edge6" class="edge">
+<title>detect&#45;&gt;report</title>
+<path fill="none" stroke="#ffc107" stroke-dasharray="5,2" d="M409.65,-139.45C468.85,-154.02 550.13,-174.01 603.78,-187.2"/>
+<polygon fill="#ffc107" stroke="#ffc107" points="602.77,-190.56 613.32,-189.55 604.45,-183.76 602.77,-190.56"/>
+<text xml:space="preserve" text-anchor="middle" x="506.62" y="-180.06" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">sudo / Windows&#45;side steps</text>
+</g>
+<!-- fetch&#45;&gt;bin -->
+<g id="edge5" class="edge">
+<title>fetch&#45;&gt;bin</title>
+<path fill="none" stroke="#4a5568" d="M737.88,-121C798.58,-121 882.9,-121 941.56,-121"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="941.43,-124.5 951.43,-121 941.43,-117.5 941.43,-124.5"/>
+<text xml:space="preserve" text-anchor="middle" x="811.38" y="-123.7" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">install</text>
+</g>
+<!-- upstream -->
+<g id="node6" class="node">
+<title>upstream</title>
+<polygon fill="#1a3a1a" stroke="#1e2a4a" points="1137.06,-213.9 1137.06,-236.1 1063.3,-251.79 959,-251.79 885.25,-236.1 885.25,-213.9 959,-198.21 1063.3,-198.21 1137.06,-213.9"/>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-228.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">upstream</text>
+<text xml:space="preserve" text-anchor="middle" x="1011.15" y="-214.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">releases / corporate mirror</text>
+</g>
+<!-- fetch&#45;&gt;upstream -->
+<g id="edge4" class="edge">
+<title>fetch&#45;&gt;upstream</title>
+<path fill="none" stroke="#00c853" d="M714.8,-139.5C759.85,-154.95 826.43,-177.11 885.25,-194 894.79,-196.74 904.78,-199.46 914.78,-202.09"/>
+<polygon fill="#00c853" stroke="#00c853" points="913.59,-205.4 924.15,-204.52 915.35,-198.62 913.59,-205.4"/>
+<text xml:space="preserve" text-anchor="middle" x="811.38" y="-191.36" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">pinned + checksummed</text>
+</g>
+</g>
+</svg>

rig/docs/graphs/02-environment.dot

@@ -0,0 +1,54 @@
+digraph rig_environment {
+    rankdir=TB
+    bgcolor="#0a0e17"
+    fontname="Helvetica"
+    node [fontname="Helvetica" fontsize=11 style=filled color="#1e2a4a" fontcolor="#e8eaf0" shape=box]
+    edge [fontname="Helvetica" fontsize=9 fontcolor="#8892a8" color="#4a5568"]
+
+    label="One environment per directory — copies never collide"
+    labelloc=t
+    fontsize=16
+    fontcolor="#0066ff"
+
+    dirname [label="directory name\ne.g. acmebank/" fillcolor="#1f6feb" fontcolor="#ffffff" shape=octagon]
+
+    subgraph cluster_derived {
+        label="Everything below is derived from it"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        cname   [label="cluster name\nacmebank" fillcolor="#121829"]
+        ctx     [label="kubectl context\nkind-acmebank" fillcolor="#121829"]
+        img     [label="image tag\nacmebank-wizard" fillcolor="#121829"]
+        ports   [label="port block\n21300–21309" fillcolor="#121829"]
+        reg     [label="registry container\nacmebank-registry" fillcolor="#121829"]
+    }
+
+    subgraph cluster_config {
+        label="Configuration — weakest first, later wins"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        versions [label="versions.env\npinned toolchain" fillcolor="#121829"]
+        profile  [label="env.d/<profile>.env\nnodes · CNI · audit · addons" fillcolor="#121829"]
+        localenv [label="ctrl/.env\nsecrets, overrides" fillcolor="#121829"]
+        shell    [label="the environment\nPROFILE=client make …" fillcolor="#1a3a1a" fontcolor="#00c853"]
+    }
+
+    dirname -> cname
+    dirname -> ctx
+    dirname -> img
+    dirname -> ports
+    dirname -> reg
+
+    versions -> profile  [label="overridden by"]
+    profile  -> localenv [label="overridden by"]
+    localenv -> shell    [label="overridden by" color="#00c853"]
+
+    cluster [label="kind cluster" fillcolor="#1a1a3a" fontcolor="#0066ff" shape=octagon]
+    cname -> cluster
+    ports -> cluster
+    shell -> cluster [style=dashed]
+}

rig/docs/graphs/02-environment.svg

@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: rig_environment Pages: 1 -->
+<svg width="971pt" height="481pt"
+ viewBox="0.00 0.00 971.00 481.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 476.83)">
+<title>rig_environment</title>
+<polygon fill="#0a0e17" stroke="none" points="-4,4 -4,-476.83 967,-476.83 967,4 -4,4"/>
+<text xml:space="preserve" text-anchor="middle" x="481.5" y="-453.63" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#0066ff">One environment per directory — copies never collide</text>
+<g id="clust1" class="cluster">
+<title>cluster_derived</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="8,-65 8,-144.5 605,-144.5 605,-65 8,-65"/>
+<text xml:space="preserve" text-anchor="middle" x="306.5" y="-125.3" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Everything below is derived from it</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_config</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="613,-65 613,-437.33 955,-437.33 955,-65 613,-65"/>
+<text xml:space="preserve" text-anchor="middle" x="784" y="-418.13" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Configuration — weakest first, later wins</text>
+</g>
+<!-- dirname -->
+<g id="node1" class="node">
+<title>dirname</title>
+<polygon fill="#1f6feb" stroke="#1e2a4a" points="375.11,-197.44 375.11,-219.63 329.94,-235.33 266.06,-235.33 220.89,-219.63 220.89,-197.44 266.06,-181.75 329.94,-181.75 375.11,-197.44"/>
+<text xml:space="preserve" text-anchor="middle" x="298" y="-211.59" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffffff">directory name</text>
+<text xml:space="preserve" text-anchor="middle" x="298" y="-198.09" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffffff">e.g. acmebank/</text>
+</g>
+<!-- cname -->
+<g id="node2" class="node">
+<title>cname</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="104,-109 16,-109 16,-73 104,-73 104,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="60" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">cluster name</text>
+<text xml:space="preserve" text-anchor="middle" x="60" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">acmebank</text>
+</g>
+<!-- dirname&#45;&gt;cname -->
+<g id="edge1" class="edge">
+<title>dirname&#45;&gt;cname</title>
+<path fill="none" stroke="#4a5568" d="M232.76,-193.05C195.81,-183.01 149.78,-167.28 113,-144.5 101.37,-137.29 90.31,-127.09 81.33,-117.6"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="84.04,-115.37 74.73,-110.3 78.85,-120.07 84.04,-115.37"/>
+</g>
+<!-- ctx -->
+<g id="node3" class="node">
+<title>ctx</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="223.75,-109 122.25,-109 122.25,-73 223.75,-73 223.75,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="173" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">kubectl context</text>
+<text xml:space="preserve" text-anchor="middle" x="173" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">kind&#45;acmebank</text>
+</g>
+<!-- dirname&#45;&gt;ctx -->
+<g id="edge2" class="edge">
+<title>dirname&#45;&gt;ctx</title>
+<path fill="none" stroke="#4a5568" d="M269.64,-181.32C248.71,-161.98 220.42,-135.83 199.86,-116.83"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="202.4,-114.41 192.68,-110.19 197.65,-119.55 202.4,-114.41"/>
+</g>
+<!-- img -->
+<g id="node4" class="node">
+<title>img</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="354,-109 242,-109 242,-73 354,-73 354,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="298" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">image tag</text>
+<text xml:space="preserve" text-anchor="middle" x="298" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">acmebank&#45;wizard</text>
+</g>
+<!-- dirname&#45;&gt;img -->
+<g id="edge3" class="edge">
+<title>dirname&#45;&gt;img</title>
+<path fill="none" stroke="#4a5568" d="M298,-181.32C298,-163.19 298,-139.07 298,-120.47"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="301.5,-120.67 298,-110.67 294.5,-120.67 301.5,-120.67"/>
+</g>
+<!-- ports -->
+<g id="node5" class="node">
+<title>ports</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="460.38,-109 371.62,-109 371.62,-73 460.38,-73 460.38,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="416" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">port block</text>
+<text xml:space="preserve" text-anchor="middle" x="416" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">21300–21309</text>
+</g>
+<!-- dirname&#45;&gt;ports -->
+<g id="edge4" class="edge">
+<title>dirname&#45;&gt;ports</title>
+<path fill="none" stroke="#4a5568" d="M324.94,-181.53C336.66,-170.19 350.54,-156.71 363,-144.5 372.11,-135.57 382.06,-125.74 390.85,-117.02"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="393.15,-119.67 397.79,-110.14 388.22,-114.7 393.15,-119.67"/>
+</g>
+<!-- reg -->
+<g id="node6" class="node">
+<title>reg</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="597.38,-109 478.62,-109 478.62,-73 597.38,-73 597.38,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="538" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">registry container</text>
+<text xml:space="preserve" text-anchor="middle" x="538" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">acmebank&#45;registry</text>
+</g>
+<!-- dirname&#45;&gt;reg -->
+<g id="edge5" class="edge">
+<title>dirname&#45;&gt;reg</title>
+<path fill="none" stroke="#4a5568" d="M356.87,-190.63C390.74,-179.74 433.49,-163.98 469,-144.5 483.3,-136.65 497.86,-126.04 509.9,-116.41"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="511.88,-119.31 517.39,-110.26 507.44,-113.9 511.88,-119.31"/>
+</g>
+<!-- cluster -->
+<g id="node11" class="node">
+<title>cluster</title>
+<polygon fill="#1a1a3a" stroke="#1e2a4a" points="469.81,-10.54 469.81,-25.46 438.29,-36 393.71,-36 362.19,-25.46 362.19,-10.54 393.71,0 438.29,0 469.81,-10.54"/>
+<text xml:space="preserve" text-anchor="middle" x="416" y="-14.3" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#0066ff">kind cluster</text>
+</g>
+<!-- cname&#45;&gt;cluster -->
+<g id="edge9" class="edge">
+<title>cname&#45;&gt;cluster</title>
+<path fill="none" stroke="#4a5568" d="M93.06,-72.62C99.54,-69.72 106.38,-67.02 113,-65 192.78,-40.7 288.45,-28.91 350.65,-23.42"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="350.69,-26.93 360.36,-22.6 350.1,-19.96 350.69,-26.93"/>
+</g>
+<!-- ports&#45;&gt;cluster -->
+<g id="edge10" class="edge">
+<title>ports&#45;&gt;cluster</title>
+<path fill="none" stroke="#4a5568" d="M416,-72.81C416,-65.23 416,-56.1 416,-47.54"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="419.5,-47.54 416,-37.54 412.5,-47.54 419.5,-47.54"/>
+</g>
+<!-- versions -->
+<g id="node7" class="node">
+<title>versions</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="759.38,-401.83 652.62,-401.83 652.62,-365.83 759.38,-365.83 759.38,-401.83"/>
+<text xml:space="preserve" text-anchor="middle" x="706" y="-386.88" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">versions.env</text>
+<text xml:space="preserve" text-anchor="middle" x="706" y="-373.38" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">pinned toolchain</text>
+</g>
+<!-- profile -->
+<g id="node8" class="node">
+<title>profile</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="790.5,-318.58 621.5,-318.58 621.5,-282.58 790.5,-282.58 790.5,-318.58"/>
+<text xml:space="preserve" text-anchor="middle" x="706" y="-303.63" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">env.d/&lt;profile&gt;.env</text>
+<text xml:space="preserve" text-anchor="middle" x="706" y="-290.13" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">nodes · CNI · audit · addons</text>
+</g>
+<!-- versions&#45;&gt;profile -->
+<g id="edge6" class="edge">
+<title>versions&#45;&gt;profile</title>
+<path fill="none" stroke="#4a5568" d="M706,-365.59C706,-355.32 706,-342.03 706,-330.21"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="709.5,-330.58 706,-320.58 702.5,-330.58 709.5,-330.58"/>
+<text xml:space="preserve" text-anchor="middle" x="737.5" y="-339.28" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">overridden by</text>
+</g>
+<!-- localenv -->
+<g id="node9" class="node">
+<title>localenv</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="761.88,-226.54 646.12,-226.54 646.12,-190.54 761.88,-190.54 761.88,-226.54"/>
+<text xml:space="preserve" text-anchor="middle" x="704" y="-211.59" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">ctrl/.env</text>
+<text xml:space="preserve" text-anchor="middle" x="704" y="-198.09" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">secrets, overrides</text>
+</g>
+<!-- profile&#45;&gt;localenv -->
+<g id="edge7" class="edge">
+<title>profile&#45;&gt;localenv</title>
+<path fill="none" stroke="#4a5568" d="M705.61,-282.22C705.34,-269.76 704.96,-252.69 704.64,-238.23"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="708.14,-238.28 704.42,-228.36 701.14,-238.43 708.14,-238.28"/>
+<text xml:space="preserve" text-anchor="middle" x="736.68" y="-256.03" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">overridden by</text>
+</g>
+<!-- shell -->
+<g id="node10" class="node">
+<title>shell</title>
+<polygon fill="#1a3a1a" stroke="#1e2a4a" points="772.38,-109 623.62,-109 623.62,-73 772.38,-73 772.38,-109"/>
+<text xml:space="preserve" text-anchor="middle" x="698" y="-94.05" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">the environment</text>
+<text xml:space="preserve" text-anchor="middle" x="698" y="-80.55" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">PROFILE=client make …</text>
+</g>
+<!-- localenv&#45;&gt;shell -->
+<g id="edge8" class="edge">
+<title>localenv&#45;&gt;shell</title>
+<path fill="none" stroke="#00c853" d="M703.11,-190.49C702.16,-172.16 700.63,-142.72 699.49,-120.79"/>
+<polygon fill="#00c853" stroke="#00c853" points="703,-120.81 698.99,-111.01 696.01,-121.18 703,-120.81"/>
+<text xml:space="preserve" text-anchor="middle" x="733.21" y="-155.2" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">overridden by</text>
+</g>
+<!-- shell&#45;&gt;cluster -->
+<g id="edge11" class="edge">
+<title>shell&#45;&gt;cluster</title>
+<path fill="none" stroke="#4a5568" stroke-dasharray="5,2" d="M637.29,-72.6C627.83,-69.99 618.17,-67.38 609,-65 562.72,-52.99 509.89,-40.48 471.22,-31.54"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="472.2,-28.18 461.67,-29.35 470.63,-35 472.2,-28.18"/>
+</g>
+</g>
+</svg>

rig/docs/graphs/03-architecture.dot

@@ -0,0 +1,56 @@
+// TODO: PLACEHOLDER — replace with the real estate topology.
+//
+// This is where the extracted platform diagrams land. The shape below is
+// illustrative only: it shows how a mocked dependency, a real service and a
+// remote system are meant to sit together, not what the system actually is.
+//
+// The intended end state is that this file stops being hand-written and is
+// generated from the running cluster, so the diagram becomes a report of what
+// exists rather than a drawing of what was once intended.
+digraph estate {
+    rankdir=LR
+    bgcolor="#0a0e17"
+    fontname="Helvetica"
+    node [fontname="Helvetica" fontsize=11 style=filled color="#1e2a4a" fontcolor="#e8eaf0" shape=box]
+    edge [fontname="Helvetica" fontsize=9 fontcolor="#8892a8" color="#4a5568"]
+
+    label="Estate topology — PLACEHOLDER"
+    labelloc=t
+    fontsize=16
+    fontcolor="#ffc107"
+
+    subgraph cluster_new {
+        label="New"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        api     [label="service under work\n(real: built and hot-reloaded)" fillcolor="#1a3a1a" fontcolor="#00c853"]
+    }
+
+    subgraph cluster_core {
+        label="Core (mocked)"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        svc_a   [label="upstream service\n(mock: canned responses)" fillcolor="#121829"]
+        db      [label="datastore\n(mock)" fillcolor="#121829" shape=cylinder]
+    }
+
+    subgraph cluster_legacy {
+        label="Legacy estate (mocked)"
+        style=dashed
+        color="#1e2a4a"
+        fontcolor="#8892a8"
+
+        batch   [label="batch drop\n(mock: writes files on a timer)" fillcolor="#121829"]
+    }
+
+    remote  [label="external system\n(remote: ExternalName,\nreachable only from a VDI)" fillcolor="#3a1a1a" fontcolor="#ffc107" shape=octagon]
+
+    api -> svc_a  [label="HTTP"]
+    api -> db     [label="query"]
+    api -> batch  [label="file handoff" style=dashed]
+    api -> remote [label="only when reachable" style=dashed color="#ffc107"]
+}

rig/docs/graphs/03-architecture.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: estate Pages: 1 -->
+<svg width="579pt" height="362pt"
+ viewBox="0.00 0.00 579.00 362.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 357.62)">
+<title>estate</title>
+<polygon fill="#0a0e17" stroke="none" points="-4,4 -4,-357.62 575.41,-357.62 575.41,4 -4,4"/>
+<text xml:space="preserve" text-anchor="middle" x="285.7" y="-334.42" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#ffc107">Estate topology — PLACEHOLDER</text>
+<g id="clust1" class="cluster">
+<title>cluster_new</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="8,-130.12 8,-210.12 199,-210.12 199,-130.12 8,-130.12"/>
+<text xml:space="preserve" text-anchor="middle" x="103.5" y="-190.92" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">New</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_core</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="357.33,-172.12 357.33,-318.12 534.83,-318.12 534.83,-172.12 357.33,-172.12"/>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-298.92" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Core (mocked)</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_legacy</title>
+<polygon fill="#0a0e17" stroke="#1e2a4a" stroke-dasharray="5,2" points="341.83,-84.12 341.83,-164.12 551.33,-164.12 551.33,-84.12 341.83,-84.12"/>
+<text xml:space="preserve" text-anchor="middle" x="446.58" y="-144.92" font-family="Helvetica,sans-Serif" font-size="16.00" fill="#8892a8">Legacy estate (mocked)</text>
+</g>
+<!-- api -->
+<g id="node1" class="node">
+<title>api</title>
+<polygon fill="#1a3a1a" stroke="#1e2a4a" points="191,-174.12 16,-174.12 16,-138.12 191,-138.12 191,-174.12"/>
+<text xml:space="preserve" text-anchor="middle" x="103.5" y="-159.17" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">service under work</text>
+<text xml:space="preserve" text-anchor="middle" x="103.5" y="-145.67" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#00c853">(real: built and hot&#45;reloaded)</text>
+</g>
+<!-- svc_a -->
+<g id="node2" class="node">
+<title>svc_a</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="526.83,-282.12 365.33,-282.12 365.33,-246.12 526.83,-246.12 526.83,-282.12"/>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-267.17" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">upstream service</text>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-253.67" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">(mock: canned responses)</text>
+</g>
+<!-- api&#45;&gt;svc_a -->
+<g id="edge1" class="edge">
+<title>api&#45;&gt;svc_a</title>
+<path fill="none" stroke="#4a5568" d="M149.07,-174.56C167.54,-182.07 189.23,-190.7 209,-198.12 258.25,-216.6 270.12,-222.85 320.75,-237.12 331.43,-240.13 342.71,-243 353.94,-245.67"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="353.12,-249.07 363.66,-247.92 354.71,-242.25 353.12,-249.07"/>
+<text xml:space="preserve" text-anchor="middle" x="255.88" y="-234.24" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">HTTP</text>
+</g>
+<!-- db -->
+<g id="node3" class="node">
+<title>db</title>
+<path fill="#121829" stroke="#1e2a4a" d="M480.7,-223.81C480.7,-226.22 465.18,-228.18 446.08,-228.18 426.97,-228.18 411.45,-226.22 411.45,-223.81 411.45,-223.81 411.45,-184.43 411.45,-184.43 411.45,-182.02 426.97,-180.06 446.08,-180.06 465.18,-180.06 480.7,-182.02 480.7,-184.43 480.7,-184.43 480.7,-223.81 480.7,-223.81"/>
+<path fill="none" stroke="#1e2a4a" d="M480.7,-223.81C480.7,-221.39 465.18,-219.43 446.08,-219.43 426.97,-219.43 411.45,-221.39 411.45,-223.81"/>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-207.17" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">datastore</text>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-193.67" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">(mock)</text>
+</g>
+<!-- api&#45;&gt;db -->
+<g id="edge2" class="edge">
+<title>api&#45;&gt;db</title>
+<path fill="none" stroke="#4a5568" d="M191.32,-168.36C257.83,-177.73 346.91,-190.28 399.91,-197.75"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="399.4,-201.22 409.79,-199.15 400.38,-194.29 399.4,-201.22"/>
+<text xml:space="preserve" text-anchor="middle" x="255.88" y="-185.69" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">query</text>
+</g>
+<!-- batch -->
+<g id="node4" class="node">
+<title>batch</title>
+<polygon fill="#121829" stroke="#1e2a4a" points="537.33,-128.12 354.83,-128.12 354.83,-92.12 537.33,-92.12 537.33,-128.12"/>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-113.17" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">batch drop</text>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-99.67" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#e8eaf0">(mock: writes files on a timer)</text>
+</g>
+<!-- api&#45;&gt;batch -->
+<g id="edge3" class="edge">
+<title>api&#45;&gt;batch</title>
+<path fill="none" stroke="#4a5568" stroke-dasharray="5,2" d="M191.32,-144.39C237.67,-138.13 294.98,-130.39 343.4,-123.85"/>
+<polygon fill="#4a5568" stroke="#4a5568" points="343.61,-127.36 353.05,-122.55 342.67,-120.42 343.61,-127.36"/>
+<text xml:space="preserve" text-anchor="middle" x="255.88" y="-143.94" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">file handoff</text>
+</g>
+<!-- remote -->
+<g id="node5" class="node">
+<title>remote</title>
+<polygon fill="#3a1a1a" stroke="#1e2a4a" points="571.41,-21.74 571.41,-52.5 497.99,-74.24 394.17,-74.24 320.75,-52.5 320.75,-21.74 394.17,0 497.99,0 571.41,-21.74"/>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-46.92" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffc107">external system</text>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-33.42" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffc107">(remote: ExternalName,</text>
+<text xml:space="preserve" text-anchor="middle" x="446.08" y="-19.92" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#ffc107">reachable only from a VDI)</text>
+</g>
+<!-- api&#45;&gt;remote -->
+<g id="edge4" class="edge">
+<title>api&#45;&gt;remote</title>
+<path fill="none" stroke="#ffc107" stroke-dasharray="5,2" d="M149.55,-137.68C167.9,-130.34 189.37,-121.97 209,-114.87 254.45,-98.43 305.32,-81.49 348.17,-67.64"/>
+<polygon fill="#ffc107" stroke="#ffc107" points="349,-71.05 357.44,-64.65 346.85,-64.39 349,-71.05"/>
+<text xml:space="preserve" text-anchor="middle" x="255.88" y="-117.57" font-family="Helvetica,sans-Serif" font-size="9.00" fill="#8892a8">only when reachable</text>
+</g>
+</g>
+</svg>

rig/docs/index.html

@@ -0,0 +1,588 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>rig — local environment installer</title>
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap');
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    background: #0a0e17;
+    color: #e8eaf0;
+    font-family: 'Inter', sans-serif;
+    line-height: 1.6;
+    height: 100vh;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+
+  header {
+    padding: 16px 24px;
+    border-bottom: 1px solid #1e2a4a;
+    display: flex;
+    align-items: baseline;
+    gap: 16px;
+    flex-shrink: 0;
+  }
+
+  header h1 {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 22px;
+    font-weight: 600;
+    letter-spacing: 3px;
+    color: #0066ff;
+  }
+
+  header .subtitle {
+    font-size: 13px;
+    color: #4a5568;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+  }
+
+  .layout { display: flex; flex: 1; min-height: 0; }
+
+  nav {
+    display: flex;
+    flex-direction: column;
+    width: 200px;
+    flex-shrink: 0;
+    background: #121829;
+    border-right: 1px solid #1e2a4a;
+    padding: 8px 0;
+    overflow-y: auto;
+  }
+
+  nav a {
+    padding: 10px 20px;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 12px;
+    color: #8892a8;
+    text-decoration: none;
+    border-left: 2px solid transparent;
+    transition: all 0.15s;
+    cursor: pointer;
+  }
+
+  nav a:hover { color: #e8eaf0; background: #1a2340; }
+  nav a.active { color: #0066ff; border-left-color: #0066ff; background: #0d1a33; }
+
+  main { flex: 1; overflow: auto; padding: 32px 48px; }
+
+  .section { display: none; animation: fadeIn 0.2s ease; }
+  .section.active { display: block; }
+  @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+
+  .section h2 {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 15px;
+    font-weight: 500;
+    color: #8892a8;
+    margin-bottom: 8px;
+    letter-spacing: 1px;
+    text-transform: uppercase;
+  }
+
+  .section > p.lede {
+    font-size: 13px;
+    color: #4a5568;
+    margin-bottom: 24px;
+    max-width: 800px;
+  }
+
+  .prose { max-width: 820px; }
+  .prose p { font-size: 14px; color: #b4bccf; line-height: 1.7; margin-bottom: 14px; }
+  .prose p b { color: #e8eaf0; }
+  .prose ul { margin: 0 0 16px 20px; }
+  .prose li { font-size: 14px; color: #b4bccf; margin-bottom: 6px; }
+
+  .prose h3 {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 13px;
+    text-transform: uppercase;
+    color: #e8eaf0;
+    margin: 32px 0 10px;
+    letter-spacing: 1px;
+  }
+
+  .prose code, pre code {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 12px;
+    color: #7ab0ff;
+    background: #121829;
+    padding: 1px 5px;
+    border-radius: 3px;
+  }
+
+  pre {
+    background: #121829;
+    border: 1px solid #1e2a4a;
+    padding: 16px;
+    overflow: auto;
+    margin-bottom: 16px;
+  }
+
+  pre code { background: none; padding: 0; }
+  pre .c { color: #4a5568; }
+  pre .k { color: #0066ff; }
+
+  .graph-container { margin: 16px 0; }
+  .graph-container img {
+    display: block;
+    max-width: 100%;
+    background: #0a0e17;
+    border: 1px solid #1e2a4a;
+    padding: 12px;
+  }
+
+  dl {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: 10px 24px;
+    margin: 16px 0;
+    max-width: 820px;
+  }
+
+  dt {
+    font-family: 'JetBrains Mono', monospace;
+    color: #0066ff;
+    font-size: 13px;
+    padding-top: 2px;
+  }
+
+  dd { font-size: 14px; color: #b4bccf; line-height: 1.6; }
+
+  table { border-collapse: collapse; margin: 16px 0; max-width: 820px; }
+  th, td {
+    text-align: left;
+    padding: 7px 16px 7px 0;
+    font-size: 13px;
+    border-bottom: 1px solid #1e2a4a;
+    color: #b4bccf;
+  }
+  th {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    text-transform: uppercase;
+    color: #8892a8;
+    letter-spacing: 1px;
+  }
+  td code { white-space: nowrap; }
+
+  .note {
+    border-left: 2px solid #ffc107;
+    background: #17130a;
+    padding: 12px 16px;
+    margin: 16px 0;
+    max-width: 820px;
+  }
+  .note p { margin: 0; font-size: 13px; color: #b4bccf; }
+  .note b { color: #ffc107; }
+
+  .menu-toggle {
+    display: none;
+    background: transparent;
+    border: 1px solid #1e2a4a;
+    color: #8892a8;
+    padding: 6px 10px;
+    font-size: 14px;
+    cursor: pointer;
+    line-height: 1;
+    margin-left: auto;
+  }
+  .menu-toggle:hover { background: #1a2340; }
+
+  .nav-backdrop {
+    display: none;
+    position: absolute;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.5);
+    z-index: 10;
+  }
+  .layout.nav-open .nav-backdrop { display: block; }
+
+  @media (max-width: 720px) {
+    header { padding: 10px 12px; gap: 8px; }
+    header h1 { font-size: 16px; letter-spacing: 1px; }
+    header .subtitle { display: none; }
+    .menu-toggle { display: inline-block; }
+    .layout { position: relative; }
+    nav {
+      position: absolute; left: 0; top: 0; bottom: 0;
+      width: 200px; z-index: 20;
+      transform: translateX(-100%);
+      transition: transform 0.2s ease;
+      box-shadow: 2px 0 8px rgba(0, 0, 0, 0.5);
+    }
+    .layout.nav-open nav { transform: translateX(0); }
+    main { padding: 16px; }
+    .section h2 { font-size: 13px; }
+    .prose p, .prose li { font-size: 13px; }
+  }
+</style>
+</head>
+<body>
+
+<header>
+  <h1>RIG</h1>
+  <span class="subtitle">local environment installer</span>
+  <button class="menu-toggle">&#9776;</button>
+</header>
+
+<div class="layout">
+  <div class="nav-backdrop"></div>
+  <nav>
+    <a href="#start">Start here</a>
+    <a href="#steps">The steps</a>
+    <a href="#install">Installation</a>
+    <a href="#environments">Environments</a>
+    <a href="#profiles">Profiles</a>
+    <a href="#registry">Registry</a>
+    <a href="#architecture">Architecture</a>
+    <a href="#troubleshooting">Troubleshooting</a>
+  </nav>
+
+  <main>
+
+  <section class="section" id="start">
+    <h2>Start here</h2>
+    <p class="lede">A runnable local model of a large, regulated estate — legacy and new side by side.</p>
+    <div class="prose">
+      <p>rig builds a disposable Kubernetes environment on your machine so you can
+      explore how a system fits together without needing access to any of it. Its
+      job is <b>onboarding and exploration</b>, not a production replica.</p>
+
+      <p>Most services in it are deliberately <b>not real</b>. What has to be faithful
+      is the topology — the names, the ports, the dependency order, who can reach whom,
+      and how it fails. The workloads themselves are noise. This is what makes the
+      whole estate fit on a laptop: a real 20-service platform will not fit even once
+      on 14&nbsp;GB, but mocks are about 30&nbsp;MB each, so three faithful copies do.</p>
+
+      <h3>The only prerequisite</h3>
+      <p><b>Docker.</b> No curl, no jq, no python, no apt repositories to configure.</p>
+<pre><code><span class="c"># then, in the environment directory:</span>
+make station     <span class="c"># is this workstation ready? reports, never fixes</span>
+make deps        <span class="c"># install the pinned toolchain</span>
+make cluster up  <span class="c"># build the cluster for the active profile</span>
+</code></pre>
+      <p>Read <code>make station</code> before <code>make deps</code>. It never changes
+      anything — it prints what it found and, at the end, the steps it cannot perform
+      for you.</p>
+    </div>
+  </section>
+
+  <section class="section" id="steps">
+    <h2>The steps</h2>
+    <p class="lede">Start to finish, in order, with what each one actually does.</p>
+    <div class="prose">
+
+      <h3>1 &middot; make station</h3>
+      <p>Asks whether this workstation is ready. It <b>changes nothing</b> — it
+      reports what it found and, at the end, the things only a human can do
+      (anything needing <code>sudo</code>, or a Windows-side restart). Read it
+      before installing anything; it is faster than discovering the same problems
+      one failure at a time.</p>
+<pre><code>make station</code></pre>
+
+      <h3>2 &middot; make setup</h3>
+      <p>Does the preparation that can be automated: installs the pinned
+      toolchain if it is missing, checks PATH, Docker, and this environment's
+      ports. Every step is independently checked, so running it twice is safe and
+      running it half-configured finishes the job.</p>
+      <p>It <b>does not stop at the first failure</b>. A setup script that dies at
+      step two hides that steps four and five would also have failed, and on an
+      unfamiliar machine the complete list is the point. The tail of the output is
+      a to-do list of only what is outstanding.</p>
+<pre><code>make setup                  <span class="c"># host + toolchain</span>
+make setup --share-docker   <span class="c"># ...and offer this machine's Docker to other distros</span>
+</code></pre>
+
+      <h3>3 &middot; make cluster up</h3>
+      <p>Builds the cluster for the active profile. It prints what the profile
+      locks in <i>before</i> spending the time, because the CNI and the audit
+      policy are fixed at creation and cannot be changed afterwards.</p>
+      <p>Re-running is safe and, more importantly, <b>convergent</b>: if a first
+      attempt was interrupted before the CNI was installed, running it again
+      finishes the job rather than reporting "already exists" and leaving every
+      node permanently NotReady.</p>
+<pre><code>make cluster up                 <span class="c"># default profile</span>
+make cluster up PROFILE=client  <span class="c"># three nodes, audit on, cached registry</span>
+make cluster reset              <span class="c"># destroy and rebuild — the only way to change CNI or audit</span>
+</code></pre>
+
+      <h3>4 &middot; make docs</h3>
+      <p>Serves this page from a throwaway container. Works with no cluster and
+      no toolchain, which is deliberate: these pages are the instructions for
+      building everything else, so they cannot depend on it.</p>
+<pre><code>make docs</code></pre>
+
+      <h3>Checking on things</h3>
+      <dl>
+        <dt>make cluster list</dt><dd>Every cluster on the machine, its memory cost and its port block. The usual reason a new one will not start is an old one you forgot about; <code>make cluster free</code> frees them without deleting.</dd>
+        <dt>make ports</dt><dd>This environment's port block, and whether each is derived or overridden.</dd>
+        <dt>make registry</dt><dd>Which of the four registry modes is active, and where it points.</dd>
+        <dt>make dockerhost</dt><dd>Which WSL distro owns Docker and what this one is using.</dd>
+      </dl>
+
+      <h3>Running more than one</h3>
+      <p>Copy the directory, rename it, and repeat from step 2. Cluster name,
+      context, image tags and the port block all follow the directory name, so
+      the second environment collides with nothing and neither one's teardown can
+      reach the other.</p>
+<pre><code>cp -r rig ../platform-v2 &amp;&amp; cd ../platform-v2
+make setup &amp;&amp; make cluster up
+</code></pre>
+    </div>
+  </section>
+
+  <section class="section" id="install">
+    <h2>Installation</h2>
+    <p class="lede">A container installs onto the host and then gets out of the way.</p>
+    <div class="graph-container">
+      <a href="viewer.html?src=graphs/01-install.svg"><img src="graphs/01-install.svg" alt="Installation flow"></a>
+    </div>
+    <div class="prose">
+      <p>The installer is a container, not a shell script, for a specific reason: a
+      stock slim Debian has no <code>curl</code>, no <code>wget</code>, no
+      <code>jq</code>, no <code>python3</code> and <b>no CA bundle</b>. A shell
+      installer could not make a verified HTTPS request, let alone check one. The
+      container carries its own toolchain, so the host needs nothing but Docker.</p>
+
+      <p>The cluster never runs inside that container. Everything it installs —
+      kind, kubectl, tilt, jq — runs natively afterwards, so nothing pays a
+      container tax during daily work.</p>
+
+      <h3>Pinned and verified</h3>
+      <p>Every tool is a single binary fetched at a pinned version and checked
+      against a published SHA256. Node images are pinned <b>by digest</b>, so
+      upgrading kind cannot silently move your Kubernetes version.</p>
+
+      <h3>Not every machine should get cluster tooling</h3>
+      <p>A managed or corporate-issued machine — the kind that holds the access
+      you cannot get anywhere else — is not somewhere to install development
+      tools by default. So the toolchain comes in two tiers:</p>
+      <table>
+        <tr><th>tier</th><th>installs</th><th>for</th></tr>
+        <tr><td><code>core</code></td><td>kubectl, jq</td><td>talk to a cluster someone else runs</td></tr>
+        <tr><td><code>dev</code></td><td>+ kind, tilt</td><td>build clusters and hot-reload into them</td></tr>
+      </table>
+<pre><code>make deps core   <span class="c"># kubectl and jq only — nothing that creates a cluster</span>
+make deps        <span class="c"># dev, the default</span>
+make setup core  <span class="c"># same distinction, via setup</span>
+</code></pre>
+      <p>Testing <i>in situ</i> on a managed machine is still possible — install
+      the <code>dev</code> tier deliberately when you need it. The point is that
+      it should be a decision rather than a side effect of running setup.</p>
+      <p>The documentation itself needs neither tier: <code>make docs</code>
+      wants only Docker.</p>
+
+      <h3>Air-gapped</h3>
+<pre><code>make wizard full                       <span class="c"># bakes every binary into the image</span>
+docker save …-wizard:full | gzip &gt; rig.tgz
+<span class="c"># carry that one file in, then:</span>
+docker load &lt; rig.tgz &amp;&amp; make cluster up PROFILE=offline
+</code></pre>
+    </div>
+  </section>
+
+  <section class="section" id="environments">
+    <h2>Environments</h2>
+    <p class="lede">One directory is one environment. Copy it, rename it, run it.</p>
+    <div class="graph-container">
+      <a href="viewer.html?src=graphs/02-environment.svg"><img src="graphs/02-environment.svg" alt="Environment derivation"></a>
+    </div>
+    <div class="prose">
+      <p>Running several versions of a system at once means several clusters on one
+      machine, not several machines. Everything that could collide is derived from
+      the directory name:</p>
+      <dl>
+        <dt>cluster + context</dt><dd><code>acmebank/</code> builds <code>acmebank</code> on <code>kind-acmebank</code>.</dd>
+        <dt>port block</dt><dd>Ten ports from a hash of the name, in the 20000+ range — clear of 80, 443, 3000, 5432, 8000 and 8080.</dd>
+        <dt>registry + images</dt><dd>Named after the environment, so two copies never share one.</dd>
+      </dl>
+      <p>Two copies therefore never collide, and neither one's
+      <code>make cluster down</code> can touch the other. <code>make ports</code>
+      shows the block; <code>make ports persist</code> freezes it into
+      <code>ctrl/.env</code> if you want it fixed rather than derived.</p>
+
+      <h3>Configuration layers</h3>
+      <p>Weakest first, later wins: pinned versions → the profile →
+      <code>ctrl/.env</code> → the environment. So
+      <code>make cluster up PROFILE=client</code> always beats every file.</p>
+    </div>
+  </section>
+
+  <section class="section" id="profiles">
+    <h2>Profiles</h2>
+    <p class="lede">Cluster shape is declared, not baked in.</p>
+    <div class="prose">
+      <table>
+        <tr><th>profile</th><th>nodes</th><th>audit</th><th>registry</th><th>for</th></tr>
+        <tr><td><code>minimal</code></td><td>1</td><td>off</td><td>none</td><td>first boot; assumes nothing</td></tr>
+        <tr><td><code>client</code></td><td>3</td><td>on</td><td>mirror</td><td>the regulated shape</td></tr>
+        <tr><td><code>offline</code></td><td>1</td><td>on</td><td>local</td><td>air-gapped</td></tr>
+      </table>
+
+      <div class="note"><p><b>The audit policy cannot be changed later.</b> It is an
+      apiserver flag, fixed when the cluster is created. <code>cluster up</code>
+      prints what a profile locks in before spending the time, and
+      <code>make cluster reset</code> is the way out.</p></div>
+
+      <h3>LoadBalancer services</h3>
+      <p>Real manifests use <code>type: LoadBalancer</code>, because a real
+      cluster has one. On a bare local cluster those Services sit at
+      <code>EXTERNAL-IP &lt;pending&gt;</code> forever, with no error anywhere —
+      the deployment looks healthy and simply is not reachable.</p>
+      <p>The <code>metallb</code> addon fixes that, so the same manifests work
+      here as upstream and nothing has to be rewritten to NodePort. Its address
+      pool is derived from the cluster's Docker network at install time rather
+      than hardcoded, because Docker picks that subnet and it differs between
+      machines.</p>
+      <div class="note"><p><b>Where those addresses are reachable from.</b> The
+      pool lives on the Docker bridge, so LoadBalancer IPs work from the Linux
+      side — including from inside WSL. A browser on Windows has no route to
+      them. Use the ingress host ports for anything you need to open in a
+      browser.</p></div>
+
+      <h3>Networking</h3>
+      <p>The cluster uses kind's built-in networking, which <b>does</b> enforce
+      standard NetworkPolicy — verified against a no-policy control, not assumed.
+      The widely repeated claim that it accepts policies and silently ignores
+      them is out of date.</p>
+      <p>A pluggable CNI was tried and removed: it only added
+      GlobalNetworkPolicy, policy tiers and egress-CIDR rules, none of which are
+      needed yet, in exchange for a slower boot and one more thing that has to be
+      right at creation time. Worth revisiting only when a policy the built-in
+      cannot express actually comes up.</p>
+
+      <h3>Memory</h3>
+      <p>Every cluster is a running container tree whether you are using it or not.
+      <code>make cluster list</code> shows what exists and what it costs;
+      <code>make cluster free</code> stops the others without deleting them.</p>
+    </div>
+  </section>
+
+  <section class="section" id="registry">
+    <h2>Registry</h2>
+    <p class="lede">Local, cached, or straight to the corporate registry.</p>
+    <div class="prose">
+      <table>
+        <tr><th>mode</th><th>what it does</th></tr>
+        <tr><td><code>none</code></td><td>images are built straight into the node</td></tr>
+        <tr><td><code>local</code></td><td>a registry container wired into the cluster</td></tr>
+        <tr><td><code>mirror</code></td><td>that container as a <b>pull-through cache</b> of the corporate registry</td></tr>
+        <tr><td><code>remote</code></td><td>no local container; pull direct with an imagePullSecret</td></tr>
+      </table>
+      <p><code>mirror</code> is what a locked-down network actually looks like:
+      images originate from the corporate registry, you do not hammer it, and you
+      keep working when the connection drops.</p>
+
+      <div class="note"><p><b>The corporate CA will bite you.</b> A corporate
+      registry is usually behind an internal CA, and trust has to reach
+      <b>three</b> places: the host Docker daemon, every cluster node's containerd
+      (nodes do <i>not</i> inherit host trust), and any in-cluster client. Set
+      <code>REGISTRY_CA_FILE</code> and <code>make station</code> reports which is
+      still missing. The symptom otherwise is an opaque
+      <code>x509: certificate signed by unknown authority</code>.</p></div>
+
+      <p>Reachability also depends on where you are: if the registry is only
+      routable from a managed workspace, <code>mirror</code> and <code>remote</code>
+      will not resolve from a laptop at all. That is what <code>local</code> and
+      <code>offline</code> are for.</p>
+    </div>
+  </section>
+
+  <section class="section" id="architecture">
+    <h2>Architecture</h2>
+    <p class="lede">The estate being modelled.</p>
+    <div class="note"><p><b>TODO — placeholder.</b> The diagram below is
+    illustrative only: it shows how a mocked dependency, a service under active
+    work, and an unreachable remote system sit together. It is not the real
+    topology. Replace <code>docs/graphs/03-architecture.dot</code> with the
+    extracted platform diagrams, then run <code>make docs graphs</code>.</p></div>
+    <div class="graph-container">
+      <a href="viewer.html?src=graphs/03-architecture.svg"><img src="graphs/03-architecture.svg" alt="Estate topology (placeholder)"></a>
+    </div>
+    <div class="prose">
+      <p>Each component is one of three things, and switching between them should be
+      a one-line change rather than a rewrite:</p>
+      <dl>
+        <dt>real</dt><dd>Built from source and hot-reloaded. The thing you are actually working on — usually exactly one.</dd>
+        <dt>mock</dt><dd>A generic stub with canned responses. Everything you do not care about today.</dd>
+        <dt>remote</dt><dd>No pod at all: a Service of type ExternalName pointing at the real system. In-cluster DNS resolves identically, so callers never change.</dd>
+      </dl>
+      <p>The intended end state is that this diagram is <b>generated from the
+      running cluster</b> rather than drawn by hand — so it becomes a report of
+      what exists instead of a picture of what was once intended.</p>
+    </div>
+  </section>
+
+  <section class="section" id="troubleshooting">
+    <h2>Troubleshooting</h2>
+    <p class="lede">The failures that are hard to diagnose from their symptoms.</p>
+    <div class="prose">
+      <h3>Tilt stops noticing file changes</h3>
+      <p>Almost always <code>inotify</code> limits, and it fails <i>silently</i> —
+      nothing errors, changes just stop being picked up. Defaults on WSL are far too
+      low. <code>make station</code> reports it and prints the fix.</p>
+
+      <h3>Cluster creation dies halfway with a port error</h3>
+      <p>Docker reports <code>failed to bind host port … address already in use</code>
+      partway through creating the cluster. Run <code>make station</code> first — it
+      checks every port in this environment's block before anything is built.</p>
+
+      <h3>Every node stays NotReady</h3>
+      <p>Usually a cluster created with the default CNI disabled but the real CNI
+      never installed — typically an interrupted first run. Just run
+      <code>make cluster up</code> again: it converges rather than exiting early, and
+      will finish the missing steps.</p>
+
+      <h3>x509: certificate signed by unknown authority</h3>
+      <p>Corporate CA trust has not reached one of the three places it needs to be.
+      See <a href="#registry">Registry</a>.</p>
+
+      <h3>kubectl says the context does not exist</h3>
+      <p>The cluster can exist while its context does not — a reset or a switched
+      <code>KUBECONFIG</code> loses it. <code>make cluster up</code> detects this and
+      re-exports the context.</p>
+    </div>
+  </section>
+
+  </main>
+</div>
+
+<script>
+(function () {
+  var layout = document.querySelector('.layout');
+  var main = document.querySelector('main');
+
+  function syncActive() {
+    var hash = location.hash.slice(1) || 'start';
+    document.querySelectorAll('.section').forEach(function (s) { s.classList.remove('active'); });
+    document.querySelectorAll('nav a').forEach(function (a) { a.classList.remove('active'); });
+    var section = document.getElementById(hash);
+    if (section) section.classList.add('active');
+    var link = document.querySelector('nav a[href="#' + hash + '"]');
+    if (link) link.classList.add('active');
+    if (main) main.scrollTop = 0;
+    layout.classList.remove('nav-open');
+  }
+
+  window.addEventListener('hashchange', syncActive);
+  window.addEventListener('DOMContentLoaded', syncActive);
+  syncActive();
+
+  document.addEventListener('click', function (e) {
+    if (e.target.closest('.menu-toggle') || e.target.closest('.nav-backdrop')) {
+      layout.classList.toggle('nav-open');
+    }
+  });
+})();
+</script>
+
+</body>
+</html>

rig/docs/viewer.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="UTF-8">
+<title>Graph Viewer</title>
+<style>
+  * { margin: 0; padding: 0; }
+  body {
+    background: #0a0e17;
+    overflow: hidden;
+    width: 100vw;
+    height: 100vh;
+  }
+  #container {
+    width: 100vw;
+    height: 100vh;
+    overflow: hidden;
+    cursor: grab;
+  }
+  #container.dragging { cursor: grabbing; }
+  img {
+    transform-origin: 0 0;
+    user-select: none;
+    -webkit-user-drag: none;
+  }
+</style>
+</head>
+<body>
+<div id="container">
+  <img id="img" />
+</div>
+<script>
+var src = new URLSearchParams(location.search).get('src');
+var img = document.getElementById('img');
+var container = document.getElementById('container');
+
+img.src = src;
+
+var scale = 1;
+var x = 0, y = 0;
+var dragging = false;
+var startX, startY, startPanX, startPanY;
+
+function apply() {
+  img.style.transform = 'translate(' + x + 'px,' + y + 'px) scale(' + scale + ')';
+}
+
+// Fit to screen on load
+img.onload = function() {
+  var sw = window.innerWidth / img.naturalWidth;
+  var sh = window.innerHeight / img.naturalHeight;
+  scale = Math.min(sw, sh) * 0.95;
+  x = (window.innerWidth - img.naturalWidth * scale) / 2;
+  y = (window.innerHeight - img.naturalHeight * scale) / 2;
+  apply();
+};
+
+// Wheel zoom toward cursor
+container.addEventListener('wheel', function(e) {
+  e.preventDefault();
+  var factor = e.deltaY < 0 ? 1.12 : 0.89;
+  var rect = container.getBoundingClientRect();
+  var mx = e.clientX - rect.left;
+  var my = e.clientY - rect.top;
+  x = mx - (mx - x) * factor;
+  y = my - (my - y) * factor;
+  scale *= factor;
+  apply();
+}, { passive: false });
+
+// Pan
+container.addEventListener('mousedown', function(e) {
+  if (e.button !== 0) return;
+  dragging = true;
+  startX = e.clientX;
+  startY = e.clientY;
+  startPanX = x;
+  startPanY = y;
+  container.classList.add('dragging');
+  e.preventDefault();
+});
+
+window.addEventListener('mousemove', function(e) {
+  if (!dragging) return;
+  x = startPanX + (e.clientX - startX);
+  y = startPanY + (e.clientY - startY);
+  apply();
+});
+
+window.addEventListener('mouseup', function() {
+  dragging = false;
+  container.classList.remove('dragging');
+});
+
+// Double-click to reset
+container.addEventListener('dblclick', function() {
+  img.onload();
+});
+</script>
+</body>
+</html>

rig/sample-rig/.gitignore

@@ -0,0 +1,9 @@
+# NOTE: generated/ is deliberately NOT ignored. The artifact IS the deliverable —
+# the whole point is a folder you copy, apply and boot without generating
+# anything first. Regenerate it with `make manifest` after editing bundle.json
+# or app/serve.py, and commit the result.
+#
+# (This differs from rig's ctrl/k8s/generated, which is a local build artifact.)
+
+__pycache__/
+*.pyc

rig/sample-rig/Makefile

@@ -0,0 +1,50 @@
+# Thin control Makefile — one target per ctrl/ script, subcommand as an
+# argument. Same shape as rig's, for the same reason: the logic lives in the
+# script, never here.
+#
+#   make up        ->  ctrl/bundle.sh up
+#   make bundle down
+#
+# This directory is a BUNDLE, not an installer. It needs a cluster, which rig
+# owns:
+#
+#   cd .. && make cluster up     # kind cluster for this environment
+#   make up                      # then deploy this bundle into it
+#
+# Start with:  make up
+
+ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+ifneq ($(ARGS),)
+$(eval $(ARGS):;@:)
+endif
+
+.DEFAULT_GOAL := help
+.PHONY: help bundle manifest up down status url list dev
+
+help:                          ## list targets
+	@grep -hE '^[a-z]+:.*?##' $(MAKEFILE_LIST) | sed 's/:.*##/\t/' | expand -t16
+
+bundle:                        ## the bundle  [manifest|up|down|status|url|list|dev]
+	bash ctrl/bundle.sh $(or $(ARGS),status)
+
+# Shorthands for the ones used constantly.
+manifest:                      ## regenerate generated/<slug>.yaml — no cluster needed
+	bash ctrl/bundle.sh manifest
+
+up:                            ## deploy this rig (installs MetalLB if absent)
+	bash ctrl/bundle.sh up
+
+down:                          ## remove this rig (leaves cluster, MetalLB, siblings)
+	bash ctrl/bundle.sh down
+
+status:                        ## what is deployed for this rig
+	bash ctrl/bundle.sh status
+
+url:                           ## the address MetalLB assigned
+	bash ctrl/bundle.sh url
+
+list:                          ## every rig in this cluster, with addresses
+	bash ctrl/bundle.sh list
+
+dev:                           ## run the UI locally with vite — no cluster needed
+	bash ctrl/bundle.sh dev

rig/sample-rig/README.md

@@ -0,0 +1,140 @@
+# sample-rig
+
+A minimal, non-sensitive bundle that proves an installation works and shows what
+shipped. Copy it, rename it, and you have another rig.
+
+```bash
+make manifest    # generate the artifact — no cluster, no kubectl needed
+make up          # deploy it into the local cluster
+make list        # every rig in this cluster, with addresses
+make dev         # run the UI locally with vite, no cluster at all
+```
+
+`make up` prints an address. Open it and the page says **IT WORKS**, then lists
+the tools and rigs in the bundle.
+
+## What it is for
+
+Three jobs, in the order you hit them:
+
+1. **Prove the install.** kind is there, a cluster exists, MetalLB hands out an
+   address, a `type: LoadBalancer` Service actually resolves, and a pod serves.
+   If all of that works, the environment is sound.
+2. **Say what shipped.** The page renders [`bundle.json`](bundle.json) —
+   standalone tools and rigs, flat, with none of soleprint's internal hierarchy.
+   Editing that file is the only step needed to change the listing.
+3. **Stand in for the real thing.** Nothing here is sensitive. The real
+   architecture connects separately, against a setup already known to work.
+
+## The UI is a complement, not the product
+
+`rig-ui/` is just a vite app. It complements a rig; a rig is complete and useful
+without it, and nothing depends on it being there. It is deliberately **not**
+generated by kind or tilt — you copy the folder into a rig after that rig is
+pulled, and apply one manifest:
+
+```bash
+kubectl apply -n <namespace> -f rig-ui/k8s.yaml
+```
+
+That file is the whole integration: one Pod running `npm run dev` on
+`node:22-alpine`, one Service. A bare Pod rather than a Deployment because this
+is a dev-loop convenience, not a workload to keep alive.
+
+The app and `bundle.json` arrive as a ConfigMap, so nothing is baked into an
+image and editing the bundle is the entire update cycle. The container runs
+`npm install` at start, which needs egress to a registry — on a locked-down
+cluster point npm at the internal one, or bake an image instead. Nothing else
+changes if you do.
+
+## One artifact, two destinations
+
+`ctrl/manifest.py` emits `generated/<slug>.yaml` — namespace, the app and
+bundle embedded in a ConfigMap, Pod, Service. It is self-contained and applies
+unmodified anywhere:
+
+```bash
+kubectl apply -f generated/sample-rig.yaml     # local kind, or an external cluster
+```
+
+`make up` applies **that same file**. There is no separate local path, so what
+works here cannot quietly differ from what is applied elsewhere.
+
+This is what `type: LoadBalancer` buys. MetalLB answers it on kind; the AWS load
+balancer controller answers it on EKS. NodePort would not survive the trip — it
+is a single cluster-wide port range, so two rigs would have to negotiate numbers.
+
+**VPC-agnostic on purpose.** The target is EKS, but the Service carries no
+annotations — no `aws-load-balancer-subnets`, no security groups, no `-scheme`,
+no `-type: nlb`. Each of those encodes a specific network layout, and one of them
+appearing here would pin the artifact to the account and VPC it was written
+against, which is precisely what stops it also working on kind. Subnet discovery
+is the cluster's business: EKS resolves it from the tags its own subnets carry.
+
+That leaves one thing genuinely environment-specific — internal versus
+internet-facing. A bare `LoadBalancer` provisions internet-facing, which a
+regulated account will usually refuse, and should. That belongs in a
+per-environment overlay applied on top, never inlined into this artifact.
+
+**MetalLB only — no ingress-nginx.** Its controller supports a narrow window of
+Kubernetes versions, so depending on it constrains which k8s a rig can be built
+with. That undercuts running trailing-edge control planes to model a legacy
+estate, which is the reason `versions.env` pins v1_33..v1_36. MetalLB carries no
+such constraint, so reachability costs nothing in version coverage.
+
+## Several rigs, one cluster
+
+Identity follows the **folder name**, the same rule rig uses for cluster
+identity. The namespace is the folder; resource names are generic, and names only
+have to be unique within a namespace.
+
+```bash
+cp -r sample-rig corporate-rig
+cd corporate-rig && make up      # its own namespace, its own address
+```
+
+No edits, no collisions, both in the same local cluster. `make list` shows them
+together. `make down` removes only this one — siblings, MetalLB and the cluster
+are left alone.
+
+Client rigs are gitignored (`*-rig/`, with `sample-rig/` the deliberate
+exception): a rig's k8s files spell out a real architecture, and that is exactly
+what must not land in this repo.
+
+## Staging workstations
+
+`ctrl/manifest.py` is stdlib-only on purpose: it runs on a bare machine before
+anything is installed. The toolchain itself is rig's job — `make deps` installs
+the pinned kind and tilt binaries, which is what makes a staging AWS workspace
+reachable from the same commands as a laptop.
+
+## Layout
+
+```
+sample-rig/
+├── Makefile            # thin — one target per ctrl/ script
+├── bundle.json         # what shipped; the UI renders THIS
+├── rig-ui/             # the vite app — optional, copied into a rig to enable it
+│   ├── k8s.yaml        #   how to plug it in: one Pod, one Service
+│   ├── index.html
+│   ├── package.json
+│   ├── vite.config.js
+│   └── src/{main.js,style.css}
+├── ctrl/
+│   ├── manifest.py     # emits the artifact
+│   └── bundle.sh       # generate / deploy / inspect
+└── generated/          # the artifact — committed, this is the deliverable
+```
+
+Editing `bundle.json` or anything in `rig-ui/` means re-running `make manifest`.
+The ConfigMap carries a checksum of everything embedded, so a stale deployment is
+visible rather than silent.
+
+## Not built, but not foreclosed
+
+Everything derives from `bundle.json` plus a target namespace. A Pulumi or
+Terraform emitter would sit beside `ctrl/manifest.py` consuming the same inputs;
+nothing above it assumes the artifact is YAML.
+
+Licence terms for the compiled UI component belong in the soleprint-generated
+bundle, not here — this sample carries no proprietary component.

rig/sample-rig/bundle.json

@@ -0,0 +1,51 @@
+{
+  "_comment": "What this bundle contains. Single source of truth — the landing page renders THIS file, so adding an entry here is the only edit needed. Deliberately FLAT: standalone tools and rigs, with none of soleprint's internal hierarchy (no artery/atlas/station layering). Nothing here is sensitive; the real architecture connects separately.",
+  "bundle": {
+    "name": "sample-rig",
+    "description": "Non-sensitive sample bundle. Proves the kind install works and shows what ships.",
+    "sensitive": false
+  },
+  "tools": [
+    {
+      "name": "modelgen",
+      "summary": "Generate models from config",
+      "standalone": true
+    },
+    {
+      "name": "datagen",
+      "summary": "Generate test data from rig-owned generators",
+      "standalone": true
+    },
+    {
+      "name": "graphgen",
+      "summary": "Generate navigable model graphs",
+      "standalone": true
+    },
+    {
+      "name": "tester",
+      "summary": "HTTP contract test runner — one suite, any environment",
+      "standalone": true
+    },
+    {
+      "name": "databrowse",
+      "summary": "SQL data browser",
+      "standalone": true
+    },
+    {
+      "name": "sbwrapper",
+      "summary": "Sandbox wrapper",
+      "standalone": true
+    }
+  ],
+  "rigs": [
+    {
+      "name": "sample-rig",
+      "summary": "This bundle — a minimal, copyable environment",
+      "active": true
+    }
+  ],
+  "next": [
+    "Point MANIFESTS_DIR at the real manifests to connect the actual architecture.",
+    "Real k8s files are versioned separately and are not part of this bundle."
+  ]
+}

rig/sample-rig/cluster.mock.json

@@ -0,0 +1,40 @@
+{
+  "_comment": "MOCKED cluster state. Nothing here is read from a live cluster — it exists so the UI can be shown when there is no cluster at all (a locked-down machine, a laptop with no memory to spare, a demo where kind will not start). The page labels it as mocked; a demo that looks live but is not is worse than one that says so. When a real cluster is present the same shapes come from kubectl.",
+
+  "mocked": true,
+
+  "cluster": {
+    "name": "sample-rig",
+    "context": "kind-sample-rig",
+    "provider": "kind",
+    "profile": "minimal",
+    "k8s": "v1.36.1",
+    "nodes": 1
+  },
+
+  "workloads": [
+    {
+      "name": "rig-ui",
+      "summary": "Pod · node:22-alpine · vite on :5173",
+      "state": "Running"
+    },
+    {
+      "name": "metallb-system/controller",
+      "summary": "Deployment · assigns LoadBalancer addresses",
+      "state": "Running"
+    },
+    {
+      "name": "metallb-system/speaker",
+      "summary": "DaemonSet · answers ARP in layer 2 mode",
+      "state": "Running"
+    }
+  ],
+
+  "services": [
+    {
+      "name": "rig-ui",
+      "summary": "LoadBalancer · 80 -> 5173 · no annotations, so it resolves on kind and on EKS alike",
+      "state": "172.18.255.200"
+    }
+  ]
+}

rig/sample-rig/ctrl/bundle.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# The rig bundle: generate it, deploy it, tear it down, find it.
+#
+# Usage: bundle.sh manifest | up | down | status | url | list | dev
+#
+# What `up` proves, in order: kind installed and a cluster exists, MetalLB can
+# hand out an address, a Service of type LoadBalancer actually resolves, and a
+# pod serves the bundle listing. If all of that works the installation is sound,
+# and the only thing missing is the real architecture.
+#
+# ONE ARTIFACT
+# `up` applies generated/<slug>.yaml — the same self-contained file you would
+# hand to an external cluster. There is no separate local path, so what works
+# here cannot quietly differ from the master deployment applied elsewhere.
+#
+# ONE CLUSTER, SEVERAL RIGS
+# Identity follows the FOLDER NAME, exactly as rig's cluster identity does. This
+# directory deploys into a namespace named after itself, so copying it to
+# corporate-rig/ yields a second rig in the SAME local cluster with no edits and
+# no collisions — different namespace, its own MetalLB address. `list` shows all
+# of them. The cluster itself is rig's business; this only ever owns a namespace.
+#
+# MetalLB is installed by calling rig's own addon script rather than
+# reimplementing it — deriving the pool from the kind Docker network is the
+# fiddly part and there should be exactly one copy of it.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+BUNDLE_ROOT="$(pwd)"
+RIG_CTRL="$(cd .. && pwd)/ctrl"
+
+# The containing folder's name, reduced to a DNS label (same rule as rig's
+# default_cluster_name and ctrl/manifest.py, so all three agree on the slug).
+slug() {
+    local n
+    n=$(basename "$BUNDLE_ROOT")
+    n=$(echo "$n" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-')
+    n=$(echo "$n" | sed 's/^-*//; s/-*$//')
+    echo "${n:-rig-bundle}"
+}
+NS="$(slug)"
+ARTIFACT="generated/${NS}.yaml"
+
+# Resolved lazily, not at load time: `manifest` and `dev` deliberately work
+# with no cluster and no kubectl at all, and a top-level check would break that.
+#
+# Follows whatever context rig's cluster.sh selected, so this bundle works in a
+# copied-and-renamed environment without being told which cluster it is in.
+init_kube() {
+    KUBECONTEXT="${KUBECONTEXT:-$(kubectl config current-context 2>/dev/null || true)}"
+    if [ -z "$KUBECONTEXT" ]; then
+        echo "no kubectl context — bring a cluster up first:  (cd .. && make cluster up)" >&2
+        exit 1
+    fi
+    KCTX="kubectl --context ${KUBECONTEXT}"
+    K="kubectl --context ${KUBECONTEXT} --namespace ${NS}"
+}
+
+require_cluster() {
+    if ! $KCTX cluster-info >/dev/null 2>&1; then
+        echo "context '$KUBECONTEXT' does not reach a cluster" >&2
+        echo "bring one up:  (cd .. && make cluster up)" >&2
+        exit 1
+    fi
+}
+
+ensure_metallb() {
+    if $KCTX get deployment -n metallb-system controller >/dev/null 2>&1; then
+        echo "metallb: present"
+        return 0
+    fi
+
+    # Only kind needs it. On a real cluster the cloud load balancer answers a
+    # `type: LoadBalancer` Service, and installing MetalLB there would be wrong.
+    case "$KUBECONTEXT" in
+        kind-*) ;;
+        *)
+            echo "metallb: skipped — '$KUBECONTEXT' is not a kind context"
+            echo "  (a cloud load balancer answers LoadBalancer services there)"
+            return 0
+            ;;
+    esac
+
+    if [ ! -f "$RIG_CTRL/addons/metallb.sh" ]; then
+        echo "metallb is not installed and rig's addon script was not found at" >&2
+        echo "  $RIG_CTRL/addons/metallb.sh" >&2
+        echo "a Service of type LoadBalancer will sit at <pending> without it." >&2
+        exit 1
+    fi
+
+    # rig's addons derive their target cluster from RIG'S OWN folder name via
+    # load_config, so left alone this bundle would install into `kind-rig` —
+    # a cluster that need not exist — while deploying everything else into the
+    # context actually selected. CLUSTER is in load_config's overridable set,
+    # so passing it here points the addon at the same cluster we are using.
+    local target="${KUBECONTEXT#kind-}"
+    echo "metallb: installing via rig's addon into '$target'"
+    CLUSTER="$target" bash "$RIG_CTRL/addons/metallb.sh"
+}
+
+# Regenerate the artifact. No cluster and no kubectl required — this is the step
+# a staging workstation runs before anything is installed.
+manifest() {
+    mkdir -p generated
+    python3 ctrl/manifest.py "$NS" > "$ARTIFACT"
+    echo "wrote $ARTIFACT ($(wc -l < "$ARTIFACT") lines)"
+    echo "  applies as-is anywhere:  kubectl apply -f ${BUNDLE_ROOT}/${ARTIFACT}"
+}
+
+up() {
+    manifest
+    init_kube
+    require_cluster
+    ensure_metallb
+
+    echo
+    echo "applying '${NS}' to context '${KUBECONTEXT}'"
+    $KCTX apply -f "$ARTIFACT"
+
+    # `rollout status` does not work on a bare Pod — it only understands
+    # Deployments, StatefulSets and DaemonSets. Wait on the condition instead.
+    # This is the slow step: the container npm-installs before vite serves.
+    echo "waiting for the pod to be ready (npm install runs first)..."
+    $K wait --for=condition=Ready pod/rig-ui --timeout=300s
+    echo
+    url
+}
+
+down() {
+    init_kube
+    # Delete the namespace and everything in it goes with it. Scoped to THIS
+    # rig — a sibling rig in the same cluster is untouched.
+    $KCTX delete namespace "$NS" --ignore-not-found
+    echo "'${NS}' removed (cluster, metallb and any sibling rig are left alone)"
+}
+
+status() {
+    init_kube
+    require_cluster
+    if ! $KCTX get namespace "$NS" >/dev/null 2>&1; then
+        echo "'${NS}' is not deployed — run: make up"
+        return 0
+    fi
+    $K get pod,svc,configmap -o wide
+}
+
+# Every rig in this cluster, not just this one — the point of the namespace
+# split is that several coexist, so there has to be a way to see them together.
+list() {
+    init_kube
+    require_cluster
+    local names
+    names=$($KCTX get namespace -l rig.bundle/name \
+            -o jsonpath='{.items[*].metadata.name}' 2>/dev/null || true)
+    if [ -z "$names" ]; then
+        echo "no rigs deployed in context '${KUBECONTEXT}'"
+        return 0
+    fi
+    printf "%-20s %-16s %s\n" RIG ADDRESS ""
+    local n ip
+    for n in $names; do
+        ip=$($KCTX -n "$n" get svc rig-ui \
+             -o jsonpath='{.status.loadBalancer.ingress[0].ip}' 2>/dev/null || true)
+        printf "%-20s %-16s %s\n" "$n" "${ip:-<pending>}" \
+            "$([ "$n" = "$NS" ] && echo '<- this one')"
+    done
+}
+
+# The address MetalLB (or a cloud load balancer) assigned. <pending> here is the
+# classic silent failure: everything reports healthy and nothing is reachable.
+url() {
+    init_kube
+    local ip
+    ip=$($K get svc rig-ui \
+         -o jsonpath='{.status.loadBalancer.ingress[0].ip}' 2>/dev/null || true)
+    if [ -z "$ip" ]; then
+        ip=$($K get svc rig-ui \
+             -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' 2>/dev/null || true)
+    fi
+    if [ -z "$ip" ]; then
+        echo "no external address yet — nothing has assigned one."
+        echo "on kind:  kubectl --context $KUBECONTEXT -n metallb-system get pods"
+        return 1
+    fi
+    echo "IT WORKS -> http://${ip}/"
+    echo "  bundle    http://${ip}/bundle.json"
+}
+
+# Run the UI locally with no cluster at all — the fast way to iterate on
+# bundle.json. Same vite command the pod runs, so what you see here is what
+# gets served there.
+dev() {
+    if ! command -v npm >/dev/null 2>&1; then
+        echo "npm not found — the UI needs node locally for this." >&2
+        echo "(in-cluster it runs on the node:22-alpine image instead)" >&2
+        exit 1
+    fi
+    # bundle.json lives one level up so it stays the rig's data rather than the
+    # app's; vite serves public/ at the root, which is where the app fetches it.
+    mkdir -p rig-ui/public
+    cp bundle.json rig-ui/public/bundle.json
+
+    # The mocked cluster is a DEMO asset and is deliberately not embedded in the
+    # deployed artifact — on a real rig the UI would then show canned values
+    # beside a live cluster, which is precisely the lie its banner warns about.
+    # It is served here, and in the static build for the public UI-only page.
+    cp cluster.mock.json rig-ui/public/cluster.mock.json
+
+    cd rig-ui
+    [ -d node_modules ] || npm install --no-audit --no-fund
+    VITE_RIG_NAME="$NS" npm run dev
+}
+
+case "${1:-status}" in
+    manifest) manifest ;;
+    up)       up ;;
+    down)     down ;;
+    status)   status ;;
+    url)      url ;;
+    list)     list ;;
+    dev)      dev ;;
+    *)        echo "usage: $0 [manifest|up|down|status|url|list|dev]" >&2; exit 1 ;;
+esac

rig/sample-rig/ctrl/manifest.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Emit the complete, self-contained deployment for this rig.
+
+    python3 ctrl/manifest.py [namespace] > generated/<slug>.yaml
+
+The output is the ARTIFACT. It carries everything — namespace, the vite app and
+bundle.json embedded in a ConfigMap, the Pod and the Service — so it applies
+unmodified to any cluster:
+
+    kubectl apply -f generated/sample-rig.yaml
+
+On kind, MetalLB answers the `type: LoadBalancer` Service. On a real external
+cluster the cloud load balancer does. Same file, no edits, no branch — which is
+the point: what runs locally is byte-identical to the deployment applied
+elsewhere, so local success actually means something.
+
+`ctrl/bundle.sh up` applies this same generated output rather than a separate
+code path, so the local convenience wrapper can never drift from the artifact.
+
+Stdlib only, deliberately: this must run on a bare staging workstation before
+anything is installed, so it cannot depend on PyYAML or a template engine.
+
+Open seam — not built: everything here derives from bundle.json plus a target
+namespace. A Pulumi or Terraform emitter would sit beside this file consuming the
+same inputs; nothing above it assumes the artifact is YAML.
+"""
+
+import json
+import re
+import sys
+import zlib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+UI = ROOT / "rig-ui"
+
+# Files embedded into the ConfigMap, mounted read-only at /src in the pod and
+# copied into vite's layout at start (see rig-ui/k8s.yaml). Flat on purpose:
+# ConfigMap keys cannot contain '/'.
+EMBEDDED = {
+    "bundle.json": ROOT / "bundle.json",
+    "package.json": UI / "package.json",
+    "vite.config.js": UI / "vite.config.js",
+    "index.html": UI / "index.html",
+    "main.js": UI / "src" / "main.js",
+    "style.css": UI / "src" / "style.css",
+}
+
+
+def slug(name: str) -> str:
+    """Reduce a folder name to a DNS label, matching ctrl/bundle.sh's rule."""
+    out = re.sub(r"[^a-z0-9-]", "-", name.lower()).strip("-")
+    return out or "rig-bundle"
+
+
+def block(text: str, indent: int) -> str:
+    """Indent a file's contents for a YAML literal block scalar.
+
+    Blank lines are emitted truly empty rather than as whitespace: trailing
+    spaces on an otherwise blank line are legal YAML but show up as diff noise
+    in a committed artifact.
+    """
+    pad = " " * indent
+    return "\n".join(pad + line if line.strip() else "" for line in text.splitlines())
+
+
+def checksum(parts: list[str]) -> str:
+    """Stable content hash of everything embedded, stamped as a label.
+
+    A mounted ConfigMap updates in place without restarting anything, so without
+    a visible change nothing signals that the pod is serving stale content.
+    """
+    return str(zlib.crc32("".join(parts).encode()) & 0xFFFFFFFF)
+
+
+def build(namespace: str) -> str:
+    contents = {}
+    for key, path in EMBEDDED.items():
+        if not path.exists():
+            sys.exit(f"missing input: {path}")
+        contents[key] = path.read_text()
+
+    # Fail loudly here rather than shipping an artifact that renders an error.
+    try:
+        json.loads(contents["bundle.json"])
+    except json.JSONDecodeError as exc:
+        sys.exit(f"bundle.json is not valid JSON: {exc}")
+
+    app = (UI / "k8s.yaml").read_text()
+    app = app.replace("__RIG_NAME__", namespace)
+
+    data = "\n".join(
+        f"  {key}: |\n{block(text, 4)}" for key, text in sorted(contents.items())
+    )
+
+    return f"""# GENERATED by ctrl/manifest.py — do not edit.
+# Regenerate with:  make manifest
+#
+# Self-contained: applies as-is to any cluster, local kind or external.
+#   kubectl apply -f this-file.yaml
+#
+# Namespace carries the identity, so several rigs coexist in one cluster.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {namespace}
+  labels:
+    rig.bundle/name: {namespace}
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: rig-ui
+  namespace: {namespace}
+  labels:
+    rig.bundle/checksum: "{checksum(list(contents.values()))}"
+data:
+{data}
+---
+{_namespaced(app, namespace)}
+"""
+
+
+def _namespaced(doc: str, namespace: str) -> str:
+    """Add `namespace:` to each resource so the artifact applies without -n.
+
+    rig-ui/k8s.yaml omits it on purpose — applied by hand it should land in
+    whatever namespace you choose. Pinning it belongs to the generated artifact,
+    which has to be self-contained.
+    """
+    return re.sub(
+        r"^(metadata:\n(?:[ \t]+.*\n)*?)([ \t]+)(name: rig-ui)$",
+        lambda m: f"{m.group(1)}{m.group(2)}{m.group(3)}\n{m.group(2)}namespace: {namespace}",
+        doc.strip(),
+        flags=re.MULTILINE,
+    )
+
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else slug(ROOT.name)
+    sys.stdout.write(build(target))

rig/sample-rig/generated/sample-rig.yaml

@@ -0,0 +1,406 @@
+# GENERATED by ctrl/manifest.py — do not edit.
+# Regenerate with:  make manifest
+#
+# Self-contained: applies as-is to any cluster, local kind or external.
+#   kubectl apply -f this-file.yaml
+#
+# Namespace carries the identity, so several rigs coexist in one cluster.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: sample-rig
+  labels:
+    rig.bundle/name: sample-rig
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: rig-ui
+  namespace: sample-rig
+  labels:
+    rig.bundle/checksum: "2074194964"
+data:
+  bundle.json: |
+    {
+      "_comment": "What this bundle contains. Single source of truth — the landing page renders THIS file, so adding an entry here is the only edit needed. Deliberately FLAT: standalone tools and rigs, with none of soleprint's internal hierarchy (no artery/atlas/station layering). Nothing here is sensitive; the real architecture connects separately.",
+      "bundle": {
+        "name": "sample-rig",
+        "description": "Non-sensitive sample bundle. Proves the kind install works and shows what ships.",
+        "sensitive": false
+      },
+      "tools": [
+        {
+          "name": "modelgen",
+          "summary": "Generate models from config",
+          "standalone": true
+        },
+        {
+          "name": "datagen",
+          "summary": "Generate test data from rig-owned generators",
+          "standalone": true
+        },
+        {
+          "name": "graphgen",
+          "summary": "Generate navigable model graphs",
+          "standalone": true
+        },
+        {
+          "name": "tester",
+          "summary": "HTTP contract test runner — one suite, any environment",
+          "standalone": true
+        },
+        {
+          "name": "databrowse",
+          "summary": "SQL data browser",
+          "standalone": true
+        },
+        {
+          "name": "sbwrapper",
+          "summary": "Sandbox wrapper",
+          "standalone": true
+        }
+      ],
+      "rigs": [
+        {
+          "name": "sample-rig",
+          "summary": "This bundle — a minimal, copyable environment",
+          "active": true
+        }
+      ],
+      "next": [
+        "Point MANIFESTS_DIR at the real manifests to connect the actual architecture.",
+        "Real k8s files are versioned separately and are not part of this bundle."
+      ]
+    }
+  index.html: |
+    <!doctype html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>IT WORKS</title>
+      </head>
+      <body>
+        <main id="app"></main>
+        <script type="module" src="/src/main.js"></script>
+      </body>
+    </html>
+  main.js: |
+    import "./style.css";
+
+    /* The IT WORKS page: renders bundle.json as the list of what shipped.
+     *
+     * Plain vite, no framework — this is a complement to the rig, not part of it,
+     * and it should stay small enough that nobody has to adopt a stack to read it.
+     *
+     * bundle.json is fetched at runtime rather than imported, so the same built app
+     * serves whatever rig it was copied into. Editing the ConfigMap changes the page
+     * without rebuilding.
+     *
+     * Styling is a handful of rules on purpose. The real visual identity lives in
+     * the soleprint UI package; nothing here should grow into a theme.
+     */
+
+    const esc = (s) =>
+      String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+    const tag = (text, on = false) =>
+      `<span class="tag${on ? " on" : ""}">${esc(text)}</span>`;
+
+    function items(list, activeKey) {
+      if (!list?.length) return `<li><span class="summary">nothing listed</span></li>`;
+      return list
+        .map((it) => {
+          const tags = [
+            it.standalone ? tag("standalone") : "",
+            it.state ? tag(it.state) : "",
+            activeKey && it[activeKey] ? tag("active", true) : "",
+          ].join("");
+          return `<li><span class="name">${esc(it.name ?? "?")}</span>
+            <span class="summary">${esc(it.summary ?? "")}</span>${tags}</li>`;
+        })
+        .join("");
+    }
+
+    /* Cluster state, when there is any to show.
+     *
+     * Fetched separately and allowed to fail: the bundle listing is the point, and a
+     * rig with no cluster reachable is a normal state, not an error. Renders nothing
+     * at all when absent.
+     *
+     * When the payload says `mocked`, say so loudly. This exists to demo the UI on a
+     * machine where kind will not run — and a demo that looks live but is not is
+     * worse than one that admits it. */
+    function clusterSection(c) {
+      if (!c) return "";
+      const m = c.cluster ?? {};
+      const banner = c.mocked
+        ? `<p class="mock">mocked — no cluster was queried; these are canned values</p>`
+        : "";
+      const meta = [m.context, m.k8s, m.profile ? `profile ${m.profile}` : "",
+                    m.nodes ? `${m.nodes} node${m.nodes > 1 ? "s" : ""}` : ""]
+        .filter(Boolean).join(" · ");
+
+      return `
+        <h2>Cluster${c.mocked ? " (mocked)" : ""}</h2>
+        ${banner}
+        ${meta ? `<p class="sub">${esc(meta)}</p>` : ""}
+        <ul>${items(c.workloads)}</ul>
+        <h2>Services (${c.services?.length ?? 0})</h2>
+        <ul>${items(c.services)}</ul>`;
+    }
+
+    function render(b, name, cluster) {
+      const meta = b.bundle ?? {};
+      const next = (b.next ?? []).map((n) => `<li>${esc(n)}</li>`).join("");
+      return `
+        <h1><span class="ok">IT WORKS</span> — ${esc(name || meta.name || "rig")}</h1>
+        <p class="sub">${esc(meta.description ?? "")}</p>
+
+        <h2>Tools (${b.tools?.length ?? 0})</h2>
+        <ul>${items(b.tools)}</ul>
+
+        <h2>Rigs (${b.rigs?.length ?? 0})</h2>
+        <ul>${items(b.rigs, "active")}</ul>
+
+        ${clusterSection(cluster)}
+
+        ${next ? `<div class="next"><ul>${next}</ul></div>` : ""}`;
+    }
+
+    const app = document.getElementById("app");
+
+    const json = (path, required) =>
+      fetch(path).then((r) => {
+        if (r.ok) return r.json();
+        if (required) throw new Error(`${path} -> HTTP ${r.status}`);
+        return null;            // optional: absent is a normal state, not an error
+      }).catch((err) => {
+        if (required) throw err;
+        return null;
+      });
+
+    Promise.all([json("/bundle.json", true), json("/cluster.mock.json", false)])
+      // RIG_NAME is injected by vite from the pod env, so two rigs sharing a
+      // cluster are distinguishable even if a copied bundle.json kept its old name.
+      .then(([b, cluster]) => {
+        app.innerHTML = render(b, import.meta.env.VITE_RIG_NAME, cluster);
+      })
+      .catch((err) => {
+        app.innerHTML = `<h1 class="err">bundle unavailable</h1>
+          <p class="sub">${esc(err.message)}</p>`;
+      });
+  package.json: |
+    {
+      "name": "rig-ui",
+      "private": true,
+      "version": "0.1.0",
+      "type": "module",
+      "scripts": {
+        "dev": "vite --host 0.0.0.0 --port 5173",
+        "build": "vite build",
+        "preview": "vite preview --host 0.0.0.0 --port 5173"
+      },
+      "devDependencies": {
+        "vite": "^6"
+      }
+    }
+  style.css: |
+    /* Minimal, self-contained. The real visual identity ships with the soleprint UI
+       package, which is a separate artifact — nothing here should grow into a theme. */
+
+    body {
+      margin: 0;
+      padding: 2.5rem 1.5rem;
+      background: #0d0d0f;
+      color: #e8e8f0;
+      font: 14px/1.6 ui-monospace, "JetBrains Mono", Menlo, monospace;
+    }
+    main { max-width: 52rem; margin: 0 auto; }
+
+    h1 { margin: 0; font-size: 1.6rem; letter-spacing: 0.02em; }
+    h1 .ok { color: #3ecf8e; }
+    h1.err { color: #f06565; }
+    .sub { color: #8888a0; margin: 0.35rem 0 2.25rem; }
+
+    h2 {
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.12em;
+      color: #8888a0;
+      margin: 2rem 0 0.75rem;
+      font-weight: 600;
+    }
+
+    ul { list-style: none; margin: 0; padding: 0; }
+    li {
+      display: flex;
+      gap: 0.75rem;
+      align-items: baseline;
+      padding: 0.5rem 0.75rem;
+      border: 1px solid #2e2e38;
+      border-radius: 6px;
+      margin-bottom: 0.4rem;
+      background: #16161a;
+    }
+    .name { font-weight: 600; min-width: 9rem; }
+    .summary { color: #8888a0; flex: 1; }
+
+    .tag {
+      font-size: 0.7rem;
+      padding: 0.1rem 0.45rem;
+      border-radius: 3px;
+      background: #26262f;
+      color: #8888a0;
+      white-space: nowrap;
+    }
+    .tag.on { background: #3ecf8e; color: #0d0d0f; }
+
+    .next {
+      color: #555568;
+      font-size: 0.8rem;
+      margin-top: 2.5rem;
+      border-top: 1px solid #2e2e38;
+      padding-top: 1rem;
+    }
+    .next li {
+      display: list-item;
+      border: 0;
+      background: none;
+      padding: 0.15rem 0;
+      margin: 0 0 0 1.1rem;
+      list-style: disc;
+    }
+
+    /* Mocked-data banner. Deliberately loud: this only appears when the cluster
+       payload is canned, and a demo that looks live but is not is worse than one
+       that says so. */
+    .mock {
+      margin: 0 0 0.75rem;
+      padding: 0.4rem 0.75rem;
+      border: 1px dashed #f5a623;
+      border-radius: 6px;
+      color: #f5a623;
+      font-size: 0.8rem;
+    }
+  vite.config.js: |
+    import { defineConfig } from "vite";
+
+    /* Serves on 0.0.0.0 so the pod is reachable through the Service, and allows any
+     * Host header because the address is assigned at runtime (MetalLB locally, a
+     * cloud load balancer on EKS) and is never known at build time. */
+    export default defineConfig({
+      server: { host: "0.0.0.0", port: 5173, strictPort: true, allowedHosts: true },
+      preview: { host: "0.0.0.0", port: 5173, strictPort: true, allowedHosts: true },
+    });
+---
+# How to plug the UI into whatever k8s you generated. THIS IS THE WHOLE THING:
+# one Pod running the vite app, one Service to reach it.
+#
+# Optional by design. The UI complements a rig; it is not part of the end
+# product, and a rig is complete and useful without it. Apply this only when you
+# want the listing:
+#
+#   kubectl apply -n <your-namespace> -f rig-ui/k8s.yaml
+#
+# A bare Pod, not a Deployment — this is a dev-loop convenience, not a workload
+# to keep alive. If it dies you re-apply it; nothing depends on it staying up.
+#
+# The app and bundle.json arrive as a ConfigMap named `rig-ui`, which
+# ctrl/manifest.py generates from the folder. Nothing is baked into an image, so
+# editing bundle.json and re-applying is the whole update cycle.
+apiVersion: v1
+kind: Pod
+metadata:
+  name: rig-ui
+  namespace: sample-rig
+  labels:
+    app: rig-ui
+spec:
+  containers:
+    - name: vite
+      image: node:22-alpine
+      workingDir: /app
+      # npm install at start: no image to build and no registry to publish to,
+      # which is the point of a minimal plug-in. It needs egress to a registry —
+      # on a locked-down cluster point npm at the internal one, or bake an image
+      # instead. Nothing else here changes if you do.
+      command: ["sh", "-c"]
+      # A ConfigMap mounts flat (keys cannot contain '/'), so the files are
+      # placed into vite's expected layout here. bundle.json goes to public/
+      # because that is what vite serves at /bundle.json, which is where the
+      # app fetches it.
+      args:
+        - |
+          mkdir -p /app/src /app/public &&
+          cp /src/package.json /src/vite.config.js /src/index.html /app/ &&
+          cp /src/main.js /src/style.css /app/src/ &&
+          cp /src/bundle.json /app/public/ &&
+          npm install --no-audit --no-fund &&
+          npm run dev
+      env:
+        # Rendered in the heading so two rigs sharing a cluster stay
+        # distinguishable. Set from the namespace by ctrl/manifest.py.
+        - name: VITE_RIG_NAME
+          value: sample-rig
+      ports:
+        - name: http
+          containerPort: 5173
+      volumeMounts:
+        # /src is read-only from the ConfigMap; the app is copied to a writable
+        # /app because npm install has to create node_modules.
+        - name: rig-ui
+          mountPath: /src
+        - name: app
+          mountPath: /app
+      readinessProbe:
+        httpGet: { path: /, port: 5173 }
+        # npm install decides how long this takes, and it is the slow part.
+        initialDelaySeconds: 15
+        periodSeconds: 5
+        failureThreshold: 30
+      resources:
+        requests: { memory: 128Mi, cpu: 50m }
+        limits: { memory: 512Mi }
+  volumes:
+    - name: rig-ui
+      configMap:
+        name: rig-ui
+    - name: app
+      emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: rig-ui
+  namespace: sample-rig
+  labels:
+    app: rig-ui
+  # No annotations, deliberately — see k8s/app.yaml. The target is EKS but this
+  # stays VPC-agnostic: no subnets, no security groups, no -scheme, no -type.
+  # A bare LoadBalancer is what lets one manifest work on kind and on EKS.
+spec:
+  type: LoadBalancer
+  selector:
+    app: rig-ui
+  ports:
+    - name: http
+      port: 80
+      targetPort: 5173
+      protocol: TCP
+      # Pinned, because a LoadBalancer Service also allocates a NodePort and
+      # this is the only address that works everywhere.
+      #
+      # On WSL the MetalLB address is on a docker bridge INSIDE the Linux VM,
+      # and Windows has no route to it — the page looks broken while the
+      # cluster is perfectly healthy. 30080 is what rig's `hostport` ingress
+      # mode publishes to the host, so this is reachable at
+      # localhost:$HTTP_PORT from a Windows browser with nothing configured.
+      #
+      # Costs nothing elsewhere: MetalLB still assigns an external IP on Linux,
+      # and on EKS the load balancer targets this NodePort anyway. One Service,
+      # no per-environment branch.
+      #
+      # A pinned NodePort is cluster-unique, so two rigs must live in separate
+      # clusters — which is how they are run anyway.
+      nodePort: 30080

rig/sample-rig/rig-ui/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+public/
+dist/

rig/sample-rig/rig-ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>IT WORKS</title>
+  </head>
+  <body>
+    <main id="app"></main>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

rig/sample-rig/rig-ui/k8s.yaml

@@ -0,0 +1,108 @@
+# How to plug the UI into whatever k8s you generated. THIS IS THE WHOLE THING:
+# one Pod running the vite app, one Service to reach it.
+#
+# Optional by design. The UI complements a rig; it is not part of the end
+# product, and a rig is complete and useful without it. Apply this only when you
+# want the listing:
+#
+#   kubectl apply -n <your-namespace> -f rig-ui/k8s.yaml
+#
+# A bare Pod, not a Deployment — this is a dev-loop convenience, not a workload
+# to keep alive. If it dies you re-apply it; nothing depends on it staying up.
+#
+# The app and bundle.json arrive as a ConfigMap named `rig-ui`, which
+# ctrl/manifest.py generates from the folder. Nothing is baked into an image, so
+# editing bundle.json and re-applying is the whole update cycle.
+apiVersion: v1
+kind: Pod
+metadata:
+  name: rig-ui
+  labels:
+    app: rig-ui
+spec:
+  containers:
+    - name: vite
+      image: node:22-alpine
+      workingDir: /app
+      # npm install at start: no image to build and no registry to publish to,
+      # which is the point of a minimal plug-in. It needs egress to a registry —
+      # on a locked-down cluster point npm at the internal one, or bake an image
+      # instead. Nothing else here changes if you do.
+      command: ["sh", "-c"]
+      # A ConfigMap mounts flat (keys cannot contain '/'), so the files are
+      # placed into vite's expected layout here. bundle.json goes to public/
+      # because that is what vite serves at /bundle.json, which is where the
+      # app fetches it.
+      args:
+        - |
+          mkdir -p /app/src /app/public &&
+          cp /src/package.json /src/vite.config.js /src/index.html /app/ &&
+          cp /src/main.js /src/style.css /app/src/ &&
+          cp /src/bundle.json /app/public/ &&
+          npm install --no-audit --no-fund &&
+          npm run dev
+      env:
+        # Rendered in the heading so two rigs sharing a cluster stay
+        # distinguishable. Set from the namespace by ctrl/manifest.py.
+        - name: VITE_RIG_NAME
+          value: __RIG_NAME__
+      ports:
+        - name: http
+          containerPort: 5173
+      volumeMounts:
+        # /src is read-only from the ConfigMap; the app is copied to a writable
+        # /app because npm install has to create node_modules.
+        - name: rig-ui
+          mountPath: /src
+        - name: app
+          mountPath: /app
+      readinessProbe:
+        httpGet: { path: /, port: 5173 }
+        # npm install decides how long this takes, and it is the slow part.
+        initialDelaySeconds: 15
+        periodSeconds: 5
+        failureThreshold: 30
+      resources:
+        requests: { memory: 128Mi, cpu: 50m }
+        limits: { memory: 512Mi }
+  volumes:
+    - name: rig-ui
+      configMap:
+        name: rig-ui
+    - name: app
+      emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: rig-ui
+  labels:
+    app: rig-ui
+  # No annotations, deliberately — see k8s/app.yaml. The target is EKS but this
+  # stays VPC-agnostic: no subnets, no security groups, no -scheme, no -type.
+  # A bare LoadBalancer is what lets one manifest work on kind and on EKS.
+spec:
+  type: LoadBalancer
+  selector:
+    app: rig-ui
+  ports:
+    - name: http
+      port: 80
+      targetPort: 5173
+      protocol: TCP
+      # Pinned, because a LoadBalancer Service also allocates a NodePort and
+      # this is the only address that works everywhere.
+      #
+      # On WSL the MetalLB address is on a docker bridge INSIDE the Linux VM,
+      # and Windows has no route to it — the page looks broken while the
+      # cluster is perfectly healthy. 30080 is what rig's `hostport` ingress
+      # mode publishes to the host, so this is reachable at
+      # localhost:$HTTP_PORT from a Windows browser with nothing configured.
+      #
+      # Costs nothing elsewhere: MetalLB still assigns an external IP on Linux,
+      # and on EKS the load balancer targets this NodePort anyway. One Service,
+      # no per-environment branch.
+      #
+      # A pinned NodePort is cluster-unique, so two rigs must live in separate
+      # clusters — which is how they are run anyway.
+      nodePort: 30080

rig/sample-rig/rig-ui/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "rig-ui",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0 --port 5173",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0 --port 5173"
+  },
+  "devDependencies": {
+    "vite": "^6"
+  }
+}

rig/sample-rig/rig-ui/src/main.js

@@ -0,0 +1,136 @@
+import "./style.css";
+
+/* The IT WORKS page: renders bundle.json as the list of what shipped.
+ *
+ * Plain vite, no framework — this is a complement to the rig, not part of it,
+ * and it should stay small enough that nobody has to adopt a stack to read it.
+ *
+ * Laid out like soleprint's templated vein pages, because it does the same job:
+ * name each component, list what it exposes, show what comes back. Tool chrome
+ * and output are styled apart on purpose (see style.css) — that separation is
+ * what tells you whether you are reading the tool or its result.
+ *
+ * bundle.json is fetched at runtime rather than imported, so the same built app
+ * serves whatever rig it was copied into. Editing the ConfigMap changes the page
+ * without rebuilding.
+ */
+
+const esc = (s) =>
+  String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const tag = (text, on = false) =>
+  `<span class="tag${on ? " on" : ""}">${esc(text)}</span>`;
+
+/* Tool chrome: one bordered card per component. */
+function components(list, activeKey) {
+  if (!list?.length)
+    return `<div class="component"><p>nothing listed</p></div>`;
+  return list
+    .map((it) => {
+      const tags = [
+        it.standalone ? tag("standalone") : "",
+        it.state ? tag(it.state) : "",
+        activeKey && it[activeKey] ? tag("active", true) : "",
+      ].join("");
+      return `<div class="component">
+        <h4>${esc(it.name ?? "?")} ${tags}</h4>
+        <p>${esc(it.summary ?? "")}</p>
+      </div>`;
+    })
+    .join("");
+}
+
+/* Endpoint rows: path on the left, what it returns on the right. */
+function endpoints(list) {
+  return list
+    .map(
+      (e) => `<li><code>${esc(e.path)}</code>
+        <span class="desc">${esc(e.desc)}</span></li>`
+    )
+    .join("");
+}
+
+/* Output: what the endpoint above actually returns, so the page demonstrates
+   itself rather than describing what a demonstration would look like. */
+function example(bundle) {
+  const sample = {
+    bundle: bundle.bundle?.name,
+    tools: (bundle.tools ?? []).map((t) => t.name),
+    rigs: (bundle.rigs ?? []).map((r) => r.name),
+  };
+  return `<pre class="output">${esc(JSON.stringify(sample, null, 2))}</pre>`;
+}
+
+/* Cluster state, when there is any to show.
+ *
+ * Fetched separately and allowed to fail: the bundle listing is the point, and a
+ * rig with no cluster reachable is a normal state, not an error. Renders nothing
+ * at all when absent. When the payload says `mocked`, say so loudly. */
+function clusterSection(c) {
+  if (!c) return "";
+  const m = c.cluster ?? {};
+  const meta = [m.context, m.k8s, m.profile && `profile ${m.profile}`,
+                m.nodes && `${m.nodes} node${m.nodes > 1 ? "s" : ""}`]
+    .filter(Boolean).join(" · ");
+
+  return `
+    <h2>Cluster${c.mocked ? " (mocked)" : ""}</h2>
+    ${c.mocked ? `<p class="mock">mocked — no cluster was queried; these are canned values</p>` : ""}
+    ${meta ? `<p class="tagline">${esc(meta)}</p>` : ""}
+    <div class="components">${components(c.workloads)}</div>
+
+    <h2>Services</h2>
+    <div class="components">${components(c.services)}</div>`;
+}
+
+function render(b, name, cluster) {
+  const meta = b.bundle ?? {};
+  const next = (b.next ?? []).map((n) => `<li>${esc(n)}</li>`).join("");
+  return `
+    <h1><span class="ok">IT WORKS</span> — ${esc(name || meta.name || "rig")}</h1>
+    <p class="tagline">${esc(meta.description ?? "")}</p>
+
+    <h2>Tools (${b.tools?.length ?? 0})</h2>
+    <div class="components">${components(b.tools)}</div>
+
+    <h2>Rigs (${b.rigs?.length ?? 0})</h2>
+    <div class="components">${components(b.rigs, "active")}</div>
+
+    <h2>Endpoints</h2>
+    <ul class="endpoints">${endpoints([
+      { path: "/", desc: "this page" },
+      { path: "/bundle.json", desc: "the manifest it renders" },
+    ])}</ul>
+
+    <h2>Example — GET /bundle.json</h2>
+    ${example(b)}
+
+    ${clusterSection(cluster)}
+
+    ${next ? `<div class="next"><ul>${next}</ul></div>` : ""}`;
+}
+
+const app = document.getElementById("app");
+
+const json = (path, required) =>
+  fetch(path)
+    .then((r) => {
+      if (r.ok) return r.json();
+      if (required) throw new Error(`${path} -> HTTP ${r.status}`);
+      return null; // optional: absent is a normal state, not an error
+    })
+    .catch((err) => {
+      if (required) throw err;
+      return null;
+    });
+
+Promise.all([json("/bundle.json", true), json("/cluster.mock.json", false)])
+  // RIG_NAME is injected by vite from the pod env, so two rigs sharing a
+  // cluster are distinguishable even if a copied bundle.json kept its old name.
+  .then(([b, cluster]) => {
+    app.innerHTML = render(b, import.meta.env.VITE_RIG_NAME, cluster);
+  })
+  .catch((err) => {
+    app.innerHTML = `<h1 class="err">bundle unavailable</h1>
+      <p class="tagline">${esc(err.message)}</p>`;
+  });

rig/sample-rig/rig-ui/src/style.css

@@ -0,0 +1,139 @@
+/* Minimal and self-contained — no framework dependency.
+ *
+ * The visual language follows soleprint's templated vein pages, because this
+ * page does the same job: say what a component is, list what it exposes, and
+ * show what comes back. Two treatments, deliberately distinct:
+ *
+ *   TOOL CHROME  bordered cards on the darker background, accent-coloured
+ *                titles, endpoint rows separated by rules.
+ *   OUTPUT       a lighter raised block, monospace, pre-wrap and selectable —
+ *                it is data, not furniture, and should read as a payload.
+ *
+ * Keeping them apart matters more than either looks: it is what tells you at a
+ * glance whether you are reading the tool or the thing it produced. */
+
+:root {
+  --bg: #0d0d0f;
+  --surface: #16161a;
+  --surface-raised: #1e1e24;
+  --border: #2e2e38;
+  --border-strong: #3d3d4a;
+  --text: #e8e8f0;
+  --muted: #8888a0;
+  --accent: #3ecf8e;
+  --accent-dim: #f5a623;
+  --mono: "JetBrains Mono", "Cascadia Mono", Consolas, ui-monospace, monospace;
+}
+
+body {
+  margin: 0;
+  padding: 2.5rem 1.5rem;
+  background: var(--bg);
+  color: var(--text);
+  font: 14px/1.6 var(--mono);
+}
+main { max-width: 56rem; margin: 0 auto; }
+
+h1 { margin: 0; font-size: 1.6rem; letter-spacing: 0.02em; }
+h1 .ok { color: var(--accent); }
+h1.err { color: #f06565; }
+.tagline { color: var(--muted); margin: 0.35rem 0 2.25rem; }
+
+h2 {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--muted);
+  margin: 2.25rem 0 0.75rem;
+  font-weight: 600;
+}
+
+/* ── tool chrome ────────────────────────────────────────────────────────── */
+
+.components {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 0.75rem;
+}
+
+.component {
+  background: var(--bg);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+.component h4 {
+  margin: 0 0 0.25rem;
+  font-size: 0.95rem;
+  color: var(--accent);
+}
+.component p {
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+.endpoints { list-style: none; margin: 0; padding: 0; }
+.endpoints li {
+  display: flex;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  padding: 0.6rem 0;
+  border-bottom: 1px solid var(--border-strong);
+}
+.endpoints li:last-child { border-bottom: none; }
+.endpoints code {
+  background: var(--surface);
+  color: var(--accent);
+  padding: 0.25rem 0.5rem;
+  border-radius: 4px;
+}
+.endpoints .desc { color: var(--muted); font-size: 0.9rem; }
+
+.tag {
+  font-size: 0.7rem;
+  padding: 0.1rem 0.45rem;
+  border-radius: 3px;
+  background: var(--border);
+  color: var(--muted);
+  white-space: nowrap;
+}
+.tag.on { background: var(--accent); color: var(--bg); }
+
+/* ── output ─────────────────────────────────────────────────────────────── */
+
+.output {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1rem;
+  font-size: 0.85rem;
+  white-space: pre-wrap;
+  word-break: break-word;
+  user-select: text;
+  color: var(--text);
+  margin: 0;
+}
+.output .k { color: var(--accent); }
+
+/* Mocked-data banner. Loud on purpose: it only appears when the payload is
+   canned, and a demo that looks live but is not is worse than one that says so. */
+.mock {
+  margin: 0 0 0.75rem;
+  padding: 0.4rem 0.75rem;
+  border: 1px dashed var(--accent-dim);
+  border-radius: 6px;
+  color: var(--accent-dim);
+  font-size: 0.8rem;
+}
+
+.next {
+  color: #555568;
+  font-size: 0.8rem;
+  margin-top: 2.5rem;
+  border-top: 1px solid var(--border);
+  padding-top: 1rem;
+}
+.next ul { margin: 0; padding: 0 0 0 1.1rem; }
+.next li { list-style: disc; padding: 0.15rem 0; }

rig/sample-rig/rig-ui/vite.config.js

@@ -0,0 +1,9 @@
+import { defineConfig } from "vite";
+
+/* Serves on 0.0.0.0 so the pod is reachable through the Service, and allows any
+ * Host header because the address is assigned at runtime (MetalLB locally, a
+ * cloud load balancer on EKS) and is never known at build time. */
+export default defineConfig({
+  server: { host: "0.0.0.0", port: 5173, strictPort: true, allowedHosts: true },
+  preview: { host: "0.0.0.0", port: 5173, strictPort: true, allowedHosts: true },
+});

soleprint/.dockerignore

@@ -0,0 +1,24 @@
+# The build context is gen/<room>/, and the Dockerfile is `COPY . .` — so this
+# file is the last thing standing between a stray secret and a public image
+# layer. build.py already filters these out of the copy into gen/; this repeats
+# the rule at the docker boundary so a hand-built context, or a future copy path
+# that forgets, still cannot bake one in.
+#
+# Copied into gen/<room>/ by build.py's named-file list alongside the Dockerfile.
+
+.env
+.env.*
+**/.env
+**/.env.*
+!.env.example
+!**/.env.example
+
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+
+.git/
+.venv/
+venv/
+node_modules/