updated make docs

rig/docs/notes/docs.md

@@ -18,3 +18,12 @@ fails. The pages declare an empty icon, so the browser does not ask for a
 
 Rendered SVGs are committed alongside their `.dot` sources for the same reason:
 the pages have to read on a machine with no Graphviz installed.
+
+## Whose docs
+
+`make docs` serves the docs of the folder it runs from. In rig that is rig's own `docs/`. A
+project's launcher sets `DOCS_DIR` to its own `docs/` (an absolute path), so `make docs` there
+serves the project's pages through this same script, on the same terms: an `index.html` at
+the top, the environment's block for the port (`HTTP_PORT + 4`), a container named after the
+environment. rig's own docs stay one `make -C <rig> docs` away. The project keeps no copy of
+this script.

rig/docs/notes/overlay.md

@@ -74,6 +74,36 @@ follow the overlay folder's name, sanitised the same way a rig folder's name is.
 One rig can therefore serve several overlays, each in its own cluster, and a
 project that carries rig at `./rig` does not name every cluster `rig`.
 
+That is the default. The convention is to pin the name in the overlay's `rig.env`:
+
+```
+CLUSTER=<name>
+```
+
+The name only has to be unique on the machine: the port block derives from it, so two
+overlays with the same name share one cluster and one set of ports. Pinned, it no longer
+follows the folder, so moving or renaming folders changes nothing. A second copy of the
+same project (another worktree, say) runs beside it by setting its own `CLUSTER=` in the
+project's ignored `.env.local`: the caller beats `rig.env`. Ports the workload forwards
+itself (a Tiltfile's `port_forwards`) are the overlay's, not the block's, and can still
+collide.
+
+A repository that runs on rig keeps it in a `devenv/` folder, with rig as the project's
+sibling:
+
+```
+devenv/
+  rig/              rig
+  <project>/        the forwarder (RIG_DIR ?= $(HERE)/../rig), its knobs, its data
+    overlay/        what rig reads
+```
+
+The overlay folder is then called `overlay/` in every project, so its name says nothing
+and `CLUSTER=` in its `rig.env` is required, not optional: left to the default, every such
+project would be the cluster `overlay`, on the same ports. The project folder, the cluster
+and the workload's namespace are three names: a folder may hold `_`, the other two are DNS
+labels.
+
 `ports.sh persist` refuses while an overlay is set: it writes to rig's
 `ctrl/.env`, and a pin there would follow every overlay.
 
@@ -164,6 +194,9 @@ RIG_DIR ?= $(HERE)/rig
 override RIG_DIR := $(abspath $(patsubst ~/%,$(HOME)/%,$(RIG_DIR)))
 ```
 
+`make docs` should serve the project's pages, not rig's: the forwarder names them with
+`DOCS_DIR := $(HERE)/docs` (see docs.md). rig's own stay `make -C <rig> docs`.
+
 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.