rig major updates

rig/examples/starter/README.md

@@ -0,0 +1,59 @@
+# `examples/starter` — the overlay rig runs when you name none
+
+An overlay is one folder, outside rig, that holds what runs: its settings, its
+manifests, its images. rig reads it and never writes into it — see
+[`docs/notes/overlay.md`](../../docs/notes/overlay.md) for the contract. This one
+ships with rig so `make tilt` has something to deploy on a fresh clone, and so a
+real overlay has a shape to be written against:
+
+```
+rig.env              settings layered over rig's defaults (this one sets none)
+k8s/base/            the components, as plain manifests
+k8s/overlays/dev/    how this environment differs from the base — MANIFESTS_DIR's default
+Tiltfile             the workload's half of the dev loop; rig's ctrl/Tiltfile includes it
+Dockerfile.example   the shape of an image you build yourself
+```
+
+To start your own, copy this folder somewhere rig does not track —
+`rig/local/<name>/`, or a repo of its own — and name it:
+
+```bash
+cp -r examples/starter local/myenv
+OVERLAY=local/myenv make cluster up      # or OVERLAY=local/myenv in ctrl/.env
+```
+
+The cluster, context and port block then follow the overlay's folder name
+(`myenv`, `kind-myenv`), so it never collides with another.
+
+## The two components are examples, not the system
+
+They exist so the real manifests have a shape to be written against.
+
+### 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.
+
+## Images
+
+`Dockerfile.example` is a commented shape, not a working build. Paths in this
+folder's Tiltfile are relative to this folder, so `context='.'` is the overlay
+and every `COPY` in the Dockerfile is relative to it:
+
+```
+docker_build(CLUSTER + '-api', context='.', dockerfile='Dockerfile.api')
+```
+
+The name given to `docker_build` must match `image:` in the manifest — that
+string is the only thing connecting the two.