proper docs and .version

rig/docs/notes/Dockerfile.deps.md

@@ -15,7 +15,7 @@ docker build -f ctrl/Dockerfile.deps --target deps      -t <slug>-deps      .
 docker build -f ctrl/Dockerfile.deps --target deps-full -t <slug>-deps:full .
 ```
 
-`deps-full` bakes every pinned binary in at build time, and the manifests rig's own addons apply (metallb, cert-manager, metrics-server). `docker save` it and you have the whole installer as one file to carry into an air-gapped network. There, put the manifests where the addons look for them:
+`make deps image full` builds the second. `deps-full` bakes every pinned binary in at build time, and the manifests rig's own addons apply (metallb, cert-manager, metrics-server). `docker save` it and you have the whole installer as one file to carry into an air-gapped network. There, put the manifests where the addons look for them:
 
 ```
 docker run --rm -v "$PWD/vendor:/out/vendor" rig-deps:full manifests --to /out/vendor/manifests

rig/docs/notes/Makefile.md

@@ -31,7 +31,7 @@ Read positionally, so the order is a contract; ctrl/selftest.sh pins it. The two
 
 `OVERLAY` and `CLUSTER` given as make arguments (`make tilt OVERLAY=local/x`) are handed to that `$(shell ...)` explicitly. Before make 4.4, `$(shell)` runs with make's own environment and does not see command-line variables, while the recipes do: tilt would then be told one context and the Tiltfile would guard on another. An overlay's forwarder avoids the question by putting `OVERLAY` in the environment.
 
-This used to be sed over ctrl/.env plus a slug computed in the Makefile, which is a SECOND derivation of values lib/config.sh already owns, and the two could disagree about the port after `ports.sh persist`, or about the name for any directory whose sanitised form differs from its raw one. One source now; the Tiltfile reads the same line.
+One source: lib/config.sh owns these values, and the Tiltfile reads the same line. A second derivation in the Makefile could disagree about the port after `ports.sh persist`, or about the name of any directory whose sanitised form differs from its raw one.
 
 ## CLUSTER / KCTX fallback
 
@@ -39,7 +39,7 @@ The fallback matters: ports.sh sources config.sh, and if a profile or .env is br
 
 ## ARGS as .PHONY
 
-Words after the target become the script's subcommand; each gets a no-op rule so make does not treat them as goals. They are also marked 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 is not enough on its own; only .PHONY stops make consulting the filesystem.
+Words after the target become the script's subcommand; each gets a no-op rule so make does not treat them as goals. They are also marked PHONY, because some of those words name real directories (`ctrl`, `docs`, `examples`), and make considers a target that is an existing directory already built: without it, `make docs ctrl` would print "make: 'ctrl' is up to date". The empty rule is not enough on its own; only .PHONY stops make consulting the filesystem.
 
 ## tilt: --port guard
 

rig/docs/notes/check.md

@@ -54,7 +54,7 @@ switch for the host part, so the standalone `rigdeps.sh detect` is short too.
 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
+its own knob (an airflow sized by the mode the overlay runs it in). 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.
 

rig/docs/notes/env.md

@@ -2,7 +2,7 @@
 
 ## ctrl/.env.example: header
 
-Machine-local config. Copy to ctrl/.env (gitignored) and edit. The cluster SHAPE is an optional profile in ctrl/env.d/ — see the *.env.example there. The architecture MODEL lives in arch/<name>.json — not in .env either.
+Machine-local config. Copy to ctrl/.env (gitignored) and edit. The cluster SHAPE is an optional profile in ctrl/env.d/ — see the *.env.example there.
 
 ## ctrl/.env.example: CLUSTER
 

rig/docs/notes/overlay.md

@@ -168,13 +168,16 @@ No search path: an unset `RIG_DIR` means `./rig`, and nothing else is tried. Mov
 changes nothing in the cluster's name, context or ports; moving or renaming the overlay
 folder does.
 
-`VERSION`, at rig's top, names the rig. It travels with the folder, vendored, a
-worktree or a plain copy, and needs no git. A project records the one it was last run
-against and warns on another; it does not refuse:
+`.version`, at rig's top, names the rig. It travels with the folder, vendored, a
+worktree, a plain copy or a `git archive` release, and needs no git. Patch and minor
+steps are edits to that file, with no tag; a `rig-<version>` tag marks a milestone only.
+A project records the version it was last run against and warns on another; it does not
+refuse. Releases before 0.1.1 carry `VERSION` instead, so the project reads that as a
+fallback:
 
 ```make
-RIG_REF := 0.1.0
-RIG_AT  := $(strip $(shell cat '$(RIG_DIR)/VERSION' 2>/dev/null))
+RIG_REF := 0.1.1
+RIG_AT  := $(strip $(shell cat '$(RIG_DIR)/.version' 2>/dev/null || cat '$(RIG_DIR)/VERSION' 2>/dev/null))
 ifneq ($(RIG_AT),$(RIG_REF))
 $(warning rig at $(RIG_DIR) is $(or $(RIG_AT),unversioned); this overlay was last run against rig $(RIG_REF))
 endif
@@ -183,18 +186,3 @@ endif
 `rig.env` holds no secrets, by this contract. A repository whose `.gitignore` has a
 broad `*.env` (a common secrets rule) would still hide it, so an overlay living in
 such a repo re-includes it in its own `.gitignore`: `!rig.env`.
-
-## Moving a copied rig to an overlay
-
-A rig copied into a project and edited there splits cleanly:
-
-| was, in the copy | goes to |
-| --- | --- |
-| `ctrl/k8s/base`, `ctrl/k8s/overlays` | `k8s/` |
-| the workload parts of `ctrl/Tiltfile` | `Tiltfile` (paths now relative to the overlay) |
-| `ctrl/env.d/<name>.env` | `rig.env` |
-| edits to `ctrl/k8s/kind-config.yaml.tpl` | `kind-config.yaml.tpl` (`${HOST_WORKDIR}` → `${OVERLAY_DIR}`) |
-| workload addons | `addons/` |
-| Dockerfiles for the workload | beside the Tiltfile |
-| `ctrl/.env` | `rig/ctrl/.env` (this machine's; drop a `MANIFESTS_DIR=ctrl/k8s/overlays/dev` line) |
-| everything else of rig's | replaced by rig as it is |

rig/docs/notes/selftest.md

@@ -28,7 +28,7 @@ So the loop is generated FROM the list: add a key to `CONFIG_OVERRIDABLE` and th
 
 ## one derivation, not three
 
-The Makefile used to compute the cluster name itself and sed `TILT_PORT` out of `ctrl/.env`: a second derivation of values `lib/config.sh` already owns, which could disagree with it after `ports.sh persist`. It now reads `ports.sh active`. Nothing structurally prevents the sed coming back, so the agreement is asserted against the real `make -n` output rather than against the source.
+The Makefile reads `ports.sh active` rather than deriving the cluster name and `TILT_PORT` itself: a second derivation of values `lib/config.sh` already owns could disagree with it after `ports.sh persist`. Nothing structurally prevents one coming back, so the agreement is asserted against the real `make -n` output rather than against the source.
 
 `--no-print-directory` and a grep, not `tail -1`: run from `make selftest` this is a RECURSIVE make, and the "Entering/Leaving directory" lines go to STDOUT. `tail -1` then reads "make[1]: Leaving directory ..." and both checks fail, but only when invoked through make, never when the script is run directly. A test that passes one way and fails the other is worse than no test.