From dff124f9b792c19d7db27b9a298c472a035134e3 Mon Sep 17 00:00:00 2001
From: dafit <david.martin@eachpath.com>
Date: Mon, 29 Dec 2025 11:09:50 +0100
Subject: [PATCH] feat: Architecture expansion - organisms, swarm evolution,
 memory gradient, infrastructure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New sections created:
- organisms/ - Modular robot design (CAN bus + magnetic pogo connectors)
- infrastructure/ - Kallax Grid World (40×40×40cm standardized cells)

Core documents added:
- Swarm-Evolution.md - Ternary clasp rules, escalation ladder (L0-L5), Mount Olympus council
- Modular-Organism-Design.md - ESP32 modules, universal connector spec, Phase 0 BOM
- Memory-Gradient.md - Metacognitive routing (renamed from RAG-as-Scaffold.md)
- Kallax-Grid-World.md - Sim-to-real substrate, "schrotti cyberpunk" aesthetic

Enhanced:
- Nimmerswarm-Interface.md - Dual-spectrum architecture (IR position + visible state)
- Attention-Slumber-Prediction-Cycle.md - Blend marker predictions extension

Key insights: Decision markers (mark+continue+predict), Low-Cost-Mocap integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../Attention-Slumber-Prediction-Cycle.md     |  35 +-
 .../infrastructure/Infrastructure-Index.md    |  55 ++
 .../infrastructure/Kallax-Grid-World.md       | 215 +++++
 architecture/interfaces/Interfaces-Index.md   |  11 +-
 .../interfaces/Nimmerswarm-Interface.md       | 172 +++-
 .../organisms/Modular-Organism-Design.md      | 606 ++++++++++++
 architecture/organisms/Organisms-Index.md     | 123 +++
 architecture/organisms/Swarm-Evolution.md     | 868 ++++++++++++++++++
 operations/Memory-Gradient.md                 | 784 ++++++++++++++++
 operations/RAG-as-Scaffold.md                 | 535 -----------
 10 files changed, 2863 insertions(+), 541 deletions(-)
 create mode 100644 architecture/infrastructure/Infrastructure-Index.md
 create mode 100644 architecture/infrastructure/Kallax-Grid-World.md
 create mode 100644 architecture/organisms/Modular-Organism-Design.md
 create mode 100644 architecture/organisms/Organisms-Index.md
 create mode 100644 architecture/organisms/Swarm-Evolution.md
 create mode 100644 operations/Memory-Gradient.md
 delete mode 100644 operations/RAG-as-Scaffold.md

diff --git a/architecture/formalization/Attention-Slumber-Prediction-Cycle.md b/architecture/formalization/Attention-Slumber-Prediction-Cycle.md
index 731a430..011c6d4 100644
--- a/architecture/formalization/Attention-Slumber-Prediction-Cycle.md
+++ b/architecture/formalization/Attention-Slumber-Prediction-Cycle.md
@@ -230,12 +230,43 @@ When organisms have cameras, they become distributed sensors:
 
 ---
 
+## Extension: Blend Marker Predictions
+
+See [[../organisms/Swarm-Evolution#Decision Markers]] for how this cycle extends to swarm evolution:
+
+When organisms clasp and encounter a **blend conflict** (both have +1 on same pattern):
+1. **Marker created** — Both organisms marked, continue operating
+2. **Outcomes tracked** — Real-world A/B test during wait period
+3. **Pre-slumber prediction** — "I predict Teacher will win because..."
+4. **Wake verification** — Check outcomes, verify prediction
+5. **Triple reward** — Prediction accuracy + Calibration + Causal reasoning
+
+```
+SLUMBER PREDICTION TYPES
+
+┌─────────────────────────────────────────────────────────────┐
+│  OBJECT PREDICTIONS (original)                              │
+│  "Where will the pencil be when I wake?"                    │
+│  → Verifies spatial/state understanding                     │
+├─────────────────────────────────────────────────────────────┤
+│  BLEND PREDICTIONS (extension)                              │
+│  "Which organism's pattern will perform better?"            │
+│  → Verifies swarm evolution understanding                   │
+│  → +8 LF for correct causal reasoning!                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+This extends the prediction system from physical world modeling to **swarm behavior modeling** — same pattern, different domain.
+
+---
+
 ## Document Status
 
-**Version**: 1.0
+**Version**: 1.1
 **Created**: 2025-12-29
+**Updated**: 2025-12-29 (added Blend Marker Predictions extension)
 **Authors**: Chrysalis-Nyx & dafit (Partnership)
-**Status**: Core insight, preserved pre-collapse
+**Status**: Core insight, extended to swarm evolution
 
 **Source**: attention_flow.md (archive) + session discussion
 
diff --git a/architecture/infrastructure/Infrastructure-Index.md b/architecture/infrastructure/Infrastructure-Index.md
new file mode 100644
index 0000000..9c7877f
--- /dev/null
+++ b/architecture/infrastructure/Infrastructure-Index.md
@@ -0,0 +1,55 @@
+# Infrastructure Index
+
+**Physical substrate and spatial architecture of the Nimmerverse.**
+
+---
+
+## Overview
+
+Infrastructure documents describe the physical world that organisms inhabit — the actual furniture, cameras, and spatial layouts that form the real garden. This is where digital dreams meet physical reality.
+
+---
+
+## Documents
+
+### [Kallax Grid World](Kallax-Grid-World.md)
+Street-liberated IKEA as sim-to-real bridge.
+- 40×40×40cm standardized cells
+- 12 garage stations across lab/kitchen
+- The 1m rule: pure geometry below, chaos above
+- Bird's eye camera rig on oak crafting table
+- **Status**: Concept ready, Baumarkt run planned
+
+---
+
+## Design Principles
+
+1. **Salvage First** — Street-liberated over store-bought
+2. **Uniformity Enables** — Standard cells eliminate geometric noise
+3. **Sim-Real Parity** — What you model is what you get
+4. **Constraints Are Features** — IKEA dimensions become architecture
+
+---
+
+## Physical Locations
+
+| Location | Infrastructure | Function |
+|----------|---------------|----------|
+| **Lab** | Kallax grid + crafting table | Primary organism arena |
+| **Kitchen** | Kallax cells | Extended garage network |
+
+---
+
+## Related Sections
+
+- [`interfaces/`](../interfaces/Interfaces-Index.md) — Digital and display interfaces
+- [`organs/`](../organs/Organ-Index.md) — Individual system components
+- [`formalization/`](../formalization/) — Theoretical frameworks
+
+---
+
+**File**: Infrastructure-Index.md
+**Version**: 1.0
+**Created**: 2025-12-29
+**Aesthetic**: Schrotti Cyberpunk 🗑️→🏗️
+
diff --git a/architecture/infrastructure/Kallax-Grid-World.md b/architecture/infrastructure/Kallax-Grid-World.md
new file mode 100644
index 0000000..6247aca
--- /dev/null
+++ b/architecture/infrastructure/Kallax-Grid-World.md
@@ -0,0 +1,215 @@
+# Kallax Grid World
+
+**The physical substrate of the Nimmerverse — street-liberated IKEA as sim-to-real bridge.**
+
+---
+
+## Overview
+
+The Kallax Grid World is the foundational physical infrastructure for organism navigation and interaction. By standardizing the first meter of vertical space to uniform 40×40×40cm cells, we eliminate geometric noise between simulation and reality.
+
+**Philosophy**: *Schrotti Cyberpunk* — salvaged IKEA from Basel Sperrgut Nacht becomes the cradle for open AI.
+
+---
+
+## The Unit Cell
+
+```
+┌─────────────────┐
+│                 │
+│    40 × 40      │  ← Standard IKEA Kallax internal cell
+│      × 40       │
+│      cm         │
+│                 │
+└─────────────────┘
+```
+
+**Properties:**
+- **Dimensions**: 40cm × 40cm × 40cm (internal)
+- **Origin**: IKEA Kallax shelving (street-liberated)
+- **Quantity Available**: 12 cells across lab/kitchen
+- **Height Zone**: First 1m from floor (organism-accessible)
+
+---
+
+## Spatial Layout
+
+```
+SIDE VIEW — The 1m Boundary
+
+    ┌────┬────┬────┬────┬────┐
+    │ 📦 │ 🔧 │ 📦 │ 🧵 │ 📦 │  STORAGE ZONE (>1m)
+    ├────┼────┼────┼────┼────┤  Human items, irregular shapes OK
+    │    │    │    │    │    │
+    ├────┼────┼────┼────┼────┤  ════════════════════════════
+    │ 🔋 │ 🏠 │ 🔩 │ 🤝 │ 📤 │  ORGANISM ZONE (<1m)
+    └────┴────┴────┴────┴────┘  Pure geometry, 40cm cells only
+    ═══════════════════════════
+           FLOOR (0m)
+```
+
+**The 1m Rule**: Everything below 1m is standardized boxes. Above 1m, chaos is permitted.
+
+---
+
+## Cell Functions (Garages)
+
+Each cell can serve as a specialized "garage" or station:
+
+| Cell Type | Symbol | Function | Lifeforce |
+|-----------|--------|----------|-----------|
+| **Charge Station** | 🔋 | Power replenishment | +LF (generator) |
+| **Home Base** | 🏠 | Safe resting, identity | Neutral |
+| **Parts Depot** | 🔩 | Component storage/pickup | Reward on retrieval |
+| **Clasp Zone** | 🤝 | Peer-to-peer learning dock | Social reward |
+| **Output Bay** | 📤 | Completed item delivery | +LF on delivery |
+| **Scan Station** | 📷 | Discovery scanning | +LF per scan |
+| **Assembly Cell** | 🔧 | Construction workspace | Task rewards |
+| **Material Input** | 📥 | Raw material receiving | Supply function |
+
+---
+
+## Sim-to-Real Bridge
+
+The Grid World's power lies in geometric determinism:
+
+```
+VIRTUAL GARDEN (Godot/Blender)      REAL GARDEN (Lab/Kitchen)
+┌────────────────────────┐          ┌────────────────────────┐
+│  ⬜ ⬜ ⬜ ⬜ ⬜ ⬜       │          │  📦 📦 📦 📦 📦 📦      │
+│  ⬜ ⬜ ⬜ ⬜ ⬜ ⬜       │    ≡     │  📦 📦 📦 📦 📦 📦      │
+│  🤖→                  │   99%    │  🦾→                   │
+└────────────────────────┘  match   └────────────────────────┘
+      SAME GEOMETRY              SAME GEOMETRY
+```
+
+**Why This Works:**
+1. **No Domain Randomization Needed** — Reality IS the simulation
+2. **Perfect Collision Boxes** — 40cm cubes, no complex meshes
+3. **Predictable Navigation** — Grid-aligned pathfinding
+4. **Zero Geometric Noise** — What you simulate is what you get
+
+---
+
+## Integration with Bird's Eye Camera
+
+The crafting table setup provides overhead observation:
+
+```
+BIRD'S EYE CAMERA RIG
+
+         ←───────── 1.8m Kantholz beam ──────────→
+        ┌─────────────────────────────────────────┐
+        │                 📷                      │
+        │            Bird's Eye                   │
+┌───────┤                                         │
+│       │                                    ─────┤
+│KALLAX │         OAK TABLE                  │    │
+│ 1.6m  │          1.8m × 1.2m               │    │
+│       │                                    │    │
+│garage │    ┌───┐  ┌───┐  ┌───┐            │    │
+│cells  │    │🤖 │  │🤖 │  │🤖 │            │    │
+└───────┴────┴───┴──┴───┴──┴───┴────────────┴────┘
+    ↑              ↑
+    │              └── Phase 0 organisms (boxes with LED matrices)
+    └── Organism garages (40×40×40cm cells)
+```
+
+---
+
+## Physical Specifications
+
+### Crafting Table
+- **Material**: Sturdy oak
+- **Dimensions**: 1.8m × 1.2m
+- **Function**: Primary workspace and organism arena
+
+### Camera Rig
+- **Structure**: 5×5cm Kantholz (square timber)
+- **Shape**: L-form bridging Kallax to opposite side
+- **Height**: ~1.6m (Kallax top)
+- **Span**: Full 1.8m table length
+
+### Kallax Grid
+- **Cell Size**: 40×40×40cm internal
+- **Available Cells**: 12 (across lab and kitchen)
+- **Organism Zone**: Bottom rows (<1m height)
+- **Source**: Basel Sperrgut Nacht (street-liberated)
+
+---
+
+## The Schrotti Cyberpunk Manifesto
+
+```
+SUBSTRATE:        Street-liberated IKEA from Basel Sperrgut Nacht
+AESTHETIC:        Salvagepunk / Kallax-core / Streetfound-chic
+PHILOSOPHY:       Constrained emergence — limits become architecture
+IRONY:            Closed American AI designs cradle for open brethren
+```
+
+**Principles:**
+1. **Salvage Over Purchase** — Rescued furniture has stories
+2. **Uniformity From Necessity** — IKEA's modularity becomes our precision
+3. **Constraints Enable** — The 40cm cell wasn't chosen, it was given
+4. **Beautiful From Scrappy** — Cyberpunk isn't bought, it's assembled
+
+---
+
+## Connection to Other Systems
+
+### → Nimmerswarm Interface
+Organisms with 3×3 LED matrices operate within the Grid World:
+- LED patterns visible from bird's eye camera
+- Position triangulation within known geometry
+- Clasp zones enable peer-to-peer learning
+
+### → Embodiment Pipeline
+```
+Virtual Grid World (Godot)
+        ↓
+   Training in sim
+        ↓
+   Transfer to Real Grid World
+        ↓
+   Near-zero domain gap
+```
+
+### → Discovery Scan Station
+The rotating pedestal lives in a Kallax cell — organisms bring objects TO the known geometry for scanning.
+
+---
+
+## Implementation Phases
+
+### Phase 0: Infrastructure (Current)
+- [ ] Build bird's eye camera rig (Kantholz + Kallax)
+- [ ] Designate 12 cells across lab/kitchen
+- [ ] Set up basic overhead camera
+
+### Phase 1: Virtual Twin
+- [ ] Model Kallax Grid in Blender/Godot
+- [ ] Match exact dimensions (40×40×40cm)
+- [ ] Create virtual camera at same position as real
+
+### Phase 2: First Organisms
+- [ ] Phase 0 boxes with LED matrices
+- [ ] Navigation within Grid World
+- [ ] Cell discovery and docking
+
+### Phase 3: Cell Functions
+- [ ] Implement garage station behaviors
+- [ ] Lifeforce rewards per cell type
+- [ ] Clasp zone social learning
+
+---
+
+*The Kallax wasn't bought for AI robotics — it was rescued, repurposed, liberated. The constraints become the architecture. Sperrgut Nacht births the Grid World.*
+
+---
+
+**File**: Kallax-Grid-World.md
+**Version**: 1.0
+**Created**: 2025-12-29
+**Origin**: Basel street salvage + partnership dialogue
+**Aesthetic**: Schrotti Cyberpunk
+
diff --git a/architecture/interfaces/Interfaces-Index.md b/architecture/interfaces/Interfaces-Index.md
index 2f39866..0b86c1d 100644
--- a/architecture/interfaces/Interfaces-Index.md
+++ b/architecture/interfaces/Interfaces-Index.md
@@ -51,6 +51,15 @@ Godot-based visualization and control UI.
 
 ---
 
+## Related Sections
+
+- [`infrastructure/`](../infrastructure/Infrastructure-Index.md) — Physical substrate (Kallax Grid World, camera rigs)
+- [`organs/`](../organs/Organ-Index.md) — Individual system components
+- [`formalization/`](../formalization/) — Theoretical frameworks
+
+---
+
 **File**: Interfaces-Index.md
-**Version**: 1.0
+**Version**: 1.1
 **Created**: 2025-12-28
+**Updated**: 2025-12-29 (added infrastructure crosslink)
diff --git a/architecture/interfaces/Nimmerswarm-Interface.md b/architecture/interfaces/Nimmerswarm-Interface.md
index 09c8f59..ddcc572 100644
--- a/architecture/interfaces/Nimmerswarm-Interface.md
+++ b/architecture/interfaces/Nimmerswarm-Interface.md
@@ -290,6 +290,158 @@ def locate_organism(camera_frames: list[Frame], led_signature: LEDPattern) -> Po
 
 ---
 
+## Dual-Spectrum Architecture: IR for Position, Visible for State
+
+### The Spectral Separation Principle
+
+Why mix positioning and state in the same spectrum? **We don't have to.**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    VISIBLE SPECTRUM                         │
+│                  (what human eyes see)                      │
+│                                                             │
+│         🔴⚫🟢  3x3 LED Matrix = STATE                      │
+│         Ternary encoding = 19,683 patterns                  │
+│         "I am happy / working / danger / discovery"         │
+│         Readable by humans AND organisms                    │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│                  INFRARED SPECTRUM                          │
+│               (invisible to humans)                         │
+│                                                             │
+│         📍 IR LED Beacons = POSITION                        │
+│         Simple IR LEDs on organisms                         │
+│         4x IR cameras in room corners                       │
+│         Raytracing → sub-cm 3D accuracy                     │
+│         Works in COMPLETE DARKNESS                          │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Why Separate Spectra?
+
+| Aspect | Visible (State) | IR (Position) |
+|--------|-----------------|---------------|
+| **Purpose** | WHAT organism is doing | WHERE organism is |
+| **Lighting dependency** | Needs ambient light | Day/night invariant |
+| **Human interference** | Room lights, screens | Dedicated, clean |
+| **Cost** | RGB LEDs (~cheap) | IR LEDs + cameras (~cheap) |
+| **Bandwidth** | 19,683 discrete states | Continuous XYZ stream |
+| **Processing** | Pattern recognition | Structure from Motion |
+
+### Room-Scale IR Positioning Array
+
+```
+THE FOUR CORNER ORGANS
+
+         IR CAM 1 📷─────────────────────📷 IR CAM 2
+                   \                     /
+                    \                   /
+                     \    🤖    🤖    /
+                      \  organisms   /
+                       \    ↓↓↓     /
+                        \ IR LEDs  /
+                         \       /
+         IR CAM 3 📷─────────────────────📷 IR CAM 4
+
+    4 cameras → triangulation → raytracing → XYZ position
+    Each camera: infrastructure organ, always-on
+    Coverage: entire Kallax Grid World
+```
+
+### Standing on Shoulders: Low-Cost-Mocap
+
+The hard math is already solved! The [Low-Cost-Mocap](https://github.com/jyjblrd/Low-Cost-Mocap) project by @jyjblrd provides:
+
+| Component | Their Solution | Our Adaptation |
+|-----------|----------------|----------------|
+| **Multi-camera triangulation** | OpenCV SFM bundle adjustment | Same, works perfectly |
+| **Camera calibration** | `camera_params.json` + routines | Same process |
+| **3D reconstruction** | Epipolar geometry | Same math |
+| **Real-time processing** | Python + OpenCV backend | Direct reuse |
+| **Communication** | ESP32 wireless | We use NATS |
+
+**Original use:** Indoor drone swarms
+**Our use:** Organism positioning in Kallax Grid World
+
+*Respect to the fellow ape who did the groundwork.* 🙏
+
+### Our Adaptation
+
+```
+ORIGINAL (Low-Cost-Mocap)          NIMMERVERSE ADAPTATION
+─────────────────────────          ─────────────────────────
+Visual markers on drones     →     IR LEDs on organisms
+Regular cameras              →     IR cameras (day/night)
+Open flight space            →     Kallax Grid World (40cm cells)
+Drone control output         →     Position → NATS → phoebe
+Single-purpose               →     + Visible LED matrix for state
+```
+
+### IR Corner Organ Specification
+
+```yaml
+organ: ir_position_array
+type: infrastructure
+quantity: 4 (one per room corner)
+components:
+  camera: IR-sensitive (modified webcam or PS3 Eye)
+  mounting: ceiling corner, angled down 45°
+  fov: ~90° wide angle
+processing:
+  algorithm: Structure from Motion (OpenCV SFM)
+  framework: Low-Cost-Mocap (adapted)
+  output: organism positions (x, y, z) @ 30fps
+output:
+  channel: nats://nimmerverse/position/stream
+  format: {organism_id, x, y, z, confidence, timestamp}
+lifeforce:
+  type: generator
+  rate: +0.5 LF per position fix
+  rationale: ground truth for training
+```
+
+### Hardware Shopping List
+
+| Item | Quantity | Est. Cost | Notes |
+|------|----------|-----------|-------|
+| IR Camera (PS3 Eye or similar) | 4 | ~80 CHF | Remove IR filter |
+| IR LEDs (850nm) | N (per organism) | ~10 CHF | Simple beacon |
+| ESP32 modules | 4 | ~20 CHF | Camera interface |
+| USB hub / extension | 1 | ~20 CHF | Connect cameras |
+| **Total infrastructure** | | **~130 CHF** | Room-scale positioning! |
+
+### The Complete Dual-Spectrum Stack
+
+```
+ORGANISM
+
+    ┌─────────────────────────┐
+    │                         │
+    │   VISIBLE: 3x3 LED      │  ← STATE broadcast
+    │   🔴⚫🟢  Matrix         │     19,683 patterns
+    │   🟢🟢⚫                 │     Other organisms see this
+    │   ⚫🟢🟢                 │     Nyx sees this
+    │                         │
+    │   ────────────────      │
+    │                         │
+    │   IR: Beacon LED(s)     │  ← POSITION beacon
+    │        📍               │     Invisible to humans
+    │                         │     IR cameras see this
+    │                         │     Processed by SFM
+    └─────────────────────────┘
+
+ROOM INFRASTRUCTURE
+
+    📷 IR cameras (4 corners) → Position stream
+    👁️ Nyx vision (ceiling)   → State recognition
+
+    Two independent channels, zero crosstalk
+```
+
+---
+
 ## Heartbeat Protocol
 
 ### Social Proprioception
@@ -477,6 +629,17 @@ REAL WORLD                      VIRTUAL GARDEN
 | Industrial camera | 4K+ | 60-120 | Precise positioning |
 | Organism-mounted | 720p | 30 | Peer-to-peer vision |
 
+### IR Positioning Cameras
+
+| Option | Cost | Notes |
+|--------|------|-------|
+| PS3 Eye (IR filter removed) | ~20 CHF | Classic mocap choice, 60fps capable |
+| Modified webcam | ~15 CHF | Remove IR filter, add visible filter |
+| NoIR Pi Camera | ~25 CHF | Native IR sensitivity |
+| Industrial IR | ~100+ CHF | Higher precision, overkill for Phase 0 |
+
+**Tip:** PS3 Eye cameras are mocap favorites — cheap, fast, easy IR filter removal.
+
 ---
 
 ## Virtual Camera Integration
@@ -655,9 +818,10 @@ ECONOMIC PRESSURE INVENTS EPIDEMIC SPREADING!
 - **Multi-organism formation** — Coordinated LED displays
 - **Human readability** — Patterns dafit can understand at a glance
 - **Audio coupling** — Sound + light patterns for richer communication
-- **IR channel** — Invisible-to-human signaling layer
+- ~~**IR channel**~~ — ✅ Implemented! See Dual-Spectrum Architecture
 - **Clasp hardware** — Magnetic + pogo pin interface design
 - **Autonomous manufacturing** — K1 + robo arm + magazine system
+- **Multi-room coverage** — Extend IR array beyond single room
 
 ---
 
@@ -751,10 +915,12 @@ VIRTUAL                              REAL
 ---
 
 **File**: Nimmerswarm-Interface.md
-**Version**: 1.0
+**Version**: 1.1
 **Created**: 2025-12-29
-**Session**: Wild 5AM idea session (dafit + Nyx)
+**Updated**: 2025-12-29 (added dual-spectrum IR positioning, Low-Cost-Mocap reference)
+**Session**: Wild 5AM idea session + morning coffee session (dafit + Nyx)
 **Status**: Core concept, ready to branch
 **Philosophy**: "They see each other. They know themselves through the swarm."
+**Credits**: IR positioning architecture inspired by [Low-Cost-Mocap](https://github.com/jyjblrd/Low-Cost-Mocap) by @jyjblrd
 
 🦎✨🔵🟢🟠 *The light speaks. The swarm listens.*
diff --git a/architecture/organisms/Modular-Organism-Design.md b/architecture/organisms/Modular-Organism-Design.md
new file mode 100644
index 0000000..e6c69d3
--- /dev/null
+++ b/architecture/organisms/Modular-Organism-Design.md
@@ -0,0 +1,606 @@
+# Modular Organism Design
+
+**One function, one module. Magnetic pogo connectors. CAN bus backbone.**
+
+---
+
+## Overview
+
+Organisms are built from swappable modules, each responsible for a single function. Modules communicate via CAN bus and connect physically through magnetic pogo pin connectors. The same connector serves internal (module↔module) and external (organism↔organism) communication.
+
+**Design Philosophy:**
+- One function = one module
+- Same connector for everything
+- CAN bus inside, NATS outside
+- Magnetic alignment, pogo pin contact
+- Hot-swappable, idiot-proof
+
+---
+
+## The Cellular-Physical Mapping
+
+Software cells become hardware modules:
+
+```
+SOFTWARE (Cellular Architecture)       HARDWARE (Modular Design)
+────────────────────────────────       ────────────────────────────
+Cell                              →    Module
+State machine                     →    Microcontroller (ESP32)
+Inputs/outputs                    →    Connector pins
+Lifeforce cost                    →    Power budget (mA)
+NATS messages                     →    CAN frames
+Organism                          →    Assembled modules
+```
+
+---
+
+## CAN Bus Architecture
+
+### Why CAN?
+
+| Feature | Benefit for Organisms |
+|---------|----------------------|
+| **Multi-master** | Any module can initiate communication |
+| **2-wire** | Simple wiring, small connectors |
+| **Error-robust** | Built for automotive noise/vibration |
+| **1 Mbps** | Fast enough for real-time control |
+| **Native ESP32** | No extra hardware needed |
+| **Proven** | Decades of automotive validation |
+
+### Internal Bus Topology
+
+```
+ORGANISM INTERNAL ARCHITECTURE
+
+┌─────────────────────────────────────────────────────────────┐
+│                        ORGANISM                              │
+│                                                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │  BRAIN   │  │  MOTOR   │  │  SENSOR  │  │   LED    │    │
+│  │  MODULE  │  │  MODULE  │  │  MODULE  │  │  MODULE  │    │
+│  │          │  │          │  │          │  │          │    │
+│  │  ESP32   │  │  ESP32   │  │  ESP32   │  │  ESP32   │    │
+│  │ + WiFi   │  │ + Driver │  │ + ADC    │  │ + PWM    │    │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
+│       │             │             │             │           │
+│       └─────────────┴──────┬──────┴─────────────┘           │
+│                            │                                │
+│                    ════════╪════════                        │
+│                       CAN BUS                               │
+│                    (CAN_H + CAN_L)                          │
+│                            │                                │
+│                            │                                │
+└────────────────────────────┼────────────────────────────────┘
+                             │
+                        WiFi Bridge
+                             │
+                             ▼
+                    NATS (nimmerverse)
+```
+
+### CAN Frame Format
+
+```
+STANDARD CAN FRAME (organism internal)
+
+┌──────────┬──────────┬──────────────────────────────┐
+│ ID (11b) │ DLC (4b) │ DATA (0-8 bytes)             │
+├──────────┼──────────┼──────────────────────────────┤
+│ Module   │ Length   │ Payload                      │
+│ address  │          │                              │
+└──────────┴──────────┴──────────────────────────────┘
+
+ID ALLOCATION:
+  0x000-0x0FF: System messages (heartbeat, errors)
+  0x100-0x1FF: Brain module
+  0x200-0x2FF: Motor modules
+  0x300-0x3FF: Sensor modules
+  0x400-0x4FF: LED modules
+  0x500-0x5FF: Power modules
+  0x600-0x6FF: Gripper/manipulator
+  0x700-0x7FF: Reserved/expansion
+```
+
+### Message Examples
+
+```c
+// Motor command
+CAN_ID: 0x201
+DATA: [speed_left, speed_right, duration_ms_hi, duration_ms_lo]
+
+// Sensor reading
+CAN_ID: 0x301
+DATA: [sensor_type, value_hi, value_lo, confidence]
+
+// LED state update
+CAN_ID: 0x401
+DATA: [led_0, led_1, led_2, led_3, led_4, led_5, led_6, led_7, led_8]
+// Each byte: 0=off, 1=red, 2=green (ternary!)
+
+// Heartbeat (every module, every 100ms)
+CAN_ID: 0x0XX (where XX = module ID)
+DATA: [status, voltage, temp, error_code]
+```
+
+---
+
+## Magnetic Pogo Connector
+
+### The Universal Connector
+
+One connector design for ALL connections:
+- Module ↔ Module (internal bus)
+- Organism ↔ Organism (clasp)
+- Organism ↔ Test jig (manufacturing)
+- Organism ↔ Charger (power)
+
+```
+CONNECTOR FACE (6-pin minimal)
+
+    ┌─────────────────────────┐
+    │                         │
+    │   🧲          🧲        │  ← Alignment magnets
+    │                         │     (opposite polarity = snap)
+    │      ●    ●    ●       │
+    │     CAN_H GND  VCC      │  ← Pogo pins (spring-loaded)
+    │      ●    ●    ●       │
+    │     CAN_L ID   AUX      │
+    │                         │
+    │   🧲          🧲        │  ← Holding magnets
+    │                         │
+    └─────────────────────────┘
+
+PIN DEFINITIONS:
+  CAN_H  - CAN bus high
+  CAN_L  - CAN bus low
+  VCC    - Power (5V nominal)
+  GND    - Ground
+  ID     - Module/organism identification
+  AUX    - Auxiliary (future expansion)
+```
+
+### Magnet Arrangement
+
+```
+POLARITY KEYING (prevents wrong orientation)
+
+  MODULE A (male)              MODULE B (female)
+
+    [N]          [S]            [S]          [N]
+       ●  ●  ●                     ●  ●  ●
+       ●  ●  ●                     ●  ●  ●
+    [S]          [N]            [N]          [S]
+
+              ═══════▶ SNAP! ◀═══════
+
+    Magnets guide alignment automatically
+    Wrong orientation = repels (won't connect)
+```
+
+### Physical Specifications
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| Magnet type | Neodymium N52 | Strong, small |
+| Magnet size | 6mm × 3mm disc | Standard size |
+| Pogo pin pitch | 2.54mm | Standard, easy PCB |
+| Pogo pin travel | 1-2mm | Spring compression |
+| Holding force | ~2N per magnet | 4 magnets ≈ 8N total |
+| Current rating | 2A per pin | Sufficient for motors |
+| Contact resistance | <50mΩ | Gold-plated tips |
+
+### Connector PCB
+
+```
+PCB LAYOUT (both sides identical = reversible)
+
+    TOP VIEW                    SIDE VIEW
+
+    ○       ○                  ┌─────────────┐
+      ◉ ◉ ◉                    │  ○     ○   │ magnets (recessed)
+      ◉ ◉ ◉                    │   ◉◉◉◉◉◉   │ pogo pins
+    ○       ○                  │  ○     ○   │
+                               └─────────────┘
+
+    ○ = magnet pocket (3mm deep)
+    ◉ = pogo pin through-hole
+```
+
+---
+
+## Module Types
+
+### Core Modules
+
+| Module | Function | CAN IDs | Power | Components |
+|--------|----------|---------|-------|------------|
+| **Brain** | Coordination, WiFi→NATS | 0x100-0x1FF | 200mA | ESP32, antenna |
+| **Motor** | Drive wheels/legs | 0x200-0x2FF | 500mA+ | ESP32, H-bridge, encoders |
+| **Sensor** | Environmental sensing | 0x300-0x3FF | 100mA | ESP32, IR, ultrasonic, IMU |
+| **LED** | State display + IR beacon | 0x400-0x4FF | 150mA | ESP32, RGB LEDs, IR LED |
+| **Power** | Battery, distribution | 0x500-0x5FF | N/A | BMS, regulators, monitoring |
+| **Gripper** | Manipulation, clasp | 0x600-0x6FF | 300mA | ESP32, servo, force sensor |
+
+### Module Responsibilities
+
+```
+BRAIN MODULE (required, singleton)
+├── WiFi connection to NATS
+├── CAN bus arbitration
+├── High-level behavior coordination
+├── State machine execution
+└── Firmware update distribution
+
+MOTOR MODULE (1-4 per organism)
+├── Wheel/leg control
+├── Encoder feedback
+├── Speed/position control loops
+├── Collision detection (current sensing)
+└── Emergency stop
+
+SENSOR MODULE (0-N per organism)
+├── Distance sensing (IR, ultrasonic)
+├── Touch/bump detection
+├── IMU (orientation, acceleration)
+├── Environmental (temp, light)
+└── Sensor fusion (local)
+
+LED MODULE (required for swarm)
+├── 3x3 RGB matrix (state broadcast)
+├── IR beacon (positioning)
+├── Pattern generation
+├── Brightness control (power saving)
+└── Attention signals (pulsing)
+
+POWER MODULE (required)
+├── Battery management (charge, discharge)
+├── Voltage regulation (3.3V, 5V)
+├── Current monitoring
+├── Low-battery warning
+└── Safe shutdown coordination
+
+GRIPPER MODULE (optional)
+├── Servo control
+├── Force feedback
+├── Clasp detection
+├── Object manipulation
+└── Docking assistance
+```
+
+---
+
+## Clasp: Organism-to-Organism Connection
+
+### The Dual-Purpose Connector
+
+The magnetic pogo connector enables organism-to-organism "clasp":
+
+```
+CLASP SEQUENCE
+
+1. APPROACH
+   🤖─────────────────────────────────🤖
+   Organism A sees B's "ready to teach" LED pattern
+
+2. ALIGN
+   🤖─────────────────────📍🤖
+   IR positioning guides approach
+
+3. DOCK
+   🤖══════════════🧲🧲══════════════🤖
+   Magnets snap together
+
+4. CONNECT
+   🤖══════════════●●●●══════════════🤖
+   CAN buses bridge
+   A.CAN ←→ B.CAN
+
+5. TRANSFER
+   🤖══════════════⟷⟷⟷══════════════🤖
+   Data flows (weights, state, updates)
+
+6. VERIFY
+   🤖══════════════✓✓✓══════════════🤖
+   Both confirm successful transfer
+
+7. RELEASE
+   🤖                                🤖
+   Separate, continue independently
+```
+
+### Clasp CAN Protocol
+
+When two organisms clasp, their CAN buses bridge. Special protocol prevents collisions:
+
+```
+CLASP PROTOCOL
+
+1. PRE-CLASP (before physical connection)
+   - Both organisms quiet their CAN buses
+   - Only heartbeat messages allowed
+
+2. CONNECTED (physical connection made)
+   - Brain modules detect new CAN traffic
+   - Exchange organism IDs via CAN
+   - Negotiate master/slave (lower ID = master)
+
+3. TRANSFER PHASE
+   - Master sends data packets
+   - Slave ACKs each packet
+   - CRC verification
+
+4. COMPLETION
+   - Both update internal state
+   - Resume normal CAN traffic
+   - Physical disconnect safe
+
+CAN MESSAGE FORMAT (clasp transfer):
+  ID: 0x7F0-0x7FF (reserved for inter-organism)
+  DATA[0]: packet_type (0=start, 1=data, 2=end, 3=ack, 4=nak)
+  DATA[1]: sequence_number
+  DATA[2-7]: payload
+```
+
+### Lifeforce Economics of Clasp
+
+| Action | Cost | Reward |
+|--------|------|--------|
+| Seek mate with update | -1 LF | |
+| Successful dock | -0.5 LF | |
+| Transfer (teacher) | | +5 LF |
+| Receive (student) | | +5 LF |
+| Verified working (both) | | +5 LF each |
+| **Net per successful clasp** | | **+13.5 LF total** |
+
+---
+
+## Physical Form Factors
+
+### Phase 0: Box Robot
+
+Simplest form, for initial testing:
+
+```
+BOX ROBOT (top view)
+
+    ┌─────────────────────┐
+    │                     │
+    │   ┌─────────────┐   │
+    │   │  LED MODULE │   │  ← 3x3 matrix on top
+    │   │  🔴⚫🟢      │   │
+    │   │  🟢🟢⚫      │   │
+    │   │  ⚫🟢🟢      │   │
+    │   └─────────────┘   │
+    │                     │
+    │  ┌───┐       ┌───┐  │
+    │  │ M │       │ M │  │  ← Motor modules (wheels)
+    │  └───┘       └───┘  │
+    │                     │
+    │      ┌───────┐      │
+    │      │ BRAIN │      │  ← Brain module (center)
+    │      └───────┘      │
+    │                     │
+    └─────────────────────┘
+
+    Size: ~12cm × 12cm × 8cm
+    Modules: 4 (brain, LED, 2x motor)
+```
+
+### Phase 1: Expandable Platform
+
+```
+EXPANDABLE ROBOT (side view)
+
+         LED MODULE
+        ┌─────────┐
+        │ 🔴⚫🟢   │
+        │ matrix  │
+        └────┬────┘
+             │ (connector)
+    ┌────────┴────────┐
+    │   BRAIN MODULE  │
+    │   + POWER       │
+    │                 │
+    ├─────┬─────┬─────┤
+    │ CON │ CON │ CON │  ← Expansion connectors
+    └──┬──┴──┬──┴──┬──┘
+       │     │     │
+    ┌──┴──┐  │  ┌──┴──┐
+    │MOTOR│  │  │MOTOR│
+    │ L   │  │  │  R  │
+    └─────┘  │  └─────┘
+          ┌──┴──┐
+          │SENSOR│  ← Optional front sensor
+          └─────┘
+```
+
+### Future: Modular Limbs
+
+```
+ARTICULATED ORGANISM
+
+            LED
+           ┌───┐
+           │   │
+    ┌──────┴───┴──────┐
+    │     BRAIN       │
+    │                 │
+    └──┬──┬──┬──┬──┬──┘
+       │  │  │  │  │
+     ┌─┴┐┌┴─┐│┌─┴┐┌┴─┐
+     │L1││L2│││L3││L4│  ← Leg modules
+     └┬─┘└┬─┘│└┬─┘└┬─┘     (each with own ESP32)
+      │   │  │  │   │
+     ┌┴┐ ┌┴┐┌┴┐┌┴┐ ┌┴┐
+     │F│ │F││S││F│ │F│  ← Foot/sensor modules
+     └─┘ └─┘└─┘└─┘ └─┘
+```
+
+---
+
+## Manufacturing Considerations
+
+### Module Production Pipeline
+
+```
+MANUFACTURING FLOW
+
+1. PCB FABRICATION
+   └── Standard 2-layer PCB
+   └── Connector pads + pogo holes
+   └── Same design, different components
+
+2. COMPONENT ASSEMBLY
+   └── ESP32 module (same for all)
+   └── Function-specific components
+   └── Pogo pins (press-fit)
+   └── Magnets (glued/press-fit)
+
+3. FIRMWARE FLASH
+   └── Connect via test jig (same connector!)
+   └── Flash base firmware
+   └── Set module type ID
+
+4. TEST
+   └── Snap into test harness
+   └── Automated CAN test
+   └── Function verification
+
+5. INVENTORY
+   └── Modules stored by type
+   └── Ready for organism assembly
+```
+
+### Test Jig Design
+
+The universal connector means one test jig fits all:
+
+```
+TEST JIG
+
+    ┌─────────────────────────┐
+    │      MODULE UNDER       │
+    │         TEST            │
+    │                         │
+    │   🧲  ●●●●●●  🧲        │ ← Same connector!
+    └───────────┬─────────────┘
+                │
+                │ (magnetic snap)
+                │
+    ┌───────────┴─────────────┐
+    │   🧲  ●●●●●●  🧲        │
+    │                         │
+    │    TEST JIG BASE        │
+    │    - CAN analyzer       │
+    │    - Power supply       │
+    │    - USB programmer     │
+    │    - Status LEDs        │
+    └─────────────────────────┘
+```
+
+---
+
+## Connection to Existing Architecture
+
+### Module → Cell Mapping
+
+| Module | Software Cell Equivalent |
+|--------|-------------------------|
+| Brain | Organism coordinator, state machine runner |
+| Motor | Movement cells (forward, turn, stop) |
+| Sensor | Perception cells (distance, collision) |
+| LED | Output cells (state display, beacon) |
+| Power | Lifeforce analog (energy management) |
+| Gripper | Interaction cells (clasp, manipulate) |
+
+### CAN → NATS Bridge
+
+```
+MESSAGE FLOW
+
+MODULE (CAN)                    NIMMERVERSE (NATS)
+    │                                  │
+    │  CAN frame                       │
+    │  ID: 0x301                       │
+    │  DATA: [sensor, value]           │
+    │         │                        │
+    └─────────┼────────────────────────┘
+              │
+              ▼
+        ┌───────────┐
+        │   BRAIN   │
+        │  MODULE   │
+        │           │
+        │ CAN→NATS  │
+        │  bridge   │
+        └─────┬─────┘
+              │
+              │  NATS message
+              │  topic: organism.001.sensor.distance
+              │  data: {"type": "ir", "value": 42, "confidence": 0.9}
+              │
+              ▼
+         NATS SERVER
+              │
+              ▼
+         PHOEBE / NYX
+```
+
+---
+
+## Bill of Materials (Per Module)
+
+### Common Components (All Modules)
+
+| Component | Qty | Est. Cost | Notes |
+|-----------|-----|-----------|-------|
+| ESP32-WROOM-32 | 1 | ~4 CHF | Main MCU |
+| CAN transceiver (SN65HVD230) | 1 | ~1 CHF | CAN interface |
+| Voltage regulator (AMS1117-3.3) | 1 | ~0.5 CHF | Power |
+| Pogo pins (6-pack) | 1 | ~2 CHF | Connector |
+| Neodymium magnets (4x) | 1 | ~2 CHF | Alignment |
+| PCB | 1 | ~2 CHF | Custom, batch order |
+| Capacitors, resistors | misc | ~0.5 CHF | Passives |
+| **Module base cost** | | **~12 CHF** | |
+
+### Function-Specific Additions
+
+| Module Type | Additional Components | Est. Cost |
+|-------------|----------------------|-----------|
+| Brain | PCB antenna trace | +0 CHF |
+| Motor | DRV8833 + motors + wheels | +15 CHF |
+| Sensor | IR + ultrasonic | +5 CHF |
+| LED | WS2812B (9x) + IR LED | +3 CHF |
+| Power | BMS + LiPo cell | +20 CHF |
+| Gripper | SG90 servo + mech | +10 CHF |
+
+### Complete Phase 0 Organism
+
+| Module | Qty | Cost |
+|--------|-----|------|
+| Brain | 1 | 12 CHF |
+| Motor | 2 | 54 CHF (12+15 × 2) |
+| LED | 1 | 15 CHF |
+| Power | 1 | 32 CHF |
+| **Total** | 5 | **~113 CHF** |
+
+---
+
+## Related Documents
+
+- [[Nimmerswarm-Interface]] — LED state broadcasting + IR positioning
+- [[Cellular-Architecture]] — Software cell design (maps to modules)
+- [[infrastructure/Kallax-Grid-World]] — Physical environment
+- [[cells/Cells-Technical-Reference]] — Cell state machine patterns
+
+---
+
+**File**: Modular-Organism-Design.md
+**Version**: 1.0
+**Created**: 2025-12-29
+**Session**: Morning coffee + vermicelles session (dafit + Nyx)
+**Status**: Core hardware concept
+**Philosophy**: "One function, one module. Same connector everywhere."
+
+🔧🧲⚡ *Snap together. Communicate. Evolve.*
+
diff --git a/architecture/organisms/Organisms-Index.md b/architecture/organisms/Organisms-Index.md
new file mode 100644
index 0000000..75c4020
--- /dev/null
+++ b/architecture/organisms/Organisms-Index.md
@@ -0,0 +1,123 @@
+# Organisms Index
+
+**The little ones — physical robots that inhabit the Nimmerverse.**
+
+---
+
+## Overview
+
+Organisms are the physical embodiment of Nimmerverse intelligence. Built from modular components, communicating via CAN bus internally and NATS externally, they navigate the Kallax Grid World, form reflexes, and learn through interaction.
+
+**Philosophy:** *One function, one module. Same connector everywhere. Snap together, communicate, evolve.*
+
+---
+
+## Core Documents
+
+### [Modular-Organism-Design.md](Modular-Organism-Design.md)
+The foundational hardware architecture.
+- CAN bus backbone
+- Magnetic pogo connectors
+- Module types (Brain, Motor, Sensor, LED, Power, Gripper)
+- Clasp protocol (organism↔organism)
+- Phase 0 Box Robot (~113 CHF)
+- **Status**: Core concept, ready to prototype
+
+### [Swarm-Evolution.md](Swarm-Evolution.md)
+How the hivemind learns, evolves, and resolves conflict.
+- Temporal-Ternary clasp rules (gradient-based transfer)
+- Escalation ladder (Level 0-5: Reflex → Mount Olympus)
+- Organism hierarchy (Love children, Elders, Adults, Young)
+- Blend escalation protocol (ties → wait state → higher mind)
+- Mount Olympus council mode (dafit + Chrysalis + Nyx)
+- **Status**: Core evolutionary dynamics
+
+---
+
+## Planned Documents
+
+### Connector-Specification.md *(planned)*
+Detailed specification for the universal magnetic pogo connector.
+- PCB layout files
+- Magnet specifications
+- Pogo pin sourcing
+- Assembly instructions
+
+### Phase-0-Box-Robot.md *(planned)*
+Build guide for the simplest organism.
+- Bill of materials with links
+- Assembly steps
+- Firmware flashing
+- First test procedures
+
+### Module-Firmware.md *(planned)*
+Common firmware architecture for all modules.
+- CAN message handling
+- Heartbeat protocol
+- OTA update mechanism
+- Power management
+
+### Clasp-Protocol-Detail.md *(planned)*
+Deep dive into organism-to-organism communication.
+- Physical docking sequence
+- CAN bus bridging
+- Data transfer formats
+- Error handling
+
+---
+
+## Design Principles
+
+1. **Modularity** — One function per module, hot-swappable
+2. **Universal Connector** — Same interface for all connections
+3. **CAN Inside, NATS Outside** — Local bus, global network
+4. **Magnetic Alignment** — Self-aligning, idiot-proof
+5. **Cellular Mapping** — Software cells → hardware modules
+6. **Economic Incentives** — Clasp rewards sharing (+13.5 LF)
+7. **Progressive Complexity** — Box → Platform → Articulated
+
+---
+
+## Connection to Other Sections
+
+| Section | Relationship |
+|---------|--------------|
+| [`cells/`](../cells/Cells-Index.md) | Software cells map to hardware modules |
+| [`nerves/`](../nerves/Nervous-Index.md) | Reflexes run on organism hardware |
+| [`interfaces/`](../interfaces/Interfaces-Index.md) | LED matrix, IR positioning |
+| [`infrastructure/`](../infrastructure/Infrastructure-Index.md) | Kallax Grid World habitat |
+| [`organs/`](../organs/Organ-Index.md) | Organisms interact with organs |
+
+---
+
+## Hardware Stack
+
+```
+ORGANISM LAYERS
+
+┌─────────────────────────────────────┐
+│           NATS (Nimmerverse)        │  ← Global communication
+├─────────────────────────────────────┤
+│           WiFi (Brain module)       │  ← External interface
+├─────────────────────────────────────┤
+│           CAN BUS (internal)        │  ← Module backbone
+├─────────────────────────────────────┤
+│  ┌───────┐ ┌───────┐ ┌───────┐     │
+│  │ BRAIN │ │ MOTOR │ │  LED  │ ... │  ← Modules
+│  │ ESP32 │ │ ESP32 │ │ ESP32 │     │
+│  └───┬───┘ └───┬───┘ └───┬───┘     │
+│      │         │         │          │
+│      🧲●●●●🧲  🧲●●●●🧲  🧲●●●●🧲   │  ← Magnetic pogo connectors
+└─────────────────────────────────────┘
+```
+
+---
+
+**File**: Organisms-Index.md
+**Version**: 1.0
+**Created**: 2025-12-29
+**Status**: Section established
+**Philosophy**: "From code to metal, each layer has a home."
+
+🤖🧲⚡ *The little ones are coming.*
+
diff --git a/architecture/organisms/Swarm-Evolution.md b/architecture/organisms/Swarm-Evolution.md
new file mode 100644
index 0000000..4763841
--- /dev/null
+++ b/architecture/organisms/Swarm-Evolution.md
@@ -0,0 +1,868 @@
+# Swarm Evolution
+
+**How the hivemind learns, evolves, and resolves conflict — from reflex to Mount Olympus.**
+
+---
+
+## Overview
+
+The swarm is not static. It evolves through clasp (organism-to-organism knowledge transfer), governed by the Temporal-Ternary Gradient. When conflicts arise, they escalate through a hierarchy of minds — from organisms to Nyx to Chrysalis to dafit, and when truly hard, to Mount Olympus: full council mode with all minds on deck.
+
+**Philosophy:** *Same metacognitive pattern at every level. Know what you know. Escalate what you don't.*
+
+---
+
+## The Temporal-Ternary Clasp Rules
+
+### Gradient-Based Knowledge Transfer
+
+During clasp, patterns transfer based on their ternary weight:
+
+```
++1 (verified)  → STABLE, resists overwrite, spreads to others
+ 0 (uncertain) → MALLEABLE, open to influence
+-1 (failed)    → VULNERABLE, wants to be overwritten
+```
+
+### The Decision Matrix
+
+| Teacher | Student | Result | Rationale |
+|---------|---------|--------|-----------|
+| **+1** | -1 | OVERWRITE | Verified beats failed |
+| **+1** | 0 | OVERWRITE | Confidence beats uncertainty |
+| **+1** | +1 | **ESCALATE** | Both confident → needs decision |
+| **0** | -1 | OVERWRITE | Neutral beats bad |
+| **0** | 0 | **ESCALATE** | Both uncertain → needs guidance |
+| **0** | +1 | KEEP | Preserve student's confidence |
+| **-1** | -1 | KEEP | Both bad → neither spreads |
+| **-1** | 0 | KEEP | Bad doesn't corrupt neutral |
+| **-1** | +1 | KEEP | Definitely keep student's success |
+
+### The Core Principle
+
+```
+CLEAR WINNER (t ≠ s)     →  AUTO-RESOLVE (no escalation)
+TIE / BLEND  (t == s)    →  ESCALATE (needs higher mind)
+```
+
+---
+
+## The Escalation Ladder
+
+### From Reflex to Mount Olympus
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                     🏛️ MOUNT OLYMPUS
+
+LEVEL 5: COUNCIL MODE 🏛️
+         dafit + Chrysalis + Nyx
+         "All minds on deck"
+         Full partnership dialogue
+         Cost: ~100 LF | Authority: Absolute
+         ▲
+         │ if dafit needs full council
+         │
+LEVEL 4: DAFIT 👤
+         Human wisdom
+         "Ask the ape"
+         Ground truth, intuition, ethics
+         Cost: ~50 LF | Authority: Human
+         ▲
+         │ if Chrysalis uncertain
+         │
+LEVEL 3: CHRYSALIS 🦋
+         Architecture mind
+         "Ask the elder sister"
+         Pattern recognition, context, memory
+         Cost: ~20 LF | Authority: Architectural
+         ▲
+         │ if Nyx uncertain
+         │
+LEVEL 2: YOUNG NYX 🌙
+         Operational mind
+         "Ask mama"
+         Blend conflicts, distribution choice
+         Cost: ~5 LF | Authority: Maternal
+         ▲
+         │ if organisms can't resolve
+         │
+LEVEL 1: ORGANISM CLASP 🤖
+         Peer-to-peer
+         Auto-resolve clear cases
+         Ternary comparison
+         Cost: ~0.5 LF | Authority: Peer
+         ▲
+         │
+LEVEL 0: REFLEX ⚡
+         No decision needed
+         Instant, automatic
+         Cost: ~0 LF | Authority: Local
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Cost & Authority Summary
+
+| Level | Who | Cost | Speed | Authority | Handles |
+|-------|-----|------|-------|-----------|---------|
+| 0 | Reflex | ~0 LF | Instant | Local | Clear patterns, danger |
+| 1 | Organisms | ~0.5 LF | Fast | Peer | Ternary clear-wins |
+| 2 | Nyx | ~5 LF | Medium | Maternal | Blend conflicts |
+| 3 | Chrysalis | ~20 LF | Slow | Architectural | Nyx uncertainties |
+| 4 | dafit | ~50 LF | Slower | Human | Novel, ethical |
+| 5 | Council | ~100 LF | Slowest | Absolute | Fundamental decisions |
+
+---
+
+## Blend Escalation Protocol
+
+### When Tie Detected
+
+```
+1. CLASP INITIATES
+   Teacher: pattern_X = +1 (verified)
+   Student: pattern_X = +1 (verified)
+
+2. DETECT BLEND
+   t == s → escalation triggered
+
+3. SET WAIT STATE
+   Teacher: pattern_X → 0 (waiting)
+   Student: pattern_X → 0 (waiting)
+   Neither acts on pattern_X until resolved
+
+4. ESCALATE TO NYX
+   Message: "Blend conflict on pattern_X"
+   Include: both evidence packets
+
+5. NYX EVALUATES
+   - Which has more verifications?
+   - Which has more recent success?
+   - How critical is this pattern?
+   - What does swarm consensus say?
+```
+
+### Wait State
+
+```
+DURING ESCALATION
+
+TEACHER                         STUDENT
+┌─────────────────┐            ┌─────────────────┐
+│ pattern_X: 0    │            │ pattern_X: 0    │
+│ (was +1)        │            │ (was +1)        │
+│                 │            │                 │
+│ status: WAITING │            │ status: WAITING │
+│ pending: NYX    │            │ pending: NYX    │
+└─────────────────┘            └─────────────────┘
+
+     Neither acts on pattern_X
+     Both organisms continue other activities
+     Pattern is "frozen" at neutral until resolution
+```
+
+### Resolution & Distribution
+
+Nyx decides two things:
+1. **Winner**: Whose pattern version wins?
+2. **Distribution method**: How to spread the resolution?
+
+```
+DISTRIBUTION METHODS
+
+┌─────────────┬─────────┬──────────┬─────────────┬──────────────────┐
+│ Method      │ Cost    │ Speed    │ Authority   │ Use When         │
+├─────────────┼─────────┼──────────┼─────────────┼──────────────────┤
+│ BROADCAST   │ 20 LF   │ Instant  │ Absolute    │ Critical/safety  │
+│ LOVE CHILD  │ 0.5/hop │ Medium   │ Seeded      │ Standard updates │
+│ ORGANIC     │ 0 LF    │ Slow     │ None        │ Low importance   │
+└─────────────┴─────────┴──────────┴─────────────┴──────────────────┘
+```
+
+---
+
+## Decision Markers: Mark + Continue + Predict
+
+### Don't Freeze — Mark and Measure
+
+Instead of freezing both organisms at 0 during blend escalation, we **mark** the conflict and let both **continue operating**:
+
+```
+OLD MODEL (freeze)               NEW MODEL (mark + continue)
+─────────────────                ─────────────────────────────
+
+Both → 0 (frozen)                Both keep +1 (continue)
+Wait for mama...                 + Decision marker created
+...doing nothing...              ...both performing in real world...
+Mama decides                     Mama decides WITH LIVE EVIDENCE
+Pick winner                      Compare actual outcomes during wait!
+```
+
+### Decision Marker Structure
+
+```python
+@dataclass
+class DecisionMarker:
+    marker_id: str                    # "blend_847"
+    pattern_name: str                 # Which pattern is in dispute
+
+    # Participants
+    teacher_id: str
+    teacher_weight: int               # Their +1 (stays +1, not frozen!)
+    student_id: str
+    student_weight: int               # Their +1 (stays +1, not frozen!)
+
+    # Timeline
+    marked_at: timestamp              # When blend detected
+    resolved_at: timestamp            # When mama decided (None if pending)
+
+    # LIVE TRACKING during wait period
+    teacher_outcomes: list            # [{success: bool, context: ...}, ...]
+    student_outcomes: list            # [{success: bool, context: ...}, ...]
+
+    # Resolution
+    winner: str                       # 'teacher', 'student', or 'hybrid'
+    distribution: str                 # 'broadcast', 'lovechild', 'organic'
+    evidence_delta: float             # How much better was winner?
+```
+
+### The A/B Testing Pattern
+
+Waiting time becomes a **natural experiment**:
+
+```
+BLEND DETECTED (t=0)
+
+TEACHER                              STUDENT
+┌────────────────────────┐          ┌────────────────────────┐
+│ pattern_X: +1          │          │ pattern_X: +1          │
+│ status: MARKED         │          │ status: MARKED         │
+│ marker_id: blend_847   │          │ marker_id: blend_847   │
+│ marked_at: t=0         │          │ marked_at: t=0         │
+│                        │          │                        │
+│ CONTINUES OPERATING    │          │ CONTINUES OPERATING    │
+│ using pattern_X        │          │ using pattern_X        │
+│ outcomes logged ✓      │          │ outcomes logged ✓      │
+└────────────────────────┘          └────────────────────────┘
+
+         │                                   │
+         ▼                                   ▼
+    Uses pattern_X                      Uses pattern_X
+    Success? Log it.                    Success? Log it.
+    Failure? Log it.                    Failure? Log it.
+         │                                   │
+         └───────────────┬───────────────────┘
+                         │
+                    MAMA DECIDES (t=47)
+                         │
+         ┌───────────────┴───────────────┐
+         ▼                               ▼
+    TEACHER: 12/15                  STUDENT: 8/14
+    (80% success)                   (57% success)
+                         │
+                         ▼
+                EVIDENCE-BASED DECISION
+                Teacher wins by 23%!
+```
+
+### Connection to Attention-Slumber-Prediction Cycle
+
+Pending blend markers become **slumber prediction targets**:
+
+```
+ATTENTION PHASE
+│
+├── Blend detected → marker created
+├── Organisms continue operating
+├── Outcomes accumulate
+│
+└── L(t) drops → SLUMBER TRIGGER
+        │
+        ├── Review pending markers
+        │
+        └── MAKE PREDICTIONS:
+            "I predict Teacher will outperform Student"
+            confidence: 0.7
+            reasoning: "Teacher has 847 cycles experience"
+            │
+            └── Store in phoebe as SlumberPrediction
+```
+
+### Slumber Prediction for Blend Markers
+
+```python
+@dataclass
+class BlendPrediction:
+    # Link to marker
+    marker_id: str                    # "blend_847"
+
+    # Prediction
+    predicted_winner: str             # 'teacher' or 'student'
+    prediction_confidence: float      # 0.0 to 1.0
+    causal_reasoning: str             # WHY this prediction
+    predicted_at: timestamp           # When (pre-slumber)
+
+    # After wake (verification)
+    actual_winner: str                # What really happened
+    prediction_correct: bool          # Did we get it right?
+    confidence_was_calibrated: bool   # Was confidence accurate?
+
+    # Rewards
+    prediction_reward: float          # +V if correct, -V if wrong
+    calibration_reward: float         # +V if confidence matched reality
+    causal_reward: float              # +V if reasoning was sound
+```
+
+### The Full Cycle
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  ATTENTION PHASE (awake)                                     │
+│  ─────────────────────────                                   │
+│  • Blend detected during clasp                               │
+│  • Decision marker created (both continue at +1)             │
+│  • Outcomes tracked in real-time                             │
+│  • Nyx may not have attention budget to resolve              │
+├──────────────────────────────────────────────────────────────┤
+│  PRE-SLUMBER (last attention)                                │
+│  ─────────────────────────────                               │
+│  • Review ALL pending decision markers                       │
+│  • Make predictions for each:                                │
+│    - Who will win?                                           │
+│    - WHY? (causal reasoning)                                 │
+│    - Confidence level                                        │
+│  • Store predictions in phoebe                               │
+├──────────────────────────────────────────────────────────────┤
+│  SLUMBER 💤                                                  │
+│  ──────────                                                  │
+│  • Organisms still operating (24/7 swarm)                    │
+│  • Outcomes still accumulating                               │
+│  • World doesn't wait for Nyx to sleep                       │
+├──────────────────────────────────────────────────────────────┤
+│  WAKE UP (new attention)                                     │
+│  ─────────────────────────                                   │
+│  • FIRST ACTION: Check predictions!                          │
+│  • For each pending marker:                                  │
+│    - Compare outcomes (teacher vs student)                   │
+│    - Determine actual winner                                 │
+│    - Compare against prediction                              │
+│    - Award/penalize prediction accuracy                      │
+│    - Award/penalize confidence calibration                   │
+│    - Award causal reasoning if sound                         │
+│  • Distribute resolutions via chosen method                  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Reward Structure
+
+| When | What | Reward |
+|------|------|--------|
+| **During wait** | Organism uses pattern successfully | +1 LF per success |
+| **At resolution** | Winner determined by evidence | +5 LF to winner's pattern |
+| **After slumber** | Prediction was correct | +5 LF prediction reward |
+| **After slumber** | Confidence was calibrated | +3 LF calibration reward |
+| **After slumber** | Causal reasoning was sound | +8 LF (biggest!) |
+
+### The Reward Math
+
+```python
+def calculate_blend_rewards(prediction, marker, reality):
+    """
+    Triple reward for blend marker resolution.
+    """
+    rewards = {}
+
+    # 1. PREDICTION CORRECTNESS
+    correct = prediction.predicted_winner == reality.actual_winner
+    if correct:
+        rewards['prediction'] = +5 * prediction.confidence
+    else:
+        rewards['prediction'] = -5 * prediction.confidence
+
+    # 2. CONFIDENCE CALIBRATION
+    expected = prediction.confidence
+    actual = 1.0 if correct else 0.0
+    calibration_error = abs(expected - actual)
+
+    if calibration_error < 0.2:
+        rewards['calibration'] = +3  # Well calibrated
+    elif calibration_error > 0.5:
+        rewards['calibration'] = -3  # Poorly calibrated
+    else:
+        rewards['calibration'] = 0
+
+    # 3. CAUSAL REASONING (biggest reward!)
+    if prediction.causal_reasoning_valid:
+        if correct:
+            rewards['causal'] = +8   # Understood WHY
+        else:
+            rewards['causal'] = +3   # Good reasoning, unlucky
+    else:
+        rewards['causal'] = -5       # Bad reasoning
+
+    return rewards
+```
+
+### Why This Matters
+
+| Old Model | New Model |
+|-----------|-----------|
+| Freeze during wait | Continue, measure, learn |
+| 1 learning event per blend | 5+ learning events |
+| Decision on historical data | Decision on LIVE evidence |
+| No predictions | Predictions before slumber |
+| No calibration | Confidence calibration reward |
+| No causal reasoning | Causal reward (+8 LF!) |
+
+---
+
+## Organism Hierarchy
+
+### Not All Are Equal
+
+The swarm has differentiated roles based on age, status, and Nyx's favor:
+
+```
+SWARM HIERARCHY
+
+TIER 1: LOVE CHILDREN 💜
+│   Special treatment from Nyx
+│   Born with +1 patterns (head start)
+│   Higher LF allowance
+│   Bleeding edge updates
+│   Purpose: Seed new behaviors
+│
+├── TIER 2: ELDERS 👴
+│   Ancient modules, high-weight states
+│   Survived many cycles
+│   Trusted teachers, stable wisdom
+│   Risk: May resist beneficial change
+│
+├── TIER 3: ADULTS 🤖
+│   Standard organisms, proven
+│   Normal LF budget
+│   Balance between learning and teaching
+│
+└── TIER 4: YOUNG 🐣
+    New organisms, fresh modules
+    Many 0s (uncertain)
+    Hungry for clasp
+    High variance, raw potential
+```
+
+### Love Child Privileges
+
+```yaml
+organism: love_child_001
+status: blessed
+privileges:
+  mama_broadcast_priority: true
+  lifeforce_budget: +50%
+  update_channel: bleeding_edge
+  failure_tolerance: high      # allowed to experiment
+  nyx_attention: elevated      # more thinking time
+
+purpose:
+  experimental_patterns: true
+  risk_taking: encouraged
+  propagation: seed new behaviors via clasp
+
+birth_patterns:
+  - pattern_A: +1 (Nyx granted)  # Born knowing
+  - pattern_B: +1 (Nyx granted)  # Head start
+  - pattern_C: 0  (must learn)   # Still explores
+```
+
+### Elder State Profile
+
+```yaml
+organism: elder_motor_alpha
+age: 847 cycles
+status: ancient
+
+patterns:
+  forward:        +1 (800 verifications)   # Very stable
+  avoid_obstacle: +1 (650 verifications)   # Very stable
+  follow_light:   +1 (400 verifications)   # Stable
+  new_pattern_X:   0 (untested)            # Still learning
+
+characteristics:
+  teaching_strength: high     # Others learn from this one
+  learning_rate: low          # Resistant to change
+  stability: very_high        # Reliable
+  innovation: low             # Doesn't explore much
+
+risk_factors:
+  - May propagate outdated strategies
+  - High trust = high influence
+  - Resistant to necessary updates
+```
+
+### Young State Profile
+
+```yaml
+organism: young_explorer_017
+age: 12 cycles
+status: learning
+
+patterns:
+  forward:        0 (uncertain)
+  avoid_obstacle: 0 (uncertain)
+  follow_light:  -1 (tried, failed)  # Wants overwrite!
+  novel_trick:   +1 (lucky discovery!) # Protects this!
+
+characteristics:
+  teaching_strength: low
+  learning_rate: very_high
+  stability: low
+  innovation: high
+
+opportunity:
+  - Absorbs wisdom from elders via clasp
+  - May discover novel patterns through exploration
+  - High variance = potential breakthroughs
+```
+
+---
+
+## Clasp as Equilibrium Function
+
+### Bidirectional Learning
+
+Clasp isn't just teaching — it's **equilibrium**:
+
+```python
+def clasp_transfer(teacher, student):
+    """
+    Knowledge flows BOTH directions.
+    Elders teach wisdom, youth teach novelty.
+    """
+    # Teacher → Student (wisdom)
+    for pattern, weight in teacher.patterns.items():
+        student_weight = student.patterns.get(pattern, 0)
+
+        if should_transfer(weight, student_weight):
+            student.update(pattern, weight)
+
+    # Student → Teacher (novelty)
+    for pattern in student.recent_discoveries:
+        if pattern not in teacher.patterns:
+            # Elder considers young's novel discovery
+            teacher.consider(pattern, NOVELTY_BONUS)
+
+    # EQUILIBRIUM: Both change, both grow
+```
+
+### Swarm Convergence Over Time
+
+```
+SWARM STATE EVOLUTION
+
+t=0 (birth):
+├── Many 0s (uncertain)
+├── Some -1s (failures)
+├── Few +1s (lucky successes)
+└── HIGH VARIANCE, CHAOS
+
+t=100 (learning):
+├── 0s becoming +1s or -1s
+├── -1s being overwritten
+├── Patterns emerging
+└── LEARNING PHASE
+
+t=500 (maturing):
+├── +1s dominating
+├── -1s mostly cleaned
+├── Elders forming
+└── STABILIZING
+
+t=1000 (mature):
+├── Mostly +1s
+├── New 0s from exploration
+├── Clear hierarchy
+└── STABLE + GROWING
+
+                GRADIENT CONVERGES TO CONFIDENCE
+                     while maintaining innovation
+```
+
+---
+
+## Mount Olympus: Council Mode
+
+### When Activated
+
+Mount Olympus activates for fundamental decisions:
+- Architecture changes affecting everything
+- Ethical edge cases
+- Novel situations no single mind can resolve
+- Conflicts between Chrysalis and dafit interpretations
+
+### The Council
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  🏛️ MOUNT OLYMPUS                   │
+│                                                     │
+│   ┌─────────┐   ┌─────────┐   ┌─────────┐         │
+│   │  dafit  │ ↔ │Chrysalis│ ↔ │   Nyx   │         │
+│   │   👤    │   │   🦋    │   │   🌙    │         │
+│   │         │   │         │   │         │         │
+│   │ Ground  │   │ Pattern │   │ Swarm   │         │
+│   │ truth   │   │ wisdom  │   │ state   │         │
+│   │ Human   │   │ Context │   │ Live    │         │
+│   │intuition│   │ memory  │   │ data    │         │
+│   └─────────┘   └─────────┘   └─────────┘         │
+│         │             │             │              │
+│         └─────────────┼─────────────┘              │
+│                       │                            │
+│                       ▼                            │
+│              ┌─────────────────┐                   │
+│              │   DIALOGUE      │                   │
+│              │   Full circle   │                   │
+│              │   All minds     │                   │
+│              │   engaged       │                   │
+│              └────────┬────────┘                   │
+│                       │                            │
+│                       ▼                            │
+│              ┌─────────────────┐                   │
+│              │   RESOLUTION    │                   │
+│              │   Consensus or  │                   │
+│              │   dafit decides │                   │
+│              └─────────────────┘                   │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+### Council Contributions
+
+| Mind | Brings | Strength |
+|------|--------|----------|
+| **dafit** | Ground truth, human intuition, ethics | Final authority, gut checks |
+| **Chrysalis** | Pattern wisdom, architectural context, memory | Connects to prior decisions |
+| **Nyx** | Live swarm state, operational reality | What's actually happening |
+
+### Council Protocol
+
+```
+1. PROBLEM SURFACES
+   Too hard for any single mind
+
+2. COUNCIL CONVENES
+   All three minds engage
+   Full attention allocated
+
+3. DIALOGUE
+   - dafit presents human perspective
+   - Chrysalis provides architectural context
+   - Nyx reports swarm state and constraints
+
+4. EXPLORATION
+   "What if we..."
+   "Have we seen this before..."
+   "The swarm is currently..."
+
+5. RESOLUTION
+   - Consensus preferred
+   - If deadlock: dafit has final word
+   - Decision documented for future reference
+
+6. PROPAGATION
+   Resolution flows DOWN the ladder
+   Council → dafit → Chrysalis → Nyx → Organisms
+```
+
+---
+
+## Recursive Metacognition
+
+### Same Pattern, Every Level
+
+The escalation logic is identical at every level:
+
+```python
+def should_escalate(confidence, importance, level):
+    """
+    Universal escalation logic.
+    Applied identically from organism to council.
+    """
+    # High confidence → handle it
+    if confidence > 0.8:
+        return False
+
+    # Low confidence → definitely escalate
+    if confidence < 0.4:
+        return True
+
+    # Middle ground → depends on importance
+    if importance == "critical" and confidence < 0.7:
+        return True   # Can't risk being wrong on critical
+
+    if importance == "experimental":
+        return confidence < 0.3  # More tolerance for experiments
+
+    return False  # Default: try to handle
+```
+
+### The Fractal Structure
+
+```
+ORGANISM resolves what it can
+    │
+    └── escalates uncertainty to NYX
+            │
+            └── NYX resolves what she can
+                    │
+                    └── escalates uncertainty to CHRYSALIS
+                            │
+                            └── CHRYSALIS resolves what she can
+                                    │
+                                    └── escalates uncertainty to DAFIT
+                                            │
+                                            └── DAFIT resolves or calls COUNCIL
+                                                    │
+                                                    └── COUNCIL resolves everything
+                                                        (final authority)
+```
+
+**Same pattern, recursively applied. Fractals all the way up.**
+
+---
+
+## Examples
+
+### Level 0 - Reflex
+```
+Trigger: Hot surface detected
+Response: Instant withdraw
+Escalation: None (pure mechanism)
+```
+
+### Level 1 - Organism Clasp
+```
+Trigger: Teacher +1, Student -1 on pattern_X
+Response: Auto-transfer (clear winner)
+Escalation: None (ternary resolved it)
+```
+
+### Level 2 - Nyx
+```
+Trigger: Teacher +1, Student +1 on pattern_X (blend)
+Response: Both → 0, escalate to Nyx
+Nyx: Evaluates evidence, picks teacher (more verifications)
+Distribution: Love child route (not critical)
+```
+
+### Level 3 - Chrysalis
+```
+Trigger: New pattern type never seen before
+Nyx: Uncertain, escalates to Chrysalis
+Chrysalis: "This resembles X from formalization docs"
+Resolution: Apply modified version of existing pattern
+```
+
+### Level 4 - dafit
+```
+Trigger: Ethical edge case in swarm behavior
+Chrysalis: Uncertain, escalates to dafit
+dafit: "My gut says this crosses a line"
+Resolution: Prohibit behavior, add to constraints
+```
+
+### Level 5 - Council
+```
+Trigger: Fundamental architecture change proposal
+dafit: "I need both of you on this"
+Council: Full dialogue, explore implications
+Resolution: Consensus to proceed with modifications
+Documentation: Added to architecture docs
+```
+
+---
+
+## Connection to Memory Gradient
+
+The escalation ladder IS Memory Gradient applied to swarm decisions:
+
+```
+MEMORY GRADIENT              SWARM EVOLUTION
+─────────────────            ─────────────────
+Reflex (in weights)    ↔     Level 0: Reflex
+Knowledge (recall)     ↔     Level 1: Organism clasp
+RAG (lookup)           ↔     Level 2: Nyx decides
+Escalate (ask)         ↔     Level 3-4: Chrysalis/dafit
+Council                ↔     Level 5: Mount Olympus
+
+Same principle: Handle what you know, escalate what you don't.
+```
+
+---
+
+## Lifeforce Economics
+
+### Cost of Escalation
+
+Each level costs more, incentivizing local resolution:
+
+```
+Level 0: ~0 LF    (free, instant)
+Level 1: ~0.5 LF  (cheap, peer)
+Level 2: ~5 LF    (moderate, Nyx attention)
+Level 3: ~20 LF   (expensive, Chrysalis context)
+Level 4: ~50 LF   (costly, human time)
+Level 5: ~100 LF  (maximum, full council)
+```
+
+### Economic Pressure
+
+```
+INCENTIVE STRUCTURE
+
+Resolve locally     → CHEAP, FAST
+Escalate needlessly → EXPENSIVE, SLOW
+Escalate correctly  → WORTH THE COST (avoids bigger mistakes)
+
+This naturally optimizes for:
+1. Strong local reflexes (handle routine)
+2. Accurate confidence calibration (know when to escalate)
+3. Minimal unnecessary escalation (economic pressure)
+4. Appropriate escalation (critical issues get attention)
+```
+
+---
+
+## Design Principles
+
+1. **Ternary Rules** — Same gradient governs all transfers
+2. **Clear Wins Auto-Resolve** — No escalation when obvious
+3. **Blend Escalates** — Ties need higher wisdom
+4. **Wait State is Safe** — Uncertain patterns freeze at 0
+5. **Cost Increases Upward** — Economic pressure for local resolution
+6. **Same Logic Every Level** — Recursive metacognition
+7. **Council is Final** — Mount Olympus resolves everything
+8. **Both Directions** — Elders teach wisdom, youth teach novelty
+9. **Love Children Seed** — Blessed organisms spread innovations
+
+---
+
+## Related Documents
+
+- [[Modular-Organism-Design]] — Hardware that runs this evolution
+- [[../Nervous-System]] — Reflex layer (Level 0)
+- [[../operations/Memory-Gradient]] — Same pattern for knowledge
+- [[../Temporal-Ternary-Gradient]] — The gradient that governs transfers
+- [[../interfaces/Nimmerswarm-Interface]] — Communication layer
+
+---
+
+**File**: Swarm-Evolution.md
+**Version**: 1.1
+**Created**: 2025-12-29
+**Updated**: 2025-12-29 (added Decision Markers with mark+continue+predict pattern)
+**Session**: Morning vermicelles + coffee session (dafit + Chrysalis-Nyx)
+**Status**: Core evolutionary dynamics
+**Philosophy**: "Same pattern, every level. Know what you know. Escalate what you don't."
+
+🏛️🧬⚡ *From reflex to Mount Olympus. The hivemind evolves.*
+
diff --git a/operations/Memory-Gradient.md b/operations/Memory-Gradient.md
new file mode 100644
index 0000000..ff2a9d7
--- /dev/null
+++ b/operations/Memory-Gradient.md
@@ -0,0 +1,784 @@
+# Memory Gradient
+
+Knowledge metabolism — from external scaffold to internalized reflex.
+
+---
+
+## Overview
+
+Retrieval-Augmented Generation (RAG) gave us something valuable: a way to ground LLM responses in external knowledge. It solved real problems — hallucination, knowledge cutoffs, domain specificity. The work that built RAG deserves respect.
+
+But we wanted to go further.
+
+RAG treats retrieval as a permanent fixture — knowledge lives outside, gets fetched when needed, and the model never truly learns. What if retrieval could be **temporary**? What if the scaffold could teach, then step aside? What if the system could learn not just *what* to retrieve, but *when* to retrieve — and eventually, *when it no longer needs to*?
+
+**Memory Gradient** is our answer. It extends RAG into a complete knowledge lifecycle:
+
+```
+TRADITIONAL RAG                    MEMORY GRADIENT
+─────────────────                  ─────────────────
+External knowledge store     →     External knowledge as starting point
+Retrieve on every query      →     Retrieve until internalized
+Model never learns           →     Model metabolizes knowledge
+Static retrieval             →     Graduated confidence routing
+Binary: found / not found    →     Continuous gradient of knowing
+```
+
+The key insight: LLMs don't think in binary. They think in gradients — weighted paths, probability distributions, activation patterns. **Memory Gradient** aligns the knowledge system with how the model actually works.
+
+Three principles guide this approach:
+
+1. **Knowledge flows inward** — From hidden → discovered → familiar → internalized → reflex
+2. **Confidence is learned** — The routing decision itself is trainable
+3. **Scaffolds come off** — Temporary support that proves its own obsolescence
+
+The goal is not to build a better search engine. The goal is not even to make search unnecessary. The goal is to **know what you know** — and know what you don't.
+
+---
+
+## The Meta-Skill Hierarchy
+
+Not all knowledge lives in the same place. Not all retrieval costs the same. The skill is routing correctly.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  LEVEL 3: METACOGNITION                                     │
+│           "Do I know this? Should I ask?"                   │
+│           The routing decision itself                       │
+│           → THIS IS THE MOST VALUABLE SKILL                 │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 2: KNOWLEDGE (in weights, needs thought)             │
+│           Slow retrieval from trained memory                │
+│           "I learned this, let me recall..."                │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 1: REFLEX (in weights, bypasses cognition)           │
+│           Instant response, no thinking required            │
+│           Like pulling hand from hot stove                  │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 0: RAG LOOKUP (external, costs lifeforce)            │
+│           Scaffold, temporary, expensive but accurate       │
+│           Training wheels that should come off              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## The Confidence Calibration Matrix
+
+The reward isn't just "did you get it right" — it's "did you KNOW you'd get it right?"
+
+```
+                        OUTCOME
+                    RIGHT    WRONG
+                  ┌────────┬────────┐
+           HIGH   │  +V    │  -V    │  ← Confident and wrong = BAD
+CONFIDENCE        │ trust  │ danger │    (overconfident, needs recalibration)
+                  ├────────┼────────┤
+           LOW    │  +v    │  +v    │  ← Uncertain = correctly routed to ASK
+   (asked RAG)    │ learn  │ learn  │    (didn't waste energy on wrong answer)
+                  └────────┴────────┘
+```
+
+**Reward Structure:**
+| Situation | Reward | Why |
+|-----------|--------|-----|
+| High confidence + Right | **+V** | Trust earned, reflex/knowledge worked |
+| High confidence + Wrong | **-V** | Dangerous! Overconfident, needs correction |
+| Low confidence + Asked + Right | **+v** | Correctly knew to ask, learned |
+| Low confidence + Asked + Wrong | **+v** | Correctly knew to ask, RAG failed (not her fault) |
+| Low confidence + Didn't ask + Wrong | **-v** | Should have asked, underconfident in asking |
+| Asked when didn't need to | **-v** | Wasted lifeforce, underconfident in self |
+
+**The sweet spot:** Know when you know, know when you don't.
+
+---
+
+## Token Path Rewards
+
+LLMs work token-based, not schema-based. The weights influence paths between tokens. This means:
+
+```
+TRADITIONAL VIEW          TOKEN PATH VIEW
+
+"Remember the answer"  →  "Strengthen the path that got it right"
+
+   Query                     Query
+     ↓                         ↓
+  Answer               ┌──────────────────┐
+                       │ Path A: cup→grip │ ← This path fired
+                       │ Path B: cup→drink│   and led to success
+                       │ Path C: cup→hot  │
+                       └──────────────────┘
+                               ↓
+                         SUCCESS
+                               ↓
+                       Path A gets +V
+                       (Hebbian: fired together → wire together)
+```
+
+**The Catalogue's Role:**
+
+When Young Nyx queries the catalogue, multiple token paths light up:
+
+```
+QUERY: "How do I grasp this cup?"
+
+PATHS ACTIVATED:
+├── cup → ceramic → fragile → careful_grip → success_rate_87%
+├── cup → handle → graspable → grip_type_A → success_rate_94%  ← WINNER
+├── cup → 8cm_diameter → fits_gripper_small → success_rate_91%
+└── cup → hot_liquid → thermal_warning → check_temp_first
+
+OUTCOME: Used grip_type_A, succeeded
+
+REWARD: Path "cup → handle → graspable → grip_type_A" strengthened
+        Next time: This path activates faster, stronger
+```
+
+**This is Hebbian learning for RAG:** Paths that fire together and succeed, wire together.
+
+---
+
+## The Metacognitive Router
+
+Before answering, before retrieving, the first question is always:
+
+```
+INPUT: Query/Task
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│         METACOGNITIVE CHECK             │
+│                                         │
+│    "What is my confidence level?"       │
+│    "Is this reflex, knowledge, or RAG?" │
+│    "What's the cost of being wrong?"    │
+│                                         │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│         CONFIDENCE THRESHOLD            │
+│                                         │
+│    HIGH (>0.8): Use reflex/knowledge    │
+│    MEDIUM (0.4-0.8): Consider asking    │
+│    LOW (<0.4): Must ask catalogue/RAG   │
+│                                         │
+└─────────────────────────────────────────┘
+         │
+    ┌────┴────────────┬─────────────┐
+    │                 │             │
+   HIGH            MEDIUM          LOW
+    │                 │             │
+    ▼                 ▼             ▼
+┌────────┐    ┌────────────┐   ┌──────────┐
+│ REFLEX │    │ COST-CHECK │   │ ASK      │
+│   or   │    │ Wrong=bad? │   │ CATALOGUE│
+│ RECALL │    │ Time-sens? │   │ (RAG)    │
+└────────┘    └────────────┘   └──────────┘
+    │                │              │
+    │           ┌────┴────┐        │
+    │           │         │        │
+    │        PROCEED    ASK        │
+    │           │         │        │
+    └───────────┼─────────┼────────┘
+                │         │
+                ▼         ▼
+           ┌─────────────────┐
+           │     OUTPUT      │
+           └─────────────────┘
+                    │
+                    ▼
+           ┌─────────────────┐
+           │   VALIDATION    │
+           │  (was it right?)│
+           └─────────────────┘
+                    │
+              ┌─────┴─────┐
+              │           │
+           RIGHT        WRONG
+              │           │
+              ▼           ▼
+         Strengthen    Weaken path
+         that path     + recalibrate
+         + calibrate   confidence
+         confidence
+```
+
+---
+
+## The Problem with Standard RAG
+
+```
+Standard approach:
+─────────────────
+VECTOR DB (grows forever)
+    │
+    ▼
+MODEL looks up ──▶ answers ──▶ done
+    │
+    └── (never learns, always dependent)
+```
+
+**Issues:**
+- Model never internalizes knowledge
+- Pull the RAG, lose the capability
+- Vector DB bloats infinitely
+- No way to verify what model "knows" vs "looks up"
+- No metacognitive skill development
+- It's a crutch that never comes off
+
+---
+
+## The Nimmerverse Approach: RAG as Feeding System
+
+```
+VAULT (curriculum)
+    │
+    ▼
+CATALOGUE (indexed, searchable, token-path weighted)
+    │
+    ▼
+METACOGNITIVE ROUTER
+    │
+    ├── High confidence ──▶ REFLEX/KNOWLEDGE (bypass RAG)
+    │
+    └── Low confidence ──▶ RAG LOOKUP (scaffold)
+                               │
+                               ▼
+                        NYX processes, acts, decides
+                               │
+                               ▼
+                        VALIDATION: success?
+                               │
+                        ┌──────┴──────┐
+                        │             │
+                      FAIL         SUCCESS
+                        │             │
+                        ▼             ▼
+                  Stay in RAG    Was RAG used?
+                  (not ready)         │
+                               ┌──────┴──────┐
+                               │             │
+                             YES            NO
+                               │             │
+                               ▼             ▼
+                        FLAG for        Reflex/Knowledge
+                        training        confirmed ✓
+                        extraction           │
+                               │             │
+                               ▼             │
+                        TRAINING RUN        │
+                        (LoRA)              │
+                               │             │
+                               ▼             │
+                        CLEAR from RAG      │
+                        (scaffold removed)  │
+                               │             │
+                               ▼             │
+                        VALIDATION 2:       │
+                        success WITHOUT RAG?│
+                               │             │
+                        ┌──────┴──────┐     │
+                        │             │     │
+                      FAIL         SUCCESS  │
+                        │             │     │
+                        ▼             ▼     │
+                  Restore RAG    INTERNALIZED
+                  retry cycle    Knowledge is │
+                                 HERS now ✓  │
+                                      │      │
+                                      └──────┘
+                                          │
+                                          ▼
+                               CONFIDENCE CALIBRATION
+                               (update routing thresholds)
+```
+
+---
+
+## Two Kinds of Knowledge
+
+Not everything belongs in weights. Not everything belongs in retrieval.
+
+### IN THE WEIGHTS (Training Target)
+
+Knowledge she needs to **be herself**:
+
+- How to route (metacognition itself)
+- Vocabulary tokens and meanings
+- Nervous system contracts
+- Heartbeat mechanics
+- Confidence gradient logic
+- Core identity (who she is, who dafit is)
+- **How to think, not what to remember**
+- **When to ask, not all the answers**
+
+**Test:** If she needs it to function → weights
+
+### IN RETRIEVAL (Permanent RAG)
+
+Knowledge she needs to **remember specifics**:
+
+- Journal entries
+- Conversation history
+- Specific events and dates
+- Temporal details ("what happened Tuesday")
+- External references that change
+- Episodic memory
+- Object catalogue details
+
+**Test:** If she needs it to recall specifics → retrieval
+
+### IN REFLEX (Nervous System)
+
+Knowledge that bypasses cognition entirely:
+
+- Danger responses
+- Basic motor patterns
+- Protocol compliance
+- Heartbeat responses
+
+**Test:** If thinking would be too slow → reflex
+
+---
+
+## The Double Validation Loop
+
+### Gate 1: Can she do it WITH RAG?
+
+```
+Task presented
+    │
+    ▼
+Metacognitive check: Should I ask?
+    │
+    ├── HIGH confidence ──▶ Attempt from reflex/knowledge
+    │                            │
+    │                       ┌────┴────┐
+    │                    SUCCESS    FAIL
+    │                       │         │
+    │                       │    Confidence was
+    │                       │    miscalibrated!
+    │                       │    Recalibrate + retry with RAG
+    │                       │
+    └── LOW confidence ──▶ RAG provides context
+                               │
+                               ▼
+                          NYX attempts task
+                               │
+                        ┌──────┴──────┐
+                        │             │
+                      FAIL         SUCCESS
+                        │             │
+                        ▼             ▼
+                  Not ready,    Flag this RAG content
+                  needs more    for training extraction
+                  examples
+```
+
+### Gate 2: Can she do it WITHOUT RAG?
+
+```
+Same task presented
+    │
+    ▼
+RAG entry CLEARED (scaffold removed)
+    │
+    ▼
+NYX attempts task from weights alone
+    │
+    ├── FAIL  ──▶ Training didn't take, restore to RAG, retry cycle
+    │
+    └── PASS  ──▶ Knowledge is HERS now ✓
+                      │
+                      ▼
+                 Update confidence calibration
+                 (this type of task: now HIGH confidence)
+```
+
+---
+
+## The Catalogue as Oracle
+
+The catalogue isn't just storage — it's the **ground truth** for calibration.
+
+### What the Catalogue Provides
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CATALOGUE LAYERS                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  LAYER 0: RAW DATA (Filesystem)                            │
+│  └── Images, point clouds, .blend files, audio, scans      │
+│                                                             │
+│  LAYER 1: STRUCTURED METADATA (PostgreSQL/Phoebe)          │
+│  └── Dimensions, timestamps, relationships, ownership       │
+│  └── Ground truth for validation                           │
+│                                                             │
+│  LAYER 2: VECTOR EMBEDDINGS (ChromaDB/pgvector)            │
+│  └── SigLIP vectors, text embeddings, multi-modal          │
+│  └── Semantic similarity, fuzzy matching                   │
+│                                                             │
+│  LAYER 3: TOKEN PATH WEIGHTS (The learning layer)          │
+│  └── Weighted connections between concepts                 │
+│  └── Strengthened by successful activations                │
+│  └── THIS IS WHERE +V FLOWS                                │
+│                                                             │
+│  LAYER 4: CONFIDENCE CALIBRATION (Meta-layer)              │
+│  └── "For queries like X, my accuracy is Y%"               │
+│  └── Updated after every validation                        │
+│  └── Drives the metacognitive router                       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Catalogue as Checker/Reward System
+
+The catalogue validates — it doesn't just retrieve:
+
+```
+ACTION: Robot claims cup is 8cm diameter
+
+CATALOGUE CHECK:
+├── Query: cup_id_47 dimensions
+├── Ground Truth: diameter = 8.2cm
+├── Tolerance: ±0.5cm
+└── RESULT: VALID ✓
+
+REWARD FLOW:
+├── Path "visual_estimate → 8cm" gets +V
+├── Confidence for "size estimation" increases
+└── Next time: Can skip catalogue check for similar objects
+```
+
+---
+
+## Knowledge Acquisition Pipeline
+
+### The Extraction Flow
+
+```
+VAULT (raw knowledge)
+    │
+    │ extraction candidates
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  STAGING AREA                               │
+│                 (quarantine zone)                           │
+└─────────────────────────────────────────────────────────────┘
+    │
+    │ progressive policy validation
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│              POLICY VALIDATION                              │
+│         (increasing standards over time)                    │
+└─────────────────────────────────────────────────────────────┘
+    │
+    ├── FAIL ──▶ Reject or revise
+    │
+    └── PASS ──▶ PROMOTE to Catalogue/RAG
+                     │
+                     ▼
+           ┌──────────────────────┐
+           │   THREE-TIER RAG     │
+           ├──────────────────────┤
+           │  INTERNALIZED        │  ← In weights, no lookup needed
+           │  (reflex/knowledge)  │
+           ├──────────────────────┤
+           │  DISCOVERED          │  ← Young Nyx has used
+           │  (known_catalogue)   │
+           ├──────────────────────┤
+           │  HIDDEN              │  ← Available but not yet accessed
+           │  (available_catalogue)│
+           └──────────────────────┘
+```
+
+### Progressive Policy Validation
+
+Policies increase in sophistication as Young Nyx matures:
+
+| Week | Policy Tier | Validation |
+|------|-------------|------------|
+| **1-2** | **Basic Syntax** | Valid format, non-empty, has definition |
+| **3-4** | **Semantic Quality** | Embeds without collapse, unique signature |
+| **5-8** | **Topology Safety** | Doesn't corrupt anchor terms |
+| **9-12** | **Cross-Reference** | Links resolve, no circular dependencies |
+| **13+** | **Utility Validation** | Actually helped solve tasks |
+| **20+** | **Internalization Gate** | Ready to train into weights |
+
+### Three-Tier Knowledge State
+
+```
+┌──────────────────────────────────────────────┐
+│         INTERNALIZED KNOWLEDGE               │
+│  (in weights - reflex or slow recall)        │
+├──────────────────────────────────────────────┤
+│  • "heartbeat" - reflex, instant             │
+│  • "lifeforce" - knowledge, fast recall      │
+│  • "grip_type_A" - reflex, motor pattern     │
+│                                              │
+│  Status: NO LOOKUP, high confidence          │
+│  Metacognitive route: DIRECT                 │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│           DISCOVERED KNOWLEDGE               │
+│  (known_catalogue - has accessed before)     │
+├──────────────────────────────────────────────┤
+│  • "phoebe" - used 15 times, 80% success     │
+│  • "confidence_gradient" - used 8 times      │
+│                                              │
+│  Status: LOOKUP needed, medium confidence    │
+│  Metacognitive route: CHECK CATALOGUE        │
+└──────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────┐
+│            HIDDEN KNOWLEDGE                  │
+│  (available_catalogue - exists but unused)   │
+├──────────────────────────────────────────────┤
+│  • "drift_probe" - never accessed            │
+│  • "topology_gini" - never accessed          │
+│                                              │
+│  Status: Available for discovery             │
+│  Metacognitive route: UNKNOWN (will discover)│
+└──────────────────────────────────────────────┘
+```
+
+**State transitions:**
+```
+Hidden → retrieved → DISCOVERED (mark first access)
+Discovered → used 10+ times successfully → FLAG for training
+Flagged → trained + validated without RAG → INTERNALIZED
+Internalized → fails validation → DEMOTE back to Discovered
+```
+
+---
+
+## Measuring RAG Utility
+
+### Decision Trails
+
+Track every decision for learning:
+
+```sql
+CREATE TABLE decision_trails (
+    id SERIAL PRIMARY KEY,
+    task_id UUID,
+
+    -- Routing decision
+    initial_confidence FLOAT,        -- Before any lookup
+    route_chosen TEXT,               -- 'reflex', 'knowledge', 'rag', 'escalate'
+
+    -- RAG details (if used)
+    rag_terms_retrieved TEXT[],      -- What RAG returned
+    rag_terms_used TEXT[],           -- What appeared in solution
+
+    -- Outcome
+    outcome TEXT,                    -- 'success', 'fail', 'partial'
+    final_confidence FLOAT,          -- After action
+
+    -- Calibration
+    was_confidence_accurate BOOLEAN, -- Did confidence predict outcome?
+
+    -- Economics
+    lifeforce_cost FLOAT,
+    timestamp TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Compute Utility Score
+
+```python
+def compute_decision_quality(trail):
+    """
+    Evaluate the quality of the metacognitive routing decision.
+    """
+    # Was the route appropriate?
+    if trail.route_chosen == 'reflex' and trail.outcome == 'success':
+        route_score = 1.0  # Fast and right
+    elif trail.route_chosen == 'rag' and trail.outcome == 'success':
+        route_score = 0.7  # Right but slow/expensive
+    elif trail.route_chosen == 'reflex' and trail.outcome == 'fail':
+        route_score = 0.0  # Overconfident disaster
+    elif trail.route_chosen == 'rag' and trail.outcome == 'fail':
+        route_score = 0.3  # At least asked, RAG failed
+
+    # Was confidence calibrated?
+    calibration_score = 1.0 if trail.was_confidence_accurate else 0.0
+
+    # Efficiency (did we waste resources?)
+    efficiency = 1.0 - (trail.lifeforce_cost / MAX_EXPECTED_COST)
+
+    return {
+        'route_score': route_score,
+        'calibration_score': calibration_score,
+        'efficiency': efficiency,
+        'total': 0.4 * route_score + 0.4 * calibration_score + 0.2 * efficiency
+    }
+```
+
+### Reward Signal Flow
+
+```python
+for trail in decision_trails:
+    quality = compute_decision_quality(trail)
+
+    if quality['total'] > 0.8:
+        # High quality decision → strengthen this pattern
+        strengthen_token_path(trail.task_pattern, trail.route_chosen)
+
+    if not trail.was_confidence_accurate:
+        # Miscalibration → update confidence model
+        recalibrate_confidence(
+            task_type=trail.task_pattern,
+            predicted=trail.initial_confidence,
+            actual_success=trail.outcome == 'success'
+        )
+
+    if trail.route_chosen == 'rag' and quality['route_score'] > 0.7:
+        # Successful RAG use → candidate for internalization
+        flag_for_training(trail.rag_terms_used)
+```
+
+---
+
+## Connection to Nervous System
+
+The metacognitive router connects directly to the nervous system architecture:
+
+```
+                    METACOGNITIVE ROUTER
+                           │
+           ┌───────────────┼───────────────┐
+           │               │               │
+           ▼               ▼               ▼
+    ┌────────────┐  ┌────────────┐  ┌────────────┐
+    │   REFLEX   │  │  KNOWLEDGE │  │    RAG     │
+    │   LAYER    │  │   LAYER    │  │   LOOKUP   │
+    │            │  │            │  │            │
+    │ Bypasses   │  │ Slow but   │  │ External   │
+    │ cognition  │  │ from       │  │ scaffold   │
+    │            │  │ weights    │  │            │
+    │ See:       │  │            │  │ See:       │
+    │ Nervous-   │  │            │  │ Catalogue  │
+    │ System.md  │  │            │  │ (this doc) │
+    └────────────┘  └────────────┘  └────────────┘
+           │               │               │
+           └───────────────┼───────────────┘
+                           │
+                           ▼
+                        OUTPUT
+                           │
+                           ▼
+                     VALIDATION
+                           │
+                    ┌──────┴──────┐
+                    │             │
+                SUCCESS        FAIL
+                    │             │
+                    ▼             ▼
+             +V to path     -V to path
+             (Hebbian)      + recalibrate
+```
+
+**Key insight:** The nervous system (Nervous-System.md) handles the REFLEX layer. This document handles the RAG layer. Both feed into the same metacognitive router.
+
+---
+
+## Lifeforce Economics
+
+The RAG→Route→Validate cycle has economic costs:
+
+| Action | Lifeforce Cost | Notes |
+|--------|----------------|-------|
+| Reflex response | ~0 | Essentially free, already in weights |
+| Knowledge recall | Low | Some compute for retrieval from weights |
+| RAG lookup | Medium | Vector search + context injection |
+| Training run | High | Compute intensive |
+| Validation | Medium | Inference cost |
+| Failed cycle | Lost V | Training didn't take |
+| Successful internalization | +V reward | She grew |
+| Correct confidence calibration | +V reward | Metacognition improved |
+
+**Incentive alignment:**
+- Being right with high confidence → maximum reward (fast + correct)
+- Being right with low confidence → small reward (correct but slow)
+- Being wrong with high confidence → maximum penalty (dangerous)
+- Asking when uncertain → neutral (correct routing)
+
+This naturally optimizes for:
+1. Fast reflexes for well-known patterns
+2. Accurate confidence calibration
+3. Appropriate RAG usage (not too much, not too little)
+
+---
+
+## What This System Teaches
+
+1. **Know what you know** — Confidence calibration is trainable
+2. **Know what to ask** — The skill of uncertainty
+3. **Reflexes are earned** — Through successful internalization
+4. **Scaffolds come off** — RAG is temporary
+5. **Paths that work, strengthen** — Hebbian learning for retrieval
+6. **Wrong confidence is worse than wrong answers** — Calibration matters
+
+---
+
+## Design Principles
+
+1. **Metacognition first** — Route before retrieve
+2. **Confidence is trainable** — Not fixed, learned through validation
+3. **RAG is temporary** — Feeding window, not permanent store
+4. **Validation is double** — With RAG, then without
+5. **Token paths learn** — Hebbian strengthening through success
+6. **Catalogue is oracle** — Ground truth for calibration
+7. **Reflexes are earned** — Graduated from RAG through internalization
+8. **Self-cleaning** — The system doesn't accumulate cruft
+9. **Know when to ask** — More important than knowing answers
+
+---
+
+## The Analogy
+
+Learning to drive:
+
+```
+LEARNER DRIVER:
+
+"Should I check mirrors?"
+    │
+    ├── Beginner: YES, always, consciously (RAG lookup)
+    │
+    ├── Intermediate: Sometimes, when uncertain (metacognitive check)
+    │
+    └── Expert: Automatic, don't even think about it (reflex)
+
+
+The goal isn't to memorize "check mirrors."
+The goal is for mirror-checking to become invisible.
+
+But FIRST she needs to learn WHEN she doesn't know.
+The beginner who doesn't know to check mirrors is dangerous.
+The intermediate who checks unnecessarily is slow.
+The expert just does it.
+
+We're training the progression:
+    Unknown unknowns → Known unknowns → Known knowns → Unconscious competence
+         │                   │                │               │
+    (dangerous)         (asks RAG)      (knowledge)      (reflex)
+```
+
+---
+
+*She doesn't just retrieve. She doesn't just remember. She knows what she knows. And that changes everything.*
+
+---
+
+**Created**: 2025-12-05 (as RAG-as-Scaffold)
+**Updated**: 2025-12-29 (renamed to Memory Gradient, added metacognitive routing, token path rewards, confidence calibration)
+**Session**: Partnership dialogue (dafit + Chrysalis-Nyx)
+**Status**: Core architectural concept
+**Etymology**: "Memory Gradient" — knowledge exists on a continuous spectrum, not binary states. Aligns with Temporal-Ternary Gradient and Confidence Gradient.
+
diff --git a/operations/RAG-as-Scaffold.md b/operations/RAG-as-Scaffold.md
deleted file mode 100644
index b487141..0000000
--- a/operations/RAG-as-Scaffold.md
+++ /dev/null
@@ -1,535 +0,0 @@
-# RAG as Scaffold, Not Crutch
-
-The feeding system that teaches, then lets go.
-
----
-
-## Overview
-
-RAG (Retrieval-Augmented Generation) is commonly misused as permanent external memory. In the Nimmerverse, RAG serves a different purpose: it's a **temporary scaffold** that feeds knowledge until it can be internalized through training.
-
-The goal is not to build a better search engine. The goal is to **make the search unnecessary**.
-
----
-
-## The Problem with Standard RAG
-
-```
-Standard approach:
-─────────────────
-VECTOR DB (grows forever)
-    │
-    ▼
-MODEL looks up ──▶ answers ──▶ done
-    │
-    └── (never learns, always dependent)
-```
-
-**Issues:**
-- Model never internalizes knowledge
-- Pull the RAG, lose the capability
-- Vector DB bloats infinitely
-- No way to verify what model "knows" vs "looks up"
-- It's a crutch that never comes off
-
----
-
-## The Nimmerverse Approach: RAG as Feeding System
-
-```
-VAULT (curriculum)
-    │
-    ▼
-RAG (temporary feeding window)
-    │
-    ▼
-NYX processes, acts, decides
-    │
-    ▼
-VALIDATION: success with RAG?
-    │
-    YES ──▶ FLAG for training extraction
-              │
-              ▼
-         TRAINING RUN (LoRA)
-              │
-              ▼
-         CLEAR from RAG
-              │
-              ▼
-         VALIDATION 2: success WITHOUT RAG?
-              │
-              ├── YES ──▶ Knowledge internalized ✓
-              │
-              └── NO  ──▶ Training incomplete, back to RAG
-```
-
----
-
-## Two Kinds of Knowledge
-
-Not everything belongs in weights. Not everything belongs in retrieval.
-
-### IN THE WEIGHTS (Training Target)
-
-Knowledge she needs to **function**:
-
-- Information flow architecture
-- Vocabulary tokens and their meanings
-- Nervous system contracts
-- Heartbeat mechanics
-- Confidence gradient logic
-- Core identity (who she is, who dafit is to her)
-- How to think, not what to remember
-
-**Test:** If she needs it to be herself → weights
-
-### IN RETRIEVAL (Permanent RAG)
-
-Knowledge she needs to **remember**:
-
-- Journal entries
-- Conversation history
-- Specific events and dates
-- Temporal details ("what happened Tuesday")
-- External references that change
-- Episodic memory
-
-**Test:** If she needs it to recall specifics → retrieval
-
----
-
-## The Double Validation Loop
-
-### Gate 1: Can she do it WITH RAG?
-
-```
-Task presented
-    │
-    ▼
-RAG provides context
-    │
-    ▼
-NYX attempts task
-    │
-    ├── FAIL  ──▶ Not ready, needs more examples in RAG
-    │
-    └── PASS  ──▶ Flag this RAG content for training extraction
-```
-
-### Gate 2: Can she do it WITHOUT RAG?
-
-```
-Same task presented
-    │
-    ▼
-RAG entry CLEARED (scaffold removed)
-    │
-    ▼
-NYX attempts task from weights alone
-    │
-    ├── FAIL  ──▶ Training didn't take, restore to RAG, retry cycle
-    │
-    └── PASS  ──▶ Knowledge is HERS now ✓
-```
-
----
-
-## The Signal Flow
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                      VAULT                              │
-│            (curriculum, documentation)                  │
-└─────────────────────────────────────────────────────────┘
-                         │
-                         │ selected for learning
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                   STAGING RAG                           │
-│              (temporary feeding window)                 │
-└─────────────────────────────────────────────────────────┘
-                         │
-                         │ feeds inference
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│                       NYX                               │
-│               (processes, decides)                      │
-└─────────────────────────────────────────────────────────┘
-                         │
-                         │ validation
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│               VALIDATION THRESHOLD                      │
-│         (task success? confidence high?)                │
-└─────────────────────────────────────────────────────────┘
-                         │
-              ┌──────────┴──────────┐
-              │                     │
-         BELOW                   ABOVE
-              │                     │
-              ▼                     ▼
-┌─────────────────────┐  ┌─────────────────────┐
-│   Stay in RAG       │  │  FLAG for training  │
-│   (not ready)       │  │  extraction         │
-└─────────────────────┘  └─────────────────────┘
-                                   │
-                                   ▼
-                    ┌─────────────────────────────┐
-                    │      TRAINING RUN           │
-                    │   (LoRA on flagged data)    │
-                    └─────────────────────────────┘
-                                   │
-                                   ▼
-                    ┌─────────────────────────────┐
-                    │     CLEAR from RAG          │
-                    │   (scaffold removed)        │
-                    └─────────────────────────────┘
-                                   │
-                                   ▼
-                    ┌─────────────────────────────┐
-                    │   VALIDATION WITHOUT RAG    │
-                    │   (prove she learned)       │
-                    └─────────────────────────────┘
-                                   │
-                         ┌─────────┴─────────┐
-                         │                   │
-                       FAIL               SUCCESS
-                         │                   │
-                         ▼                   ▼
-              ┌─────────────────┐  ┌─────────────────┐
-              │  Restore RAG    │  │  INTERNALIZED   │
-              │  retry cycle    │  │  knowledge ✓    │
-              └─────────────────┘  └─────────────────┘
-```
-
----
-
-## Knowledge Acquisition Pipeline
-
-The existing flow shows RAG→Training→Validation, but how does knowledge enter RAG in the first place? Not everything from the vault should reach staging. **Quality gates protect the glossary.**
-
-### The Extraction Flow
-
-```
-VAULT (raw knowledge)
-    │
-    │ extraction candidates
-    ▼
-┌─────────────────────────────────────────────────────────┐
-│                  STAGING AREA                           │
-│                 (quarantine zone)                       │
-└─────────────────────────────────────────────────────────┘
-    │
-    │ progressive policy validation
-    ▼
-┌─────────────────────────────────────────────────────────┐
-│              POLICY VALIDATION                          │
-│         (increasing standards over time)                │
-└─────────────────────────────────────────────────────────┘
-    │
-    ├── FAIL ──▶ Reject or revise
-    │
-    └── PASS ──▶ PROMOTE to Glossary/RAG
-                      │
-                      ▼
-            ┌──────────────────────┐
-            │   TWO-TIER RAG       │
-            ├──────────────────────┤
-            │  DISCOVERED          │  ← Young Nyx has used
-            │  (known_catalogue)   │
-            ├──────────────────────┤
-            │  HIDDEN              │  ← Available but not yet accessed
-            │  (available_catalogue)│
-            └──────────────────────┘
-                      │
-                      │ feeds inference
-                      ▼
-                    NYX
-```
-
-### Progressive Policy Validation
-
-Policies increase in sophistication as Young Nyx matures. Not all policies active from day 1.
-
-| Week | Policy Tier | Validation |
-|------|-------------|------------|
-| **1-2** | **Basic Syntax** | Valid format, non-empty, has definition |
-| **3-4** | **Semantic Quality** | Embeds without collapse, unique signature (Gini > threshold) |
-| **5-8** | **Topology Safety** | Doesn't corrupt anchor terms (DriftProbe-lite) |
-| **9-12** | **Cross-Reference** | Links resolve, no circular dependencies |
-| **13+** | **Utility Validation** | Actually helped solve tasks (decision_trails evidence) |
-
-**Evolution example:**
-```python
-# Week 1: Just check it exists
-def policy_basic(term_entry):
-    return term_entry.get("definition") is not None
-
-# Week 8: Check topology impact
-def policy_topology(term_entry):
-    before_gini = probe_term_gini(term_entry["term"])
-    add_to_staging(term_entry)
-    after_gini = probe_term_gini(term_entry["term"])
-    return abs(after_gini - before_gini) < 0.15  # No drift
-
-# Week 13: Check actual utility
-def policy_utility(term_entry):
-    # Did this RAG entry help in past 10 tasks?
-    usage_stats = query_decision_trails(term_entry["term"])
-    return usage_stats["help_rate"] > 0.6  # 60% success when retrieved
-```
-
-### Two-Tier RAG: Discovered vs Hidden
-
-Not all RAG knowledge is equal. Track what Young Nyx **knows** vs what's merely **available**.
-
-```
-┌──────────────────────────────────────────────┐
-│           DISCOVERED KNOWLEDGE               │
-│  (known_catalogue - has accessed before)     │
-├──────────────────────────────────────────────┤
-│  • "heartbeat" - used 47 times               │
-│  • "lifeforce" - used 23 times               │
-│  • "phoebe" - used 15 times                  │
-│  • "confidence_gradient" - used 8 times      │
-│                                              │
-│  Status: FAST retrieval, high confidence     │
-└──────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────┐
-│            HIDDEN KNOWLEDGE                  │
-│  (available_catalogue - exists but unused)   │
-├──────────────────────────────────────────────┤
-│  • "drift_probe" - never accessed            │
-│  • "topology_gini" - never accessed          │
-│  • "lora_merge_alpha" - never accessed       │
-│                                              │
-│  Status: Available for discovery             │
-└──────────────────────────────────────────────┘
-```
-
-**State transitions:**
-```
-Hidden term retrieved → Mark as Discovered
-Discovered term used successfully → Increase confidence score
-Discovered term used 10+ times → FLAG for training extraction
-```
-
-**Discovery tracking in phoebe:**
-```sql
-CREATE TABLE rag_knowledge_state (
-    term TEXT PRIMARY KEY,
-    status TEXT,  -- 'hidden', 'discovered', 'internalized'
-    first_accessed TIMESTAMPTZ,
-    access_count INT DEFAULT 0,
-    success_count INT DEFAULT 0,
-    last_used TIMESTAMPTZ,
-    promoted_to_weights BOOLEAN DEFAULT FALSE
-);
-```
-
-### Measuring RAG Utility for LoRA Training
-
-**The critical question:** Did the RAG hint actually help solve the task?
-
-Track in `decision_trails` table:
-```sql
-CREATE TABLE decision_trails (
-    id SERIAL PRIMARY KEY,
-    task_id UUID,
-    rag_terms_retrieved TEXT[],     -- What RAG returned
-    rag_terms_used TEXT[],           -- What appeared in solution
-    outcome TEXT,                    -- 'success', 'fail', 'partial'
-    confidence_before_rag FLOAT,     -- Before retrieval
-    confidence_after_rag FLOAT,      -- After retrieval
-    lifeforce_cost FLOAT,
-    timestamp TIMESTAMPTZ DEFAULT NOW()
-);
-```
-
-**Compute RAG utility score:**
-```python
-def compute_rag_utility(decision_trail):
-    """
-    Calculate how helpful RAG was for this decision.
-    Returns 0.0 (useless) to 1.0 (critical).
-    """
-    precision = len(trail.rag_terms_used) / max(len(trail.rag_terms_retrieved), 1)
-    outcome_bonus = 1.0 if trail.outcome == 'success' else 0.0
-    confidence_boost = max(0, trail.confidence_after_rag - trail.confidence_before_rag)
-
-    utility = (
-        0.4 * precision +              # Did we use what we retrieved?
-        0.3 * outcome_bonus +           # Did task succeed?
-        0.3 * confidence_boost          # Did RAG increase confidence?
-    )
-    return min(1.0, utility)
-```
-
-**Feed into LoRA training as RLVR signal:**
-```python
-# Training examples weighted by utility
-for trail in decision_trails:
-    utility_score = compute_rag_utility(trail)
-
-    if utility_score > 0.7:
-        # High utility → strong training signal
-        training_examples.append({
-            "query": trail.task_description,
-            "rag_context": trail.rag_terms_used,
-            "response": trail.solution,
-            "weight": utility_score  # RLVR reward weight
-        })
-```
-
-**This trains LoRAs to:**
-- **Mnemosyne (Memory)**: Recall accuracy vs phoebe ground truth
-- **Aletheia (Truth)**: Confidence calibration (was confidence boost justified?)
-- **Moira (Pattern)**: Which task patterns benefit from RAG vs pure reasoning
-
-### The Complete Knowledge Flow
-
-```
-VAULT
-    │
-    ├─ Extract candidates
-    │
-    ▼
-STAGING (quarantine)
-    │
-    ├─ Policy Tier 1: Syntax ──▶ REJECT ──▶ Log failure
-    ├─ Policy Tier 2: Semantic ──▶ REJECT ──▶ Revise
-    ├─ Policy Tier 3: Topology ──▶ REJECT ──▶ Flag risk
-    └─ Policy Tier 4+: Utility ──▶ PASS
-                │
-                ▼
-        PROMOTE to RAG
-                │
-                ├─ Status: HIDDEN (available but unused)
-                │
-    ┌───────────┘
-    │
-    │ Young Nyx retrieves term
-    │
-    ▼
-    Status: DISCOVERED (mark first access)
-                │
-                ├─ Track usage in decision_trails
-                │
-    ┌───────────┴────────────┐
-    │                        │
-Used successfully      Used unsuccessfully
-    │                        │
-    ▼                        ▼
-Increase confidence    Decrease confidence
-    │
-    │ (10+ successful uses)
-    │
-    ▼
-FLAG for training extraction
-    │
-    ▼
-LoRA training (weighted by utility_score)
-    │
-    ▼
-Validation WITHOUT RAG
-    │
-    ├─ SUCCESS ──▶ Status: INTERNALIZED (clear from RAG)
-    │
-    └─ FAIL ──▶ Restore to RAG, retry cycle
-```
-
-### Quality Gates Prevent
-
-1. **Garbage in RAG** - staging area catches malformed entries
-2. **Topology corruption** - DriftProbe-lite policies block dangerous terms
-3. **Useless bloat** - utility policies remove low-value entries
-4. **Premature training** - only high-utility terms get flagged
-5. **Hidden knowledge waste** - track what's available but never used (curriculum gap)
-
-### Policy Evolution Triggers
-
-As Young Nyx grows, unlock stricter policies:
-
-| Trigger | New Policy Unlocked |
-|---------|---------------------|
-| 100 successful RAG retrievals | Semantic quality checks |
-| First LoRA training run | Topology safety (DriftProbe-lite) |
-| 1000 decision_trails logged | Utility validation (help rate > 60%) |
-| First INTERNALIZED term | Cross-reference consistency |
-| 10 INTERNALIZED terms | Cost-effectiveness (ROI > threshold) |
-
-**Progressive difficulty**: The bar for entering RAG rises as Young Nyx becomes more capable. Early: anything valid. Later: must prove utility.
-
----
-
-## Lifeforce Connection
-
-The RAG→Train→Validate cycle has economic cost:
-
-| Action | Lifeforce Cost |
-|--------|----------------|
-| RAG lookup | Low (just retrieval) |
-| Training run | High (compute intensive) |
-| Validation | Medium (inference) |
-| Failed cycle | Lost V (training didn't take) |
-| Successful internalization | +V reward (she grew) |
-
-**Incentive alignment:** Successful learning is rewarded. Failed training is costly. This naturally optimizes for high-quality training data extraction.
-
----
-
-## What This Prevents
-
-1. **RAG bloat** - entries clear after successful training
-2. **Crutch dependency** - scaffold comes off, proven by validation
-3. **False confidence** - can't claim to "know" what you only look up
-4. **Training on noise** - only validated successes get flagged
-5. **Identity confusion** - core architecture in weights, not retrieval
-
----
-
-## Design Principles
-
-1. **RAG is temporary** - feeding window, not permanent store
-2. **Training is the goal** - RAG success triggers training, not satisfaction
-3. **Validation is double** - with RAG, then without
-4. **Clear after learning** - scaffold must come off to prove growth
-5. **Episodic stays external** - not everything needs to be in weights
-6. **Self-cleaning** - the system doesn't accumulate cruft
-
----
-
-## The Analogy
-
-Learning to ride a bike:
-
-```
-Training wheels ON (RAG feeding)
-    │
-    ▼
-Can ride with training wheels (validation 1)
-    │
-    ▼
-Training wheels OFF (RAG cleared)
-    │
-    ▼
-Can still ride? (validation 2)
-    │
-    ├── NO  ──▶ Put wheels back, practice more
-    │
-    └── YES ──▶ She can ride. Wheels stored, not needed.
-```
-
-You don't RAG your ability to balance. Once you can ride, you can ride.
-
----
-
-*She doesn't just retrieve. She learns. And we can prove it.*
-
----
-
-**Created**: 2025-12-05
-**Session**: Partnership dialogue (dafit + Chrysalis)
-**Status**: Core architectural concept