rig major updates

rig/docs/index.html

@@ -240,6 +240,7 @@
     <a href="#steps">The steps</a>
     <a href="#install">Installation</a>
     <a href="#environments">Environments</a>
+    <a href="#overlays">Overlays</a>
     <a href="#profiles">Profiles</a>
     <a href="#registry">Registry</a>
     <a href="#architecture">Architecture</a>
@@ -303,7 +304,8 @@ make cluster up  <span class="c"># cluster + registry + addons; ports derive by
       finishes the job rather than reporting "already exists" and leaving every
       node permanently NotReady.</p>
 <pre><code>make cluster up                 <span class="c"># built-in defaults — no profile needed</span>
-make cluster up PROFILE=client  <span class="c"># after copying env.d/client.env.example: cached registry</span>
+make cluster up PROFILE=mirror  <span class="c"># after copying env.d/mirror.env.example: cached registry</span>
+make cluster up OVERLAY=examples/data  <span class="c"># an overlay: what runs, kept outside rig</span>
 make cluster reset              <span class="c"># destroy and rebuild — how an edited kind config takes effect</span>
 </code></pre>
 
@@ -321,12 +323,12 @@ make cluster reset              <span class="c"># destroy and rebuild — how an
       </dl>
 
       <h3>Running more than one</h3>
-      <p>Copy the directory, rename it, and run <code>make cluster up</code>. Cluster name,
-      context, image tags and the port block all follow the directory name, so
-      the second environment collides with nothing and neither one's teardown can
-      reach the other.</p>
-<pre><code>cp -r rig ../platform-v2 &amp;&amp; cd ../platform-v2
-make cluster up
+      <p>Name another overlay, or copy the directory and rename it. Cluster name,
+      context, image tags and the port block all follow the folder name — the
+      overlay's, or rig's — so the second environment collides with nothing and
+      neither one's teardown can reach the other.</p>
+<pre><code>OVERLAY=local/platform-v2 make cluster up
+cp -r rig ../platform-v3 &amp;&amp; cd ../platform-v3 &amp;&amp; make cluster up
 </code></pre>
     </div>
   </section>
@@ -382,16 +384,16 @@ docker load &lt; rig.tgz &amp;&amp; make cluster up PROFILE=offline   <span clas
 
   <section class="section" id="environments">
     <h2>Environments</h2>
-    <p class="lede">One directory is one environment. Copy it, rename it, run it.</p>
+    <p class="lede">One folder is one environment — an overlay's, or rig's own. Copy it, rename it, run it.</p>
     <div class="graph-container">
       <a href="viewer.html?src=graphs/02-environment.svg"><img src="graphs/02-environment.svg" alt="Environment derivation"></a>
     </div>
     <div class="prose">
       <p>Running several versions of a system at once means several clusters on one
       machine, not several machines. Everything that could collide is derived from
-      the directory name:</p>
+      the folder name (the overlay's when one is named):</p>
       <dl>
-        <dt>cluster + context</dt><dd><code>acmebank/</code> builds <code>acmebank</code> on <code>kind-acmebank</code>.</dd>
+        <dt>cluster + context</dt><dd><code>platform-v2/</code> builds <code>platform-v2</code> on <code>kind-platform-v2</code>.</dd>
         <dt>port block</dt><dd>Ten ports from a hash of the name, in the 20000+ range — clear of 80, 443, 3000, 5432, 8000 and 8080.</dd>
         <dt>registry + images</dt><dd>Named after the environment, so two copies never share one.</dd>
       </dl>
@@ -402,25 +404,50 @@ docker load &lt; rig.tgz &amp;&amp; make cluster up PROFILE=offline   <span clas
 
       <h3>Configuration layers</h3>
       <p>Weakest first, later wins: built-in defaults → pinned versions → a
-      profile, if you name one → <code>ctrl/.env</code> → the environment. So
+      profile, if you name one → the overlay's <code>rig.env</code> →
+      <code>ctrl/.env</code> → the environment. So
       <code>make cluster up PROFILE=&lt;name&gt;</code> always beats every file.</p>
     </div>
   </section>
 
+  <section class="section" id="overlays">
+    <h2>Overlays</h2>
+    <p class="lede">What runs lives outside rig — rig reads it and never writes into it.</p>
+    <div class="prose">
+      <p>An overlay is one folder, kept outside rig's version control, holding a
+      use case. Every piece is optional:</p>
+      <table>
+        <tr><th>in the overlay</th><th>what rig does with it</th></tr>
+        <tr><td><code>rig.env</code></td><td>a config layer: addons, namespaces, images — anything a profile could set</td></tr>
+        <tr><td><code>k8s/overlays/dev/</code></td><td>the manifests the dev loop applies</td></tr>
+        <tr><td><code>kind-config.yaml.tpl</code></td><td>the cluster's shape, when it needs its own (mounts, ports)</td></tr>
+        <tr><td><code>addons/&lt;name&gt;.sh</code></td><td>addons, found before rig's own</td></tr>
+        <tr><td><code>Tiltfile</code></td><td>the workload's half of the dev loop, included by rig's</td></tr>
+      </table>
+<pre><code>cp -r examples/starter local/myenv   <span class="c"># local/ is gitignored</span>
+OVERLAY=local/myenv make cluster up
+</code></pre>
+      <p>With none named, rig runs its own <code>examples/starter</code>.
+      <code>examples/data</code> carries postgres, redis and airflow as an
+      overlay's own addons. A project can also carry rig at
+      <code>&lt;project&gt;/rig/</code> and be the overlay itself, with a
+      three-line forwarding Makefile — see <code>docs/notes/overlay.md</code>.</p>
+    </div>
+  </section>
+
   <section class="section" id="profiles">
     <h2>Profiles</h2>
-    <p class="lede">Optional overlays — rig needs none.</p>
+    <p class="lede">How this machine reaches the world — optional; rig needs none.</p>
     <div class="prose">
       <table>
         <tr><th>example</th><th>registry</th><th>for</th></tr>
         <tr><td><i>none</i></td><td>local</td><td>the built-in defaults; no profile needed</td></tr>
-        <tr><td><code>client.env.example</code></td><td>mirror</td><td>images through a corporate registry</td></tr>
+        <tr><td><code>mirror.env.example</code></td><td>mirror</td><td>images through an internal registry</td></tr>
         <tr><td><code>offline.env.example</code></td><td>local</td><td>air-gapped</td></tr>
-        <tr><td><code>data.env.example</code></td><td>local</td><td>postgres, redis, airflow</td></tr>
       </table>
 
       <div class="note"><p><b>The kind config cannot be re-applied.</b> Edit
-      <code>ctrl/k8s/kind-config.yaml.tpl</code>; it takes effect when the cluster is created. <code>cluster up</code> prints what it
+      <code>ctrl/k8s/kind-config.yaml.tpl</code> (or the overlay's own); it takes effect when the cluster is created. <code>cluster up</code> prints what it
       locks in before spending the time, and <code>make cluster reset</code> is
       the way out.</p></div>