From f179badbafa20bd235acccb5cc62b9e76061921f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabor=20K=C3=B6rber?= <gab@g4b.org>
Date: Sun, 24 May 2026 01:59:29 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=A5=87=20export=20from=20upstream=20(7b48?=
 =?UTF-8?q?e4e)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md         |  3 ++-
 config-layers.svg | 63 ++++++++++++++++++++++++++++-------------------
 2 files changed, 39 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 1948183..e00952e 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,7 @@ sandcage setup ssh --global          # configure SSH globally
 ## Configuration
 
 <p align="center">
-  <img src="config-layers.svg" alt="Configuration layering — defaults, global, project, CLI flags" width="720">
+  <img src="config-layers.svg" alt="Configuration layering — defaults, global, project, local, CLI flags" width="720">
 </p>
 
 Configuration is layered. Each level overrides the one below it, so you only set what you need:
@@ -93,6 +93,7 @@ Configuration is layered. Each level overrides the one below it, so you only set
 **Compiled defaults** — sensible out of the box
 **Global config** (`~/.sandcage/config.toml`) — user-wide preferences
 **Project config** (`.sandcage.yml`) — per-project setup, checked into version control
+**Local config** (`.sandcage.local.yml`) — personal overrides, gitignored (SSH keys, secrets, local mounts)
 **CLI flags** — per-invocation overrides
 
 ### .sandcage.yml example
diff --git a/config-layers.svg b/config-layers.svg
index 5e6b5a5..bca6c06 100644
--- a/config-layers.svg
+++ b/config-layers.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" width="800" height="360">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 420" width="800" height="420">
   <style>
     text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; }
     .title { font-size: 15px; font-weight: 600; fill: #24292f; }
@@ -21,6 +21,10 @@
       <stop offset="0%" stop-color="#D4A574"/>
       <stop offset="100%" stop-color="#c0895a"/>
     </linearGradient>
+    <linearGradient id="grad3b" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#b87d4a"/>
+      <stop offset="100%" stop-color="#a06838"/>
+    </linearGradient>
     <linearGradient id="grad4" x1="0" y1="0" x2="1" y2="0">
       <stop offset="0%" stop-color="#8a5c2a"/>
       <stop offset="100%" stop-color="#6b4720"/>
@@ -34,37 +38,44 @@
   <text class="title" x="400" y="30" text-anchor="middle">Configuration Layering</text>
 
   <!-- Priority arrow on the left -->
-  <line x1="70" y1="60" x2="70" y2="310" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
-  <text class="arrow-text" x="66" y="190" text-anchor="middle" transform="rotate(-90, 66, 190)">Higher priority overrides</text>
+  <line x1="70" y1="60" x2="70" y2="370" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr)"/>
+  <text class="arrow-text" x="66" y="220" text-anchor="middle" transform="rotate(-90, 66, 220)">Higher priority overrides</text>
 
   <!-- Layer 1 - Compiled Defaults (bottom, lightest) -->
-  <rect x="120" y="250" width="540" height="56" rx="6" fill="url(#grad1)"/>
-  <text class="layer-label" x="390" y="275" text-anchor="middle" fill="#24292f">Compiled Defaults</text>
-  <text class="layer-desc" x="390" y="293" text-anchor="middle" fill="#57606a">Built into the sandcage binary</text>
-  <text class="side-label" x="680" y="275">Base values</text>
-  <text class="side-detail" x="680" y="291">always present</text>
+  <rect x="120" y="310" width="540" height="56" rx="6" fill="url(#grad1)"/>
+  <text class="layer-label" x="390" y="335" text-anchor="middle" fill="#24292f">Compiled Defaults</text>
+  <text class="layer-desc" x="390" y="353" text-anchor="middle" fill="#57606a">Built into the sandcage binary</text>
+  <text class="side-label" x="680" y="335">Base values</text>
+  <text class="side-detail" x="680" y="351">always present</text>
 
   <!-- Layer 2 - Global Config -->
-  <rect x="140" y="185" width="540" height="56" rx="6" fill="url(#grad2)"/>
-  <text class="layer-label" x="410" y="210" text-anchor="middle">Global Config</text>
-  <text class="layer-desc" x="410" y="228" text-anchor="middle">~/.sandcage/config.toml</text>
-  <text class="side-label" x="700" y="210">User-wide</text>
-  <text class="side-detail" x="700" y="226">SSH, shell, mounts</text>
+  <rect x="140" y="245" width="540" height="56" rx="6" fill="url(#grad2)"/>
+  <text class="layer-label" x="410" y="270" text-anchor="middle">Global Config</text>
+  <text class="layer-desc" x="410" y="288" text-anchor="middle">~/.sandcage/config.toml</text>
+  <text class="side-label" x="700" y="270">User-wide</text>
+  <text class="side-detail" x="700" y="286">SSH, shell, mounts</text>
 
   <!-- Layer 3 - Project Config -->
-  <rect x="160" y="120" width="540" height="56" rx="6" fill="url(#grad3)"/>
-  <text class="layer-label" x="430" y="145" text-anchor="middle">Project Config</text>
-  <text class="layer-desc" x="430" y="163" text-anchor="middle">.sandcage.yml</text>
-  <text class="side-label" x="720" y="145">Per-project</text>
-  <text class="side-detail" x="720" y="161">packages, toolchains, env</text>
+  <rect x="160" y="180" width="540" height="56" rx="6" fill="url(#grad3)"/>
+  <text class="layer-label" x="430" y="205" text-anchor="middle">Project Config</text>
+  <text class="layer-desc" x="430" y="223" text-anchor="middle">.sandcage.yml — checked into version control</text>
+  <text class="side-label" x="720" y="205">Per-project</text>
+  <text class="side-detail" x="720" y="221">packages, toolchains, env</text>
 
-  <!-- Layer 4 - CLI Flags (top, darkest) -->
-  <rect x="180" y="55" width="540" height="56" rx="6" fill="url(#grad4)"/>
-  <text class="layer-label" x="450" y="80" text-anchor="middle">CLI Flags</text>
-  <text class="layer-desc" x="450" y="98" text-anchor="middle">sandcage claude -p ~/project -- --resume</text>
-  <text class="side-label" x="740" y="80">Per-invocation</text>
-  <text class="side-detail" x="740" y="96">highest priority</text>
+  <!-- Layer 4 - Local Config (new) -->
+  <rect x="170" y="115" width="540" height="56" rx="6" fill="url(#grad3b)"/>
+  <text class="layer-label" x="440" y="140" text-anchor="middle">Local Config</text>
+  <text class="layer-desc" x="440" y="158" text-anchor="middle">.sandcage.local.yml — gitignored, personal overrides</text>
+  <text class="side-label" x="730" y="140">Per-developer</text>
+  <text class="side-detail" x="730" y="156">SSH keys, secrets, mounts</text>
+
+  <!-- Layer 5 - CLI Flags (top, darkest) -->
+  <rect x="180" y="55" width="540" height="50" rx="6" fill="url(#grad4)"/>
+  <text class="layer-label" x="450" y="77" text-anchor="middle">CLI Flags</text>
+  <text class="layer-desc" x="450" y="94" text-anchor="middle">sandcage claude -p ~/project -- --resume</text>
+  <text class="side-label" x="740" y="77">Per-invocation</text>
+  <text class="side-detail" x="740" y="93">highest priority</text>
 
   <!-- Bottom note -->
-  <text x="400" y="340" text-anchor="middle" font-size="11" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif">Each layer overrides the one below it. Only set what you need — sensible defaults handle the rest.</text>
-</svg>
\ No newline at end of file
+  <text x="400" y="400" text-anchor="middle" font-size="11" fill="#8b949e" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif">Each layer overrides the one below it. Only set what you need — sensible defaults handle the rest.</text>
+</svg>