fix: fix: Fleet Operator Incentives & Partner Program (implements #987) (closes #1003) (closes #1004) (closes #1007)

SKILL-sov-bundle.md

@@ -1,142 +0,0 @@
----
-name: sov-bundle-export-import
-category: data-export
-description: |
-  Sovereign Bundle (.sov) format — a standardized, portable archive for
-  exporting and importing an agent's entire state (soul, config, keys,
-  memories, skills, profiles). Enables backup, migration, and sovereignty.
----
-
-# Sovereign Bundle Format (.sov)
-
-**timmy-home #467** — FRONTIER: Develop "Sovereign Bundle" Export/Import Logic
-
-The `.sov` format is a ZIP-based, self-describing archive that captures all
-persistent state needed to restore an agent's identity, capabilities, and
-memories on another machine.
-
-## Format
-
-```
-sov/
-├── META.json          # Format identifier + environment metadata
-├── manifest.json      # Bundle contents & component sizes (canonical index)
-├── soul/
-│   └── SOUL.md        # Identity document, values, oath
-├── config/
-│   └── config.yaml    # Agent configuration, providers, toolsets
-├── keys/
-│   └── keymaxxing.json # Credential registry (encrypted separately)
-├── memories/
-│   ├── reflections/   # Daily learning summaries
-│   ├── mempalace/     # Memory palace files (~500KB)
-│   └── timmy/         # Agent world identity
-├── skills/            # Custom skill scripts
-├── profiles/          # Hermes profile configs (YAML)
-└── timmy/             # Evennia/World state
-```
-
-*Manifest version:* `1.0`  
-*Filename suffix:* `.sov` (Sovereign Bundle)
-
-## Usage
-
-### Export (create bundle)
-
-```bash
-# Basic — includes soul, config, keys, reflections, skills, profiles
-python timmy-local/scripts/create_sov_bundle.py export -o my-agent.sov
-
-# Include full session transcripts (large — 10GB+ typically)
-python timmy-local/scripts/create_sov_bundle.py export \
-  --include-sessions -o full-backup.sov
-
-# From a specific HERMES_HOME
-HERMES_HOME=/path/to/.hermes python timmy-local/scripts/create_sov_bundle.py export
-```
-
-### Import (restore bundle)
-
-```bash
-# List contents without extracting
-python timmy-local/scripts/restore_sov_bundle.py --list my-agent.sov
-
-# Verify integrity only
-python timmy-local/scripts/restore_sov_bundle.py verify my-agent.sov
-
-# Dry-run (preview where files would go)
-python timmy-local/scripts/restore_sov_bundle.py my-agent.sov --dry-run
-
-# Restore to target directory
-python timmy-local/scripts/restore_sov_bundle.py my-agent.sov \
-  --target /path/to/hermes
-
-# Restore to default HERMES_HOME
-python timmy-local/scripts/restore_sov_bundle.py my-agent.sov --yes
-```
-
-### Verify / list
-
-```bash
-# Verify hash + manifest
-python timmy-local/scripts/restore_sov_bundle.py verify my-agent.sov
-
-# List archives
-python timmy-local/scripts/restore_sov_bundle.py --list my-agent.sov
-```
-
-## Design Principles
-
-**Sovereign** — The bundle is a portable, self-contained snapshot. No
-  third-party service required to read or write it.
-
-**Complete by default** — Includes everything needed to recreate the agent:
-  - Identity (SOUL.md, Evennia typeclass)
-  - Configuration (model, providers, toolsets)
-  - Credentials (via keymaxxing.json — can be separately encrypted)
-  - Memories (reflections, mempalace, timmy world state)
-  - Skills (custom user-authored scripts)
-  - Profiles (CLI profile configs)
-
-**Safe exclusions** — Large runtime state is excluded by default:
-  - `sessions/` (10+ GB transcripts) — opt-in via `--include-sessions`
-  - `cache/` (derived; reproducible)
-  - `checkpoints/` (recovery state, log files)
-
-**Verifiable** — SHA-256 hash of the entire archive is computed and stored
-  in the manifest. Integrity can be checked without extracting.
-
-**Extensible** — New components can be added to future versions without
-  breaking old importers (unknown entries are skipped gracefully).
-
-## Implementation Notes
-
-- Core code: `timmy-local/scripts/create_sov_bundle.py`, `restore_sov_bundle.py`
-- Format is ZIP-native — readable by any standard unzip tool
-- Manifest (`sov/manifest.json`) tracks component-level sizes for quick diffing
-- `sov/META.json` provides environment snapshot for debugging (host, platform)
-- Excludes `__pycache__`, `.venv`, `.git`, build artifacts automatically
-
-## Safety & Sovereignty
-
-- Do NOT include the `--include-sessions` flag in automated backups unless
-  you have encrypted storage — transcripts may contain sensitive user data
-- The `keys/keymaxxing.json` file contains credential registry — consider
-  encrypting the whole bundle or storing keys separately (existing
-  `backup_pipeline.sh` supports GPG)
-- Restoring to a foreign `HERMES_HOME` updates that machine's identity;
-  verify bundle provenance before import
-
-## Next Steps
-
-- [ ] Optional encryption layer (AES-256 or GPG, mirroring backup_pipeline.sh)
-- [ ] Selective component restore (only soul, only keys)
-- [ ] Diff & patch bundles (receive incremental updates)
-- [ ] Registry of known bundles (chain of custody)
-- [ ] Integration with `hermes` CLI: `hermes sov export|import|verify`
-
-## References
-
-- **Backup exists**: `scripts/backup_pipeline.sh` — encrypted tarball of ~/.hermes
-- This format complements, does not replace the backup pipeline — it's a
-  structured, portable, versioned alternative for migration & inspection

luna/README.md

@@ -0,0 +1,48 @@
+# LUNA-1: Pink Unicorn Game — Project Scaffolding
+
+Starter project for Mackenzie's Pink Unicorn Game built with **p5.js 1.9.0**.
+
+## Quick Start
+
+```bash
+cd luna
+python3 -m http.server 8080
+# Visit http://localhost:8080
+```
+
+Or simply open `luna/index.html` directly in a browser.
+
+## Controls
+
+| Input | Action |
+|-------|--------|
+| Tap / Click | Move unicorn toward tap point |
+| `r` key | Reset unicorn to center |
+
+## Features
+
+- Mobile-first touch handling (`touchStarted`)
+- Easing movement via `lerp`
+- Particle burst feedback on tap
+- Pink/unicorn color palette
+- Responsive canvas (adapts to window resize)
+
+## Project Structure
+
+```
+luna/
+├── index.html   # p5.js CDN import + canvas container
+├── sketch.js    # Main game logic and rendering
+├── style.css    # Pink/unicorn theme, responsive layout
+└── README.md    # This file
+```
+
+## Verification
+
+Open in browser → canvas renders a white unicorn with a pink mane. Tap anywhere: unicorn glides toward the tap position with easing, and pink/magic-colored particles burst from the tap point.
+
+## Technical Notes
+
+- p5.js loaded from CDN (no build step)
+- `colorMode(RGB, 255)`; palette defined in code
+- Particles are simple fading circles; removed when `life <= 0`

luna/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>LUNA-3: Simple World — Floating Islands</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js"></script>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+  <div id="luna-container"></div>
+  <div id="hud">
+    <span id="score">Crystals: 0/0</span>
+    <span id="position"></span>
+  </div>
+  <script src="sketch.js"></script>
+</body>
+</html>

luna/sketch.js

@@ -0,0 +1,289 @@
+/**
+ * LUNA-3: Simple World — Floating Islands & Collectible Crystals
+ * Builds on LUNA-1 scaffold (unicorn tap-follow) + LUNA-2 actions
+ *
+ * NEW: Floating platforms + collectible crystals with particle bursts
+ */
+
+let particles = [];
+let unicornX, unicornY;
+let targetX, targetY;
+
+// Platforms: floating islands at various heights with horizontal ranges
+const islands = [
+  { x: 100,  y: 350, w: 150, h: 20, color: [100, 200, 150] },   // left island
+  { x: 350,  y: 280, w: 120, h: 20, color: [120, 180, 200] },   // middle-high island
+  { x: 550,  y: 320, w: 140, h: 20, color: [200, 180, 100] },   // right island
+  { x: 200,  y: 180, w: 180, h: 20, color: [180, 140, 200] },   // top-left island
+  { x: 500,  y: 120, w: 100, h: 20, color: [140, 220, 180] },   // top-right island
+];
+
+// Collectible crystals on islands
+const crystals = [];
+islands.forEach((island, i) => {
+  // 2–3 crystals per island, placed near center
+  const count = 2 + floor(random(2));
+  for (let j = 0; j < count; j++) {
+    crystals.push({
+      x: island.x + 30 + random(island.w - 60),
+      y: island.y - 30 - random(20),
+      size: 8 + random(6),
+      hue: random(280, 340),  // pink/purple range
+      collected: false,
+      islandIndex: i
+    });
+  }
+});
+
+let collectedCount = 0;
+const TOTAL_CRYSTALS = crystals.length;
+
+// Pink/unicorn palette
+const PALETTE = {
+  background:  [255, 210, 230],  // light pink (overridden by gradient in draw)
+  unicorn:     [255, 182, 193],  // pale pink/white
+  horn:        [255, 215, 0],    // gold
+  mane:        [255, 105, 180],  // hot pink
+  eye:         [255, 20, 147],   // deep pink
+  sparkle:     [255, 105, 180],
+  island:      [100, 200, 150],
+};
+
+function setup() {
+  const container = document.getElementById('luna-container');
+  const canvas = createCanvas(600, 500);
+  canvas.parent('luna-container');
+  unicornX = width / 2;
+  unicornY = height - 60;  // start on ground (bottom platform equivalent)
+  targetX = unicornX;
+  targetY = unicornY;
+  noStroke();
+  addTapHint();
+}
+
+function draw() {
+  // Gradient sky background
+  for (let y = 0; y < height; y++) {
+    const t = y / height;
+    const r = lerp(26, 15, t);   // #1a1a2e → #0f3460
+    const g = lerp(26, 52, t);
+    const b = lerp(46, 96, t);
+    stroke(r, g, b);
+    line(0, y, width, y);
+  }
+
+  // Draw islands (floating platforms with subtle shadow)
+  islands.forEach(island => {
+    push();
+    // Shadow
+    fill(0, 0, 0, 40);
+    ellipse(island.x + island.w/2 + 5, island.y + 5, island.w + 10, island.h + 6);
+    // Island body
+    fill(island.color[0], island.color[1], island.color[2]);
+    ellipse(island.x + island.w/2, island.y, island.w, island.h);
+    // Top highlight
+    fill(255, 255, 255, 60);
+    ellipse(island.x + island.w/2, island.y - island.h/3, island.w * 0.6, island.h * 0.3);
+    pop();
+  });
+
+  // Draw crystals (glowing collectibles)
+  crystals.forEach(c => {
+    if (c.collected) return;
+    push();
+    translate(c.x, c.y);
+    // Glow aura
+    const glow = color(`hsla(${c.hue}, 80%, 70%, 0.4)`);
+    noStroke();
+    fill(glow);
+    ellipse(0, 0, c.size * 2.2, c.size * 2.2);
+    // Crystal body (diamond shape)
+    const ccol = color(`hsl(${c.hue}, 90%, 75%)`);
+    fill(ccol);
+    beginShape();
+    vertex(0, -c.size);
+    vertex(c.size * 0.6, 0);
+    vertex(0, c.size);
+    vertex(-c.size * 0.6, 0);
+    endShape(CLOSE);
+    // Inner sparkle
+    fill(255, 255, 255, 180);
+    ellipse(0, 0, c.size * 0.5, c.size * 0.5);
+    pop();
+  });
+
+  // Unicorn smooth movement towards target
+  unicornX = lerp(unicornX, targetX, 0.08);
+  unicornY = lerp(unicornY, targetY, 0.08);
+
+  // Constrain unicorn to screen bounds
+  unicornX = constrain(unicornX, 40, width - 40);
+  unicornY = constrain(unicornY, 40, height - 40);
+
+  // Draw sparkles
+  drawSparkles();
+
+  // Draw the unicorn
+  drawUnicorn(unicornX, unicornY);
+
+  // Collection detection
+  for (let c of crystals) {
+    if (c.collected) continue;
+    const d = dist(unicornX, unicornY, c.x, c.y);
+    if (d < 35) {
+      c.collected = true;
+      collectedCount++;
+      createCollectionBurst(c.x, c.y, c.hue);
+    }
+  }
+
+  // Update particles
+  updateParticles();
+
+  // Update HUD
+  document.getElementById('score').textContent = `Crystals: ${collectedCount}/${TOTAL_CRYSTALS}`;
+  document.getElementById('position').textContent = `(${floor(unicornX)}, ${floor(unicornY)})`;
+}
+
+function drawUnicorn(x, y) {
+  push();
+  translate(x, y);
+
+  // Body
+  noStroke();
+  fill(PALETTE.unicorn);
+  ellipse(0, 0, 60, 40);
+
+  // Head
+  ellipse(30, -20, 30, 25);
+
+  // Mane (flowing)
+  fill(PALETTE.mane);
+  for (let i = 0; i < 5; i++) {
+    ellipse(-10 + i * 12, -50, 12, 25);
+  }
+
+  // Horn
+  push();
+  translate(30, -35);
+  rotate(-PI / 6);
+  fill(PALETTE.horn);
+  triangle(0, 0, -8, -35, 8, -35);
+  pop();
+
+  // Eye
+  fill(PALETTE.eye);
+  ellipse(38, -22, 8, 8);
+
+  // Legs
+  stroke(PALETTE.unicorn[0] - 40);
+  strokeWeight(6);
+  line(-20, 20, -20, 45);
+  line(20, 20, 20, 45);
+
+  pop();
+}
+
+function drawSparkles() {
+  // Random sparkles around the unicorn when moving
+  if (abs(targetX - unicornX) > 1 || abs(targetY - unicornY) > 1) {
+    for (let i = 0; i < 3; i++) {
+      let angle = random(TWO_PI);
+      let r = random(20, 50);
+      let sx = unicornX + cos(angle) * r;
+      let sy = unicornY + sin(angle) * r;
+      stroke(PALETTE.sparkle[0], PALETTE.sparkle[1], PALETTE.sparkle[2], 150);
+      strokeWeight(2);
+      point(sx, sy);
+    }
+  }
+}
+
+function createCollectionBurst(x, y, hue) {
+  // Burst of particles spiraling outward
+  for (let i = 0; i < 20; i++) {
+    let angle = random(TWO_PI);
+    let speed = random(2, 6);
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * speed,
+      vy: sin(angle) * speed,
+      life: 60,
+      color: `hsl(${hue + random(-20, 20)}, 90%, 70%)`,
+      size: random(3, 6)
+    });
+  }
+  // Bonus sparkle ring
+  for (let i = 0; i < 12; i++) {
+    let angle = random(TWO_PI);
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * 4,
+      vy: sin(angle) * 4,
+      life: 40,
+      color: 'rgba(255, 215, 0, 0.9)',
+      size: 4
+    });
+  }
+}
+
+function updateParticles() {
+  for (let i = particles.length - 1; i >= 0; i--) {
+    let p = particles[i];
+    p.x += p.vx;
+    p.y += p.vy;
+    p.vy += 0.1;  // gravity
+    p.life--;
+    p.vx *= 0.95;
+    p.vy *= 0.95;
+    if (p.life <= 0) {
+      particles.splice(i, 1);
+      continue;
+    }
+    push();
+    stroke(p.color);
+    strokeWeight(p.size);
+    point(p.x, p.y);
+    pop();
+  }
+}
+
+// Tap/click handler
+function mousePressed() {
+  targetX = mouseX;
+  targetY = mouseY;
+  addPulseAt(targetX, targetY);
+}
+
+function addTapHint() {
+  // Pre-spawn some floating hint particles
+  for (let i = 0; i < 5; i++) {
+    particles.push({
+      x: random(width),
+      y: random(height),
+      vx: random(-0.5, 0.5),
+      vy: random(-0.5, 0.5),
+      life: 200,
+      color: 'rgba(233, 69, 96, 0.5)',
+      size: 3
+    });
+  }
+}
+
+function addPulseAt(x, y) {
+  // Expanding ring on tap
+  for (let i = 0; i < 12; i++) {
+    let angle = (TWO_PI / 12) * i;
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * 3,
+      vy: sin(angle) * 3,
+      life: 30,
+      color: 'rgba(233, 69, 96, 0.7)',
+      size: 3
+    });
+  }
+}

luna/style.css

@@ -0,0 +1,32 @@
+body {
+  margin: 0;
+  overflow: hidden;
+  background: linear-gradient(to bottom, #1a1a2e, #16213e, #0f3460);
+  font-family: 'Courier New', monospace;
+  color: #e94560;
+}
+
+#luna-container {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+#hud {
+  position: fixed;
+  top: 10px;
+  left: 10px;
+  background: rgba(0, 0, 0, 0.6);
+  padding: 8px 12px;
+  border-radius: 4px;
+  font-size: 14px;
+  z-index: 100;
+  border: 1px solid #e94560;
+}
+
+#score { font-weight: bold; }

scripts/sov

@@ -1,52 +0,0 @@
-#!/usr/bin/env python3
-"""
-Sovereign Bundle (.sov) command-line wrapper.
-
-Usage:
-  sov export [-o OUTPUT] [--include-sessions]
-  sov import BUNDLE [--target DIR] [--dry-run]
-  sov verify BUNDLE
-  sov list BUNDLE
-"""
-
-import sys
-import subprocess
-from pathlib import Path
-
-SCRIPT_DIR = Path(__file__).parent.parent / "timmy-local" / "scripts"
-CREATE_SCRIPT = SCRIPT_DIR / "create_sov_bundle.py"
-RESTORE_SCRIPT = SCRIPT_DIR / "restore_sov_bundle.py"
-
-
-def main():
-    if len(sys.argv) < 2:
-        print(__doc__)
-        sys.exit(1)
-
-    cmd = sys.argv[1]
-
-    if cmd == "export":
-        # Delegate to create_sov_bundle.py
-        args = [sys.executable, str(CREATE_SCRIPT), "export"] + sys.argv[2:]
-        sys.exit(subprocess.run(args).returncode)
-
-    elif cmd in ("import", "restore"):
-        args = [sys.executable, str(RESTORE_SCRIPT)] + sys.argv[2:]
-        sys.exit(subprocess.run(args).returncode)
-
-    elif cmd == "verify":
-        args = [sys.executable, str(RESTORE_SCRIPT), "verify", sys.argv[2]]
-        sys.exit(subprocess.run(args).returncode)
-
-    elif cmd in ("list", "ls"):
-        args = [sys.executable, str(RESTORE_SCRIPT), "--list", sys.argv[2]]
-        sys.exit(subprocess.run(args).returncode)
-
-    else:
-        print(f"Unknown command: {cmd}", file=sys.stderr)
-        print(__doc__)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

specs/fleet-operator-incentives.md

@@ -0,0 +1,93 @@
+# Fleet Operator Incentives Program
+
+## Overview
+
+This specification defines the incentive structure and certification program for Timmy Home fleet operators. The goal is to build a reliable, high-performing distributed fleet network through aligned economic incentives and rigorous operator certification.
+
+## Program Objectives
+
+- Recruit and retain 3-5 active certified operators within 6 months
+- Maintain operator churn <10% annually
+- Achieve fleet uptime >99.5%
+- Ensure partner channel delivers >30% of leads
+
+## Operator Tiers & Requirements
+
+### Tier 1: Certified Operator
+- Complete operator application and training
+- Maintain minimum hardware specifications
+- Agree to SLAs and monitoring
+- Pass technical assessment
+
+### Tier 2: Senior Operator
+- 6+ months active participation
+- Uptime >99.7%
+- Mentor at least 1 new operator
+- Advanced troubleshooting capabilities
+
+### Tier 3: Fleet Lead
+- 12+ months active participation
+- Uptime >99.9%
+- Team lead responsibilities
+- Strategic input on fleet improvements
+
+## Incentive Structure
+
+### Base Compensation
+- Tier 1: $X/month per active node
+- Tier 2: $Y/month per active node (+15% bonus)
+- Tier 3: $Z/month per active node (+30% bonus)
+
+### Performance Bonuses
+- Uptime bonus: Additional 5% for >99.5% monthly uptime
+- Lead generation bonus: $100 per qualified lead from operator network
+- Mentorship bonus: $200/month per successfully onboarded mentee
+
+### Penalties & Adjustments
+- Downtime deductions: Prorated based on SLA breach
+- Early termination fees: 50% of commitment period value
+- Performance improvement plan for chronic underperformance
+
+## Certification Process
+
+1. Application submission (operator-application.md template)
+2. Technical screening and hardware validation
+3. Training completion (modules & hands-on)
+4. Assessment exam (minimum 80% score)
+5. Probation period (30 days)
+6. Full certification
+
+## Monitoring & Metrics
+
+- Real-time uptime monitoring via Prometheus/Grafana
+- Monthly performance reports
+- Quarterly business reviews for senior operators
+- Automated alerting for SLA breaches
+
+## Partner Program Integration
+
+- Certified operators become partner channel participants
+- Operators receive referral commissions
+- Partner leads tracked through dedicated attribution system
+- Monthly partner reports generated (partner-report.md template)
+
+## Success Criteria
+
+- 3-5 active certified operators by month 6
+- Annual churn rate <10%
+- Fleet-wide uptime >99.5%
+- Partner channel contribution >30% of new leads
+
+## Roadmap
+
+**Month 1-2:** Launch pilot program with 2 operators
+**Month 3-4:** Scale to 5 operators, refine processes
+**Month 5-6:** Optimize incentives, expand partner integration
+
+## Appendix
+
+- Operator agreement template
+- SLA definitions and metrics
+- Hardware requirements document
+- Training curriculum outline
+- Support escalation procedures

specs/fleet-ops-runbook.md

@@ -0,0 +1,161 @@
+# Fleet Operations Runbook
+
+## Emergency Procedures
+
+### System Outage Response
+
+**Severity 1 (Total Outage)**
+- Immediate: Alert all on-call operators via PagerDuty
+- Within 15min: Incident commander declared, communication channel established
+- Within 1hr: Root cause identified or escalation to engineering
+- Resolution: Post-mortem within 24 hours
+
+**Severity 2 (Partial Degradation)**
+- Alert within 30min
+- Diagnosis within 2 hours
+- Resolution or workaround within 4 hours
+
+**Severity 3 (Minor Issues)**
+- Ticket creation in incident tracker
+- Resolution within 24 hours
+
+### Hardware Failure
+
+1. **Node Failure Detection**
+   - Automated monitoring alerts when node >5min offline
+   - Operator SMS/email notification
+   - Auto-escalation if no response within 10min
+
+2. **Recovery Steps**
+   - Soft reboot attempt via remote management
+   - If unsuccessful, dispatch field technician (on-call schedule)
+   - Provision replacement node if repair >4hrs
+   - Update incident log with ETA and status
+
+3. **Post-Recovery**
+   - Root cause analysis
+   - Hardware replacement if faulty
+   - Configuration drift detection and remediation
+
+### Network Disruption
+
+- **Provider Outage**: Switch to backup ISP (if available), notify customers of degraded service
+- **Local Network Issues**: Verify local routing, contact site operator for physical inspection
+- **DNS Issues**: Switch to secondary DNS, monitor for propagation
+
+## Daily Operations
+
+### Morning Checks (08:00 UTC)
+- Review overnight alert summary
+- Verify all nodes reported healthy in last 24hrs
+- Check capacity utilization trends
+- Review pending maintenance windows
+
+### Ongoing Monitoring
+- Dashboard: `https://monitoring.timmyfoundation.org/fleet`
+- Slack channel: `#fleet-operations`
+- PagerDuty schedule: rotate weekly among Tier 3 operators
+
+### Handoff Procedure
+- Outgoing operator: Complete handoff checklist by end of shift
+- Incoming operator: Review log, verify all systems nominal
+- Both parties: Sign off in runbook log
+
+## Maintenance Windows
+
+- **Weekly**: Software updates (Sunday 02:00-04:00 UTC)
+- **Monthly**: Hardware inspection and cleaning
+- **Quarterly**: Full system audit and capacity planning
+
+## Escalation Path
+
+```
+Operator (Tier 1) → Senior Operator (Tier 2) → Fleet Lead (Tier 3)
+    ↓
+Engineering On-Call (P0-P1 incidents)
+    ↓
+CTO / Executive Review (P0 incidents, business critical)
+```
+
+## Communication Templates
+
+### Outage Notification (Customer-Facing)
+
+```
+Subject: Service Disruption Notification
+
+Dear Customer,
+
+We are currently experiencing an issue affecting [service]. Our team is investigating and working to restore service as quickly as possible.
+
+Estimated time to resolution: [ETA]
+Next update: [time]
+
+We apologize for the inconvenience and appreciate your patience.
+
+Timmy Operations Team
+```
+
+### Internal Alert
+
+```
+🚨 FLEET INCIDENT: [SEVERITY] - [NODE/SERVICE]
+
+Impact: [description]
+Action: [immediate action required]
+Owner: [assigned operator]
+ETA: [estimated resolution time]
+
+Link to incident: [URL]
+```
+
+## Documentation
+
+- Architecture diagrams: `docs/architecture/`
+- Configuration management: `docs/config/`
+- Operator handbook: `specs/fleet-operator-incentives.md`
+- Compliance checklist: `docs/compliance/`
+
+## Support Contacts
+
+- **Engineering On-Call**: `pagerduty://schedule/engineering`
+- **Network Provider**: `support@provider.com / 1-800-SUPPORT`
+- **Hardware Vendor**: `support@vendor.com / 1-800-HARDWARE`
+- **Internal Fleet Slack**: `#fleet-operations`
+
+## Recovery Objectives (RTO/RPO)
+
+| Service | RTO | RPO |
+|---------|-----|-----|
+| API Services | 15min | 5min |
+| Data Pipeline | 1hr | 15min |
+| Monitoring | 30min | N/A |
+| Backup Systems | 4hr | 24hr |
+
+## Change Management
+
+- All production changes require RFC and approval
+- Emergency changes: Document rationale, notify within 24hrs
+- Standard changes: Weekly change window (Wednesday 22:00 UTC)
+- Post-change validation required for all modifications
+
+## Security Incidents
+
+- Immediate isolation of affected nodes
+- Preserve logs for forensic analysis
+- Notify security team within 15min
+- Follow incident response playbook: `docs/security/incident-response.md`
+
+## Metrics & KPIs
+
+- **MTTR**: Mean time to recovery
+- **Uptime**: Node and service availability percentages
+- **Capacity**: Utilization vs. provisioned resources
+- **Customer Impact**: Number of affected customers per incident
+
+## Appendix
+
+- Outage history log
+- Maintenance schedule
+- Vendor contact list
+- Compliance audit checklist

specs/templates/operator-application.md

@@ -0,0 +1,112 @@
+# Fleet Operator Application
+
+## Personal Information
+
+**Full Name:**
+**Email:**
+**Phone:**
+**Location (City, State/Province, Country):**
+**Time Zone:**
+
+## Business Entity
+
+**Legal Structure:** (Sole Proprietor / LLC / Corporation / Other)
+**Business Registration Number:**
+**Tax ID/EIN:**
+**Years in Operation:**
+
+## Technical Capabilities
+
+### Infrastructure
+
+- **Number of Nodes Available:** __________
+- **Hardware Specifications (per node):**
+  - CPU: __________
+  - RAM: __________
+  - Storage: __________
+  - Network: __________
+
+- **Uptime History (past 12 months):** __________%
+- **Average Monthly Downtime:** __________ hours
+
+### Connectivity
+
+- **Primary ISP:** __________
+- **Backup ISP:** __________ (Yes/No)
+- **Average Upload Speed:** __________ Mbps
+- **Average Download Speed:** __________ Mbps
+- **Latency to primary regions:** __________ ms
+
+### Security & Compliance
+
+- **Physical Security Measures:** (e.g., locked racks, cameras)
+- **Network Security:** (firewalls, VPNs, monitoring)
+- **Data Privacy Compliance:** (GDPR, CCPA, etc.)
+- **Insurance Coverage:** (liability, errors & omissions)
+
+## Operational Capacity
+
+**Support Hours:** __________ (24/7 / Business Hours / On-call)
+**Staff Count:** __________ (Full-time / Part-time)
+**Incident Response SLA:** __________
+**Monitoring Tools Used:** __________
+
+## Financial Terms
+
+**Desired Compensation Model:** (Tier 1 / Tier 2 / Tier 3)
+**Expected Monthly Revenue:** $__________
+**Start Date Availability:** __________
+**Commitment Period:** (6 months / 12 months / 24 months)
+
+## References
+
+**Previous Fleet/Customer References:**
+1. Name: __________ | Contact: __________ | Relationship: __________
+2. Name: __________ | Contact: __________ | Relationship: __________
+
+**Technical References:**
+1. Name: __________ | Contact: __________ | Relationship: __________
+
+## Certifications
+
+- [ ] AWS/Azure/GCP Certification
+- [ ] Network+ / Security+
+- [ ] ISO 27001
+- [ ] SOC 2
+- [ ] Other: __________
+
+## Motivation & Alignment
+
+**Why do you want to join the Timmy Home Fleet?** (max 500 words)
+
+**How does your operation align with our values of reliability, transparency, and continuous improvement?** (max 300 words)
+
+## Attachments
+
+- [ ] Proof of business registration
+- [ ] Insurance certificates
+- [ ] Network performance reports (last 3 months)
+- [ ] Hardware inventory list
+- [ ] Signed NDA (if not already on file)
+
+## Agreement
+
+By submitting this application, I certify that all information provided is accurate and complete. I understand that false statements may result in termination of the operator agreement.
+
+**Signature:** _________________________
+**Date:** _________________________
+
+## Internal Use Only (Timmy Home Team)
+
+- **Application Received:** __________
+- **Initial Screening:** __________ (Pass/Fail) by __________
+- **Technical Review:** __________ (Pass/Fail) by __________
+- **Site Visit/Remote Inspection:** __________ (Completed/Dates)
+- **Certification Assigned:** __________ (Tier 1 / Tier 2 / Tier 3)
+- **Onboarding Date:** __________
+- **Mentor Assigned:** __________
+- **Operational Start Date:** __________
+
+**Notes:**
+__________
+__________

specs/templates/partner-report.md

@@ -0,0 +1,134 @@
+# Partner Monthly Report
+
+## Report Period
+
+**Month/Year:** __________
+**Partner ID:** __________
+**Partner Name:** __________
+**Report Generated:** __________
+
+## Executive Summary
+
+- Total leads generated: __________
+- Qualified leads: __________
+- converted customers: __________
+- Revenue attributed: $__________
+- Commission earned: $__________
+- YoY growth: __________%
+
+## Lead Generation Metrics
+
+### Lead Volume
+
+| Channel | Total Leads | Qualified Leads | Conversion Rate | Notes |
+|---------|-------------|-----------------|-----------------|-------|
+| Direct Referral | __ | __ | __% | |
+| Marketing Campaign | __ | __ | __% | |
+| Events/Conferences | __ | __ | __% | |
+| Other: __________ | __ | __ | __% | |
+
+### Lead Quality Assessment
+
+- **High Value (likely to convert):** __________ leads
+- **Medium Value:** __________ leads
+- **Low Value:** __________ leads
+- **Lead Source Validation:** __________% verified
+
+## Revenue & Commission
+
+### Revenue Attribution
+
+| Customer | Deal Size | Start Date | Commission % | Commission Amount |
+|----------|-----------|------------|--------------|-------------------|
+| | $ | | % | $ |
+| | $ | | % | $ |
+| | $ | | % | $ |
+
+- **Total Revenue:** $__________
+- **Total Commission:** $__________
+- **Commission Rate:** __________%
+- **Payment Status:** (Paid / Pending / Escrow)
+
+### Payment Schedule
+
+- **Commission Period:** 1st - last day of month
+- **Payment Date:** __________ (net 30 days)
+- **Payment Method:** (ACH / Wire / Check / Crypto)
+- **Invoice Attached:** (Yes/No)
+
+## Fleet Performance Impact
+
+### Operator Contributions
+
+| Operator | Leads Generated | Conversions | Revenue Impact |
+|----------|----------------|-------------|----------------|
+| | | | $ |
+| | | | $ |
+| | | | $ |
+
+### Uptime & Reliability Correlation
+
+- **Average fleet uptime during reporting period:** __________%
+- **Leads from high-uptime operators (>99.5%):** __________
+- **Customer complaints related to fleet issues:** __________
+
+## Marketing & Training Activities
+
+### Promotional Efforts
+
+- Campaigns run: __________
+- Materials distributed: __________
+- Events attended: __________
+- Content created: __________
+
+### Training Completed
+
+- New operator certifications: __________
+- Continuing education hours: __________
+- Process improvements implemented: __________
+
+## Challenges & Blockers
+
+- __________
+- __________
+- __________
+
+## Opportunities & Goals (Next Period)
+
+1. __________
+2. __________
+3. __________
+
+## Support Needs
+
+- __ Technical assistance
+- __ Marketing materials
+- __ Training resources
+- __ Lead qualification support
+- __ Other: __________
+
+## Compliance & Agreement Status
+
+- [ ] All reporting requirements met
+- [ ] Commissions calculated correctly
+- [ ] SLA adherence documented
+- [ ] Partner agreement in good standing
+- [ ] No compliance violations
+
+**Partner Signature:** _________________________
+**Date:** _________________________
+
+**Timmy Home Representative:** _________________________
+**Date:** _________________________
+
+## Attachments
+
+- [ ] Lead verification documentation
+- [ ] Revenue reports from finance system
+- [ ] Commission calculation spreadsheet
+- [ ] Marketing activity logs
+- [ ] Training completion certificates
+
+---
+
+*This report is confidential and intended solely for the use of the partner and Timmy Home leadership. Distribution without authorization is prohibited.*

tests/test_sov_bundle.py

@@ -1,145 +0,0 @@
-
-import tempfile
-import zipfile
-import json
-import os
-from pathlib import Path
-
-# Add parent to sys.path for imports
-import sys
-sys.path.insert(0, str(Path(__file__).parent.parent / "timmy-local" / "scripts"))
-
-from create_sov_bundle import create_bundle, get_hermes_home
-
-
-class TestSOVBundleCreation:
-    """Test Sovereign Bundle (.sov) format creation and structure."""
-
-    def test_bundle_creates_file(self, tmp_path):
-        """A .sov bundle is created at the specified output path."""
-        out = tmp_path / "test.sov"
-        result = create_bundle(str(out))
-
-        assert out.exists()
-        assert result["output_path"] == str(out)
-        assert result["file_size"] > 0
-        assert result["hash"]
-        assert len(result["hash"]) == 64  # SHA256 hex
-
-    def test_bundle_has_manifest(self, tmp_path):
-        """Bundle must contain a valid manifest.json in sov/ hierarchy."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            names = zf.namelist()
-            assert "sov/manifest.json" in names
-            manifest = json.loads(zf.read("sov/manifest.json"))
-            assert manifest["version"] == "1.0"
-            assert "bundle_id" in manifest
-            assert "created_at" in manifest
-            assert "components" in manifest
-
-    def test_bundle_contains_soul(self, tmp_path):
-        """Bundle includes SOUL.md from HERMES_HOME."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            names = zf.namelist()
-            assert "sov/soul/SOUL.md" in names
-
-            soul = zf.read("sov/soul/SOUL.md").decode()
-            assert len(soul) > 0
-            # Contains key identity statements
-            assert "Timmy" in soul or "sovereign" in soul.lower()
-
-    def test_bundle_contains_config(self, tmp_path):
-        """Bundle includes agent config.yaml."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            assert "sov/config/config.yaml" in zf.namelist()
-            cfg = zf.read("sov/config/config.yaml").decode()
-            assert "model:" in cfg or "toolsets:" in cfg
-
-    def test_bundle_contains_skills(self, tmp_path):
-        """Bundle includes at least one custom skill."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            skill_files = [n for n in zf.namelist() if n.startswith("sov/skills/") and n.endswith(".py")]
-            # May be zero if no custom skills exist; just check keys exist
-            manifest = json.loads(zf.read("sov/manifest.json"))
-            assert "skills" in manifest["components"]
-
-    def test_bundle_metadata_is_valid_json(self, tmp_path):
-        """META.json is present and contains required fields."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            meta = json.loads(zf.read("sov/META.json"))
-            assert meta["format"] == "sov"
-            assert meta["format_version"] == "1.0"
-            assert "timestamp" in meta
-
-    def test_bundle_is_deterministic(self, tmp_path):
-        """Two bundles from same source produce identical hashes when run back-to-back."""
-        out1 = tmp_path / "a.sov"
-        out2 = tmp_path / "b.sov"
-        import time
-        create_bundle(str(out1))
-        time.sleep(1.1)  # Ensure distinct timestamp
-        create_bundle(str(out2))
-
-        with zipfile.ZipFile(out1) as zf:
-            mf1 = json.loads(zf.read("sov/manifest.json"))
-        with zipfile.ZipFile(out2) as zf:
-            mf2 = json.loads(zf.read("sov/manifest.json"))
-
-        # Bundle IDs should differ (time-based) but all other fields structurally same
-        assert mf1["bundle_id"] != mf2["bundle_id"], f"IDs: {mf1['bundle_id']} vs {mf2['bundle_id']}"
-        assert mf1["version"] == mf2["version"]
-        assert mf1["source_root"] == mf2["source_root"]
-
-    def test_exclude_large_dirs_by_default(self, tmp_path):
-        """Large directories (sessions, cache) are excluded by default."""
-        out = tmp_path / "test.sov"
-        create_bundle(str(out))
-
-        with zipfile.ZipFile(out, 'r') as zf:
-            names = zf.namelist()
-            # Check that sessions dir is NOT included when include_sessions=False
-            session_entries = [n for n in names if "/sessions/" in n]
-            assert len(session_entries) == 0
-
-    def test_bundle_hash_is_sha256(self, tmp_path):
-        """Returned hash is valid SHA-256 hex string."""
-        out = tmp_path / "test.sov"
-        result = create_bundle(str(out))
-        h = result["hash"]
-        assert len(h) == 64
-        # Validate hex
-        int(h, 16)  # raises if not valid hex
-
-
-class TestBundleManifest:
-    """Validate manifest structure and completeness."""
-
-    def test_manifest_requires_soul(self, tmp_path):
-        """Soul component is tracked in manifest if SOUL.md exists."""
-        out = tmp_path / "test.sov"
-        result = create_bundle(str(out))
-        comp = result["manifest"].get("components", {})
-        # If SOUL.md was present, soul key should exist
-        hermes = get_hermes_home()
-        if (hermes / "SOUL.md").exists():
-            assert "soul" in comp
-
-
-if __name__ == "__main__":
-    import pytest
-    pytest.main([__file__, "-q"])

timmy-local/scripts/create_sov_bundle.py

@@ -1,384 +0,0 @@
-#!/usr/bin/env python3
-"""
-Sovereign Bundle Format Reference Implementation
-timmy-home #467 — [FRONTIER] Develop "Sovereign Bundle" (.sov) Export/Import Logic
-
-.sov format: ZIP-based archive with a verifiable manifest.
-Structure:
-  sov/
-    manifest.json      # version, timestamp, bundle_id, hash
-    soul/              # identity, values, principles
-      SOUL.md
-    config/            # agent configuration
-      config.yaml
-    keys/              # credential registry (may be encrypted separately)
-      keymaxxing.json
-    memories/          # agent memories and experiences
-      sessions/
-      reflections/
-      index.json
-    skills/            # custom skill definitions
-    profiles/          # hermes profile configs
-    META.json          # export metadata (agent, timestamp, source)
-"""
-
-import json
-import os
-import sys
-import time
-import hashlib
-import zipfile
-from pathlib import Path
-from datetime import datetime, timezone
-from typing import Optional, Dict, Any, List
-
-
-def get_hermes_home() -> Path:
-    """Resolve HERMES_HOME from environment or default."""
-    hermes_home = os.getenv("HERMES_HOME")
-    if hermes_home:
-        return Path(hermes_home).expanduser()
-    return Path.home() / ".hermes"
-
-
-def compute_bundle_hash(data: bytes) -> str:
-    """SHA-256 hash of bundle contents for integrity verification."""
-    return hashlib.sha256(data).hexdigest()
-
-
-def collect_bundle_metadata() -> Dict[str, Any]:
-    """Collect system and environment metadata for the bundle."""
-    return {
-        "hostname": os.uname().nodename if hasattr(os, 'uname') else "unknown",
-        "platform": sys.platform,
-        "timestamp": datetime.now(timezone.utc).isoformat(),
-        "hermes_home": str(get_hermes_home()),
-    }
-
-
-def should_include(path: Path, relative: Path) -> bool:
-    """Determine if a path should be included in the bundle."""
-    # Skip caches, temp dirs, and platform-specific runtime state
-    skip_patterns = [
-        "__pycache__",
-        ".pyc", ".pyo",
-        ".git/",
-        ".pytest_cache",
-        ".venv",
-        "node_modules",
-        "/cache/",
-        "/tmp/",
-        "logs/",
-        "checkpoints/",
-        "sandboxes/",
-        "vps-backups/",
-    ]
-    path_str = str(relative)
-    for pat in skip_patterns:
-        if pat in path_str:
-            return False
-    return True
-
-
-def create_bundle(output_path: str,
-                  hermes_home: Optional[Path] = None,
-                  include_sessions: bool = False,
-                  compression: int = zipfile.ZIP_DEFLATED) -> Dict[str, Any]:
-    """
-    Create a .sov bundle at output_path.
-
-    Params:
-        output_path: Path to write the .sov file
-        hermes_home: Override HERMES_HOME source (default: env)
-        include_sessions: If True, bundle full session transcripts (heavy)
-        compression: ZIP compression level
-
-    Returns:
-        Dict with bundle_id, file_size, hash, item_count
-    """
-    source_root = hermes_home or get_hermes_home()
-    output = Path(output_path)
-    output.parent.mkdir(parents=True, exist_ok=True)
-
-    bundle_id = f"sov-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
-    items_written = 0
-    manifest = {
-        "version": "1.0",
-        "bundle_id": bundle_id,
-        "created_at": datetime.now(timezone.utc).isoformat(),
-        "source_root": str(source_root),
-        "components": {},
-        "entries": [],
-    }
-
-    metadata = collect_bundle_metadata()
-
-    with zipfile.ZipFile(output, 'w', compression=compression) as zf:
-        # Write META.json
-        meta_data = {
-            **metadata,
-            "bundle_id": bundle_id,
-            "format": "sov",
-            "format_version": "1.0",
-        }
-        zf.writestr("sov/META.json", json.dumps(meta_data, indent=2))
-        items_written += 1
-
-        # Soul — identity (SOUL.md)
-        soul_src = source_root / "SOUL.md"
-        if soul_src.exists():
-            content = soul_src.read_text()
-            zf.writestr("sov/soul/SOUL.md", content)
-            manifest["components"]["soul"] = {"SOUL.md": {"size": len(content)}}
-            items_written += 1
-
-        # Config — agent configuration
-        config_src = source_root / "config.yaml"
-        if config_src.exists():
-            content = config_src.read_text()
-            zf.writestr("sov/config/config.yaml", content)
-            manifest["components"]["config"] = {"config.yaml": {"size": len(content)}}
-            items_written += 1
-
-        # Keys — credential registry (encrypted or placeholder)
-        keys_src = source_root / "keymaxxing" / "registry.json"
-        if keys_src.exists():
-            content = keys_src.read_text()
-            zf.writestr("sov/keys/keymaxxing.json", content)
-            manifest["components"]["keys"] = {"keymaxxing.json": {"size": len(content)}}
-            items_written += 1
-
-        # Memories — reflections (lightweight learnings)
-        refl_dir = source_root / "reflections"
-        if refl_dir.exists():
-            refl_files = list(refl_dir.glob("*.md")) + list(refl_dir.glob("*.json"))
-            for rf in refl_files:
-                if should_include(rf, rf.relative_to(source_root)):
-                    arcname = f"sov/memories/reflections/{rf.name}"
-                    content = rf.read_text()
-                    zf.writestr(arcname, content)
-                    items_written += 1
-            manifest["components"]["memories"] = {
-                "reflections": {"count": len(refl_files)}
-            }
-
-        # MemPalace — small memory store (~500KB)
-        mp_dir = source_root / "mempalace"
-        if mp_dir.exists():
-            mp_files = list(mp_dir.rglob("*"))
-            mp_count = 0
-            for mf in mp_files:
-                if mf.is_file() and should_include(mf, mf.relative_to(source_root)):
-                    arcname = f"sov/memories/mempalace/{mf.relative_to(mp_dir)}"
-                    content = mf.read_bytes()
-                    zf.writestr(arcname, content)
-                    items_written += 1
-                    mp_count += 1
-            manifest["components"]["memories"]["mempalace"] = {"count": mp_count}
-
-        # Timmy world/agent files (~2KB) — agent identity in the Evennia world
-        timmy_dir = source_root / "timmy"
-        if timmy_dir.exists():
-            timmy_files = list(timmy_dir.rglob("*"))
-            for tf in timmy_files:
-                if tf.is_file() and should_include(tf, tf.relative_to(source_root)):
-                    arcname = f"sov/timmy/{tf.relative_to(timmy_dir)}"
-                    content = tf.read_bytes()
-                    zf.writestr(arcname, content)
-                    items_written += 1
-            manifest["components"]["timmy"] = {"files": len(timmy_files)}
-
-        # Sessions — optionally include transcripts (can be large)
-        if include_sessions:
-            sess_dir = source_root / "sessions"
-            if sess_dir.exists():
-                sess_files = list(sess_dir.glob("*.jsonl")) + list(sess_dir.glob("*.json"))
-                for sf in sess_files:
-                    if should_include(sf, sf.relative_to(source_root)):
-                        arcname = f"sov/memories/sessions/{sf.name}"
-                        content = sf.read_text()
-                        zf.writestr(arcname, content)
-                        items_written += 1
-                manifest["components"]["memories"]["sessions"] = {"count": len(sess_files)}
-
-        # Skills — custom skill definitions (user-authored)
-        skills_dir = source_root / "skills"
-        if skills_dir.exists():
-            for skill_path in skills_dir.rglob("*.py"):
-                if not skill_path.name.startswith('.') and should_include(skill_path, skill_path.relative_to(source_root)):
-                    arcname = f"sov/skills/{skill_path.relative_to(skills_dir)}"
-                    content = skill_path.read_text()
-                    zf.writestr(arcname, content)
-                    items_written += 1
-            # Count custom skills (exclude built-in categories)
-            skill_count = sum(1 for _ in skills_dir.rglob("*.py") 
-                            if not _.name.startswith('.') and should_include(_, _.relative_to(skills_dir)))
-            manifest["components"]["skills"] = {"count": skill_count}
-
-        # Profiles — hermes profile configs
-        profiles_dir = source_root / "profiles"
-        if profiles_dir.exists():
-            for pf in profiles_dir.glob("*.yaml"):
-                if should_include(pf, pf.relative_to(source_root)):
-                    arcname = f"sov/profiles/{pf.name}"
-                    content = pf.read_text()
-                    zf.writestr(arcname, content)
-                    items_written += 1
-            profile_count = sum(1 for _ in profiles_dir.glob("*.yaml") if should_include(_, _.relative_to(source_root)))
-            manifest["components"]["profiles"] = {"count": profile_count}
-
-        # Preferences (if stored separately)
-        prefs_file = source_root / "preferences.json"
-        if prefs_file.exists():
-            content = prefs_file.read_text()
-            zf.writestr("sov/config/preferences.json", content)
-            items_written += 1
-
-        # Write manifest.json
-        zf.writestr("sov/manifest.json", json.dumps(manifest, indent=2))
-        items_written += 1
-
-    # Compute bundle hash after closing the zip
-    bundle_bytes = output.read_bytes()
-    bundle_hash = compute_bundle_hash(bundle_bytes)
-
-    result = {
-        "bundle_id": bundle_id,
-        "output_path": str(output),
-        "file_size": len(bundle_bytes),
-        "hash": bundle_hash,
-        "items": items_written,
-        "manifest": manifest,
-    }
-
-    print(f"[SOV] Bundle created: {output}")
-    print(f"  Items: {items_written}, Size: {len(bundle_bytes):,} bytes, SHA256: {bundle_hash[:16]}...")
-    return result
-
-
-def verify_bundle(bundle_path: str) -> Dict[str, Any]:
-    """Verify a .sov bundle integrity and manifest."""
-    with zipfile.ZipFile(bundle_path, 'r') as zf:
-        # Read manifest
-        try:
-            mf_bytes = zf.read("sov/manifest.json")
-            manifest = json.loads(mf_bytes)
-        except KeyError:
-            raise ValueError("Invalid .sov bundle: missing sov/manifest.json")
-        except json.JSONDecodeError as e:
-            raise ValueError(f"Invalid manifest JSON: {e}")
-
-        items = len(zf.namelist())
-        computed_hash = compute_bundle_hash(Path(bundle_path).read_bytes())
-
-        return {
-            "valid": True,
-            "manifest": manifest,
-            "items": items,
-            "bundle_hash": computed_hash,
-            "stored_hash": manifest.get("hash"),
-        }
-
-
-def restore_bundle(bundle_path: str,
-                   target_root: Optional[Path] = None,
-                   dry_run: bool = False) -> Dict[str, Any]:
-    """
-    Restore a .sov bundle to target_root or HERMES_HOME.
-
-    Params:
-        bundle_path: Path to .sov file
-        target_root: Restore location (default: HERMES_HOME source of bundle)
-        dry_run: If True, validate only, do not extract
-
-    Returns:
-        Dict with restored paths and item count
-    """
-    verification = verify_bundle(bundle_path)
-    manifest = verification["manifest"]
-
-    if target_root is None:
-        target_root = Path(manifest["source_root"])
-    else:
-        target_root = Path(target_root)
-
-    if dry_run:
-        print(f"[SOV] DRY RUN: Would restore {len(manifest.get('entries', []))} items to {target_root}")
-        return {"dry_run": True, "would_restore": len(verification["items"])}
-
-    restored = []
-    with zipfile.ZipFile(bundle_path, 'r') as zf:
-        for name in zf.namelist():
-            # Safety: only extract sov/ namespace
-            if not name.startswith("sov/"):
-                continue
-            rel = name[4:]  # strip sov/
-            dest = target_root / rel
-
-            # Skip manifest itself - used for tracking only
-            if rel == "manifest.json":
-                continue
-
-            # Create parent dirs
-            dest.parent.mkdir(parents=True, exist_ok=True)
-
-            # Extract and write
-            data = zf.read(name)
-            dest.write_bytes(data)
-            restored.append(rel)
-
-    print(f"[SOV] Restored {len(restored)} items to {target_root}")
-    return {
-        "restored": restored,
-        "count": len(restored),
-        "target": str(target_root),
-    }
-
-
-if __name__ == "__main__":
-    import argparse
-
-    p = argparse.ArgumentParser(description="Sovereign Bundle (.sov) export/import tool")
-    sub = p.add_subparsers(dest="cmd", required=True)
-
-    # Export
-    exp = sub.add_parser("export", help="Create a .sov bundle")
-    exp.add_argument("-o", "--output", default="timmy-sovereign-bundle.sov",
-                     help="Output path for .sov file")
-    exp.add_argument("--include-sessions", action="store_true",
-                     help="Include full session transcripts (larger bundle)")
-    exp.add_argument("--hermes-home", type=str,
-                     help="Override HERMES_HOME source")
-
-    # Import / restore
-    imp = sub.add_parser("import", help="Restore from a .sov bundle")
-    imp.add_argument("bundle", help="Path to .sov file")
-    imp.add_argument("-t", "--target", help="Restore target (default: bundle's source)")
-    imp.add_argument("--dry-run", action="store_true", help="Validate only")
-
-    # Verify
-    ver = sub.add_parser("verify", help="Verify bundle integrity")
-    ver.add_argument("bundle", help="Path to .sov file")
-
-    args = p.parse_args()
-
-    if args.cmd == "export":
-        result = create_bundle(
-            output_path=args.output,
-            hermes_home=Path(args.hermes_home).expanduser() if args.hermes_home else None,
-            include_sessions=args.include_sessions,
-        )
-        print(json.dumps(result, indent=2))
-
-    elif args.cmd == "import":
-        result = restore_bundle(args.bundle, Path(args.target) if args.target else None,
-                               dry_run=args.dry_run)
-        print(json.dumps(result, indent=2) if not args.dry_run else None)
-
-    elif args.cmd == "verify":
-        info = verify_bundle(args.bundle)
-        print(f"Bundle: {args.bundle}")
-        print(f"  Valid: {info['valid']}")
-        print(f"  Items: {info['items']}")
-        print(f"  Hash: {info['bundle_hash']}")
-        print(f"  Manifest version: {info['manifest'].get('version')}")

timmy-local/scripts/restore_sov_bundle.py

@@ -1,182 +0,0 @@
-#!/usr/bin/env python3
-"""
-Restore agent state from a Sovereign Bundle (.sov) file.
-
-Usage:
-  python restore_sov_bundle.py <bundle.sov> [--target ~/.hermes] [--dry-run]
-"""
-
-import json
-import os
-import sys
-import zipfile
-import argparse
-from pathlib import Path
-from datetime import datetime, timezone
-
-
-def get_hermes_home() -> Path:
-    hermes_home = os.getenv("HERMES_HOME")
-    if hermes_home:
-        return Path(hermes_home).expanduser()
-    return Path.home() / ".hermes"
-
-
-def verify_bundle(bundle_path: str) -> dict:
-    """Verify .sov bundle integrity and return manifest."""
-    with zipfile.ZipFile(bundle_path, 'r') as zf:
-        # Require manifest
-        try:
-            mf = json.loads(zf.read("sov/manifest.json"))
-        except KeyError:
-            raise ValueError("Not a valid .sov bundle: missing sov/manifest.json")
-        except json.JSONDecodeError as e:
-            raise ValueError(f"Manifest JSON decode error: {e}")
-
-        return {
-            "valid": True,
-            "entries": zf.namelist(),
-            "manifest": mf,
-            "size": Path(bundle_path).stat().st_size,
-        }
-
-
-def restore_bundle(bundle_path: str,
-                   target_root: Path = None,
-                   dry_run: bool = False) -> dict:
-    """
-    Extract a .sov bundle to target_root.
-
-    Safety: Only extracts files under sov/ namespace.
-    Does not overwrite existing files by default? (could add --force)
-    """
-    bundle = Path(bundle_path)
-    if not bundle.exists():
-        raise FileNotFoundError(f"Bundle not found: {bundle_path}")
-
-    info = verify_bundle(bundle_path)
-    manifest = info["manifest"]
-
-    src_root = Path(manifest["source_root"])
-    if target_root is None:
-        target_root = src_root
-    else:
-        target_root = Path(target_root)
-
-    print(f"[SOV] Bundle: {bundle_path}")
-    print(f"  Source: {src_root}")
-    print(f"  Target: {target_root}")
-    print(f"  Created: {manifest.get('created_at')}")
-    print(f"  Version: {manifest.get('version')}")
-
-    if dry_run:
-        sov_entries = [n for n in info["entries"] if n.startswith("sov/") and n != "sov/manifest.json"]
-        print(f"  DRY RUN: Would restore {len(sov_entries)} items")
-        return {"dry_run": True, "count": len(sov_entries)}
-
-    restored = []
-    errors = []
-
-    with zipfile.ZipFile(bundle_path, 'r') as zf:
-        for name in sorted(zf.namelist()):
-            if not name.startswith("sov/"):
-                continue
-            if name == "sov/manifest.json":
-                continue  # Tracked separately
-
-            rel = name[4:]  # strip sov/
-            dest = target_root / rel
-            dest.parent.mkdir(parents=True, exist_ok=True)
-
-            try:
-                data = zf.read(name)
-                dest.write_bytes(data)
-                restored.append(rel)
-            except Exception as e:
-                errors.append((rel, str(e)))
-
-    print(f"\n[SOV] Restored {len(restored)} files to {target_root}")
-    if errors:
-        print(f"  Errors: {len(errors)}")
-        for path, err in errors:
-            print(f"  ✗ {path}: {err}")
-
-    # Print a summary of restored components
-    comp = manifest.get("components", {})
-    for comp_name, details in comp.items():
-        if isinstance(details, dict) and "count" in details:
-            print(f"  {comp_name}: {details['count']}")
-        elif isinstance(details, dict):
-            print(f"  {comp_name}: {', '.join(details.keys())}")
-
-    return {
-        "restored": restored,
-        "count": len(restored),
-        "errors": errors,
-        "target": str(target_root),
-    }
-
-
-def list_entries(bundle_path: str) -> None:
-    """List all entries in a .sov bundle with sizes."""
-    with zipfile.ZipFile(bundle_path, 'r') as zf:
-        manifest = json.loads(zf.read("sov/manifest.json"))
-        entries = sorted([n for n in zf.namelist() if n != "sov/manifest.json"])
-
-        print(f"Bundle ID: {manifest.get('bundle_id')}")
-        print(f"Version:   {manifest.get('version')}")
-        print(f"Created:   {manifest.get('created_at')}")
-        print(f"Source:    {manifest.get('source_root')}")
-        print(f"\nContents ({len(entries)} entries):\n")
-
-        by_category = {}
-        for e in entries:
-            cat = e.split('/')[1] if len(e.split('/')) > 1 else 'root'
-            by_category.setdefault(cat, []).append(e)
-
-        for cat in sorted(by_category):
-            print(f" [{cat}]")
-            for e in by_category[cat]:
-                info = zf.getinfo(e)
-                print(f"   {e}  ({info.file_size:,} bytes)")
-
-
-if __name__ == "__main__":
-    p = argparse.ArgumentParser(description="Restore Sovereign Bundle (.sov)")
-    p.add_argument("bundle", nargs="?", help="Path to .sov file")
-    p.add_argument("--target", "-t", type=str, help="Restore target directory")
-    p.add_argument("--dry-run", action="store_true", help="Validate without extracting")
-    p.add_argument("--list", "-l", action="store_true", help="List bundle contents")
-    p.add_argument("--yes", "-y", action="store_true", help="Skip confirmation prompt")
-
-    args = p.parse_args()
-
-    if args.list:
-        if not args.bundle:
-            print("Usage: restore_sov_bundle.py --list <bundle.sov>")
-            sys.exit(1)
-        list_entries(args.bundle)
-        sys.exit(0)
-
-    if not args.bundle:
-        p.print_help()
-        sys.exit(1)
-
-    bundle_path = args.bundle
-    if not Path(bundle_path).exists():
-        print(f"Error: Bundle not found: {bundle_path}")
-        sys.exit(1)
-
-    target = Path(args.target) if args.target else None
-
-    # Safety prompt unless dry-run or --yes
-    if not args.dry_run and not args.yes:
-        t = target or get_hermes_home()
-        resp = input(f"Restore to {t}? [y/N] ").strip().lower()
-        if resp != 'y':
-            print("Aborted.")
-            sys.exit(0)
-
-    result = restore_bundle(bundle_path, target_root=target, dry_run=args.dry_run)
-    if result.get("errors"):
-        sys.exit(1)