big update based on real wokr

rig/docs/notes/addons.md

@@ -4,6 +4,12 @@
 
 Each addon is its own idempotent script — adding one is adding a file, not editing a dispatcher. `ADDONS` names them, in install order; the overlay's `addons/<name>.sh` is found before rig's `ctrl/addons/<name>.sh`, and every one runs from rig's `ctrl/` with `RIG_CTRL` exported, wherever its file lives (see [overlay.md](overlay.md)).
 
+## The manifest beside the script
+
+An addon's Kubernetes objects are a plain `<name>.yaml` beside its `<name>.sh`, not a heredoc inside it: the YAML reads, diffs and lints as YAML, and the script keeps only what YAML cannot do (secrets made once, a database created, waiting for a rollout). The script renders it with `render_manifest "$ADDON_DIR/<name>.yaml"` (`lib/config.sh`) and pipes it to `kubectl apply`.
+
+`render_manifest` fills `${NAME}` and `${NAME:-default}` from the loaded config or the script's own variables, and fails on a name nothing sets, so a typo is an error rather than an empty image. `$VAR` and `$(VAR)` are left alone: they are the container's, as in postgres' `pg_isready -U $POSTGRES_USER`. selftest checks that every name a manifest uses is set somewhere. `ADDON_DIR` is taken before the script's `cd` into rig's `ctrl/`: `ADDON_DIR="$(cd "$(dirname "$0")" && pwd)"`.
+
 ## What rig ships, and what it does not
 
 rig's own addons make the *cluster* work, and are useless outside one: metallb, cert-manager, metrics-server. Things a workload happens to need — a database, a cache, a scheduler — are the workload's, and which workload needs which is not rig's business, so they live with the overlay. `examples/data/addons/` has postgres, redis and airflow as a worked example; an overlay that wants them copies them in.

rig/docs/notes/check.md

@@ -34,14 +34,37 @@ A port held by THIS environment's own cluster is not a clash; it is the thing wo
 
 The ports are extracted 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.
 
-## Compact by default
-
-`make check` prints one line per question — host, toolchain, and for this rig: cluster, memory,
-ports, registry, addons — and adds detail only where something needs attention (`!` lines, the
-"held elsewhere" list when memory is tight, the clashing port). `make check all` prints every fact,
-as the full report did before 2026-09-17. `deps.sh detect all` is the same switch for the host part,
-so the standalone `rigdeps.sh detect` is short too. Changed because the long report buried the few
-lines that mattered.
+## Budget first, configuration after (2026-09-23)
+
+`make check` answers the question people run it for first, in the shape the adapter rig had
+(the user preferred it): a memory budget with one row per part, the node overhead, the total
+against what the machine has and has available; then a one-line verdict (`fits`, `! tight`,
+`! does not fit`, with the two opposite fixes told apart); then where things stand and the next
+command — not created, stopped (with the `docker start` line), up (with the Tilt and gateway
+URLs, and whether this environment's Tilt is already running).
+
+Below that, the configuration as it is, raw: the host and toolchain (`deps.sh detect`), then
+one `key value` line each for cluster, context, overlay, profile, nodes, kind config, manifests,
+ingress, ports (named), registry, addons. `!` lines always print; `make check all` adds every
+fact (per-port detail, addon list, swap and overcommit notes). `deps.sh detect all` is the same
+switch for the host part, so the standalone `rigdeps.sh detect` is short too.
+
+## MEMORY_BUDGET
+
+rig knows what a node costs (NODE_MB), not what a workload does, so the parts come from the
+overlay's rig.env: `MEMORY_BUDGET="name=MB ..."`, in the order listed; a 0 is left out, and an
+entry that is not `name=MB` is a `!` line. rig.env is sourced, so an overlay can size a part by
+its own knob (poc_rig's airflow follows its mode). When one part outweighs the rest together
+(and is at least 1 GB), check names it as the first thing to switch off; `MEMORY_BUDGET_TIP`
+says how, in the overlay's words. No budget: one `?` row says where to add it.
+
+## Tilt: ours or another
+
+A Tilt still running after `make cluster down` holds the Tilt port, and the next `make tilt`
+fails with "address already in use" (2026-09-23, the Workspace). check reads the listener with
+`ss -p` (our own processes only): a `tilt` whose working directory is this ctrl/ is this
+environment's Tilt, reported as running with its URL; another `tilt` is a `!` line with its pid,
+its folder and the `kill` that frees the port. Anything else is the ordinary port clash.
 
 ## overlay and kind config
 

rig/docs/notes/docs.md

@@ -8,6 +8,12 @@ out `python -m http.server` too — a minimal Debian has no python3. What it doe
 have, by definition, is Docker: the single prerequisite rig already demands. So a
 throwaway nginx container serves a read-only bind mount.
 
+It runs with a config of its own: one worker (nginx's `auto` starts one per core,
+twelve on an ordinary laptop, for a handful of static pages), no access log and a
+quiet entrypoint, so the terminal shows the URL and nothing else unless something
+fails. The pages declare an empty icon, so the browser does not ask for a
+`favicon.ico` that is not there.
+
 ## Committed SVGs
 
 Rendered SVGs are committed alongside their `.dot` sources for the same reason:

rig/docs/notes/overlay.md

@@ -60,6 +60,9 @@ air-gapped install); an overlay says what runs. `ctrl/.env` is still this
 machine's, and the caller still wins over everything.
 
 `rig.env` may not set `PROFILE` or `OVERLAY`: both are chosen before it loads.
+
+`MEMORY_BUDGET` (and optionally `MEMORY_BUDGET_TIP`) is how an overlay tells `make check` what its
+workload costs: rig only knows the node. See check.md.
 The paths it sets (`MANIFESTS_DIR`, `KIND_CONFIG`) are relative to the overlay.
 `MANIFESTS_DIR=none` means rig applies no manifests and the overlay's Tiltfile
 does, e.g. when kustomize needs flags.
@@ -100,7 +103,8 @@ load_config
 ```
 
 `OVERLAY_DIR` is set, so an addon can find files beside it
-(`$(_from_ctrl "$OVERLAY_DIR")/...`). rig's own `ctrl/addons/` holds only what
+(`$(_from_ctrl "$OVERLAY_DIR")/...`). Its manifest is a `<name>.yaml` beside the script,
+rendered with `render_manifest` (see [addons.md](addons.md)). rig's own `ctrl/addons/` holds only what
 makes a cluster work (metallb, cert-manager, metrics-server);
 `examples/data/addons/` shows workload ones.