overlay

rig/VERSION

@@ -0,0 +1 @@
+0.1.0

rig/docs/notes/overlay.md

@@ -155,6 +155,31 @@ $(wordlist 2,$(words $(GOALS)),$(GOALS)):
 The cluster is then named after `<project>`, exactly as a copied rig named
 `<project>` was, so moving a copied rig to this layout keeps its cluster and ports.
 
+rig can also live outside the project, which then holds only the overlay. The
+forwarder names it with one variable, a machine path that is never committed (the
+shell, or an ignored `.env.local`), defaulting to the vendored layout:
+
+```make
+RIG_DIR ?= $(HERE)/rig
+override RIG_DIR := $(abspath $(patsubst ~/%,$(HOME)/%,$(RIG_DIR)))
+```
+
+No search path: an unset `RIG_DIR` means `./rig`, and nothing else is tried. Moving rig
+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:
+
+```make
+RIG_REF := 0.1.0
+RIG_AT  := $(strip $(shell 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
+```
+
 `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`.