@ramarivera/coding-buddy 0.4.0-alpha.8 → 0.6.0

package/{adapters/claude/install → cli}/backup.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * claude-buddy backup — snapshot all claude-buddy related state
+ * coding-buddy backup — snapshot all coding-buddy related state
  *
  * Usage:
  *   bun run backup                 Create a new snapshot
@@ -10,15 +10,20 @@
  *   bun run backup restore <ts>    Restore a specific backup
  *   bun run backup delete <ts>     Delete a specific backup
  *
- * Backups are stored in ~/.claude-buddy/backups/YYYY-MM-DD-HHMMSS/
+ * Backups are stored in <state-dir>/backups/YYYY-MM-DD-HHMMSS/, where
+ * <state-dir> resolves via server/paths.ts ($CLAUDE_CONFIG_DIR/buddy-state
+ * when that env var is set, else ~/.claude-buddy).
  *
  * What gets backed up:
- *   - ~/.claude/settings.json (full file)
- *   - ~/.claude.json mcpServers["claude-buddy"] block (only our entry)
- *   - ~/.claude/skills/buddy/SKILL.md
- *   - ~/.claude-buddy/companion.json
- *   - ~/.claude-buddy/status.json
- *   - ~/.claude-buddy/reaction.json
+ *   - settings.json (full file)
+ *   - .claude.json mcpServers["claude-buddy"] block (only our entry)
+ *   - skills/buddy/SKILL.md
+ *   - <state-dir>/menagerie.json
+ *   - <state-dir>/config.json
+ *   - <state-dir>/status.json
+ *   - <state-dir>/events.json
+ *   - <state-dir>/unlocked.json
+ *   - <state-dir>/active_days.json
  */
 
 import {
@@ -26,15 +31,19 @@ import {
   readdirSync, statSync, rmSync, copyFileSync,
 } from "fs";
 import { dirname, join } from "path";
-import { homedir } from "os";
-import { getBuddySkillDir, getClaudeJsonPath, getClaudeSettingsPath } from "../storage/paths.ts";
-
-const HOME = homedir();
-const BACKUPS_DIR = join(HOME, ".claude-buddy", "backups");
-const SETTINGS = getClaudeSettingsPath();
-const CLAUDE_JSON = getClaudeJsonPath();
-const SKILL = join(getBuddySkillDir(), "SKILL.md");
-const STATE_DIR = join(HOME, ".claude-buddy");
+import {
+  buddyStateDir,
+  claudeSettingsPath,
+  claudeSkillDir,
+  claudeUserConfigPath,
+} from "../server/path.ts";
+
+const SETTINGS = claudeSettingsPath();
+const CLAUDE_JSON = claudeUserConfigPath();
+const SKILL_DIR = claudeSkillDir("buddy");
+const SKILL = join(SKILL_DIR, "SKILL.md");
+const STATE_DIR = buddyStateDir();
+const BACKUPS_DIR = join(STATE_DIR, "backups");
 
 const RED = "\x1b[31m";
 const GREEN = "\x1b[32m";
@@ -74,16 +83,16 @@ function createBackup(): string {
   const dir = join(BACKUPS_DIR, ts);
   mkdirSync(dir, { recursive: true });
 
-  const manifest: { timestamp: string; files: string[] } = { timestamp: ts, files: [] };
+  const manifest: Record<string, any> = { timestamp: ts, files: [] };
 
   // 1. settings.json
   const settings = tryRead(SETTINGS);
   if (settings) {
     writeFileSync(join(dir, "settings.json"), settings);
     manifest.files.push("settings.json");
-    ok(`Backed up: ~/.claude/settings.json`);
+    ok(`Backed up: ${SETTINGS}`);
   } else {
-    warn(`Skipped: ~/.claude/settings.json (not found)`);
+    warn(`Skipped: ${SETTINGS} (not found)`);
   }
 
   // 2. claude.json mcpServers["claude-buddy"]
@@ -95,12 +104,12 @@ function createBackup(): string {
       if (ourMcp) {
         writeFileSync(join(dir, "mcpserver.json"), JSON.stringify(ourMcp, null, 2));
         manifest.files.push("mcpserver.json");
-        ok(`Backed up: ~/.claude.json → mcpServers["claude-buddy"]`);
+        ok(`Backed up: ${CLAUDE_JSON} → mcpServers["claude-buddy"]`);
       } else {
-        warn(`Skipped: ~/.claude.json mcpServers["claude-buddy"] (not registered)`);
+        warn(`Skipped: ${CLAUDE_JSON} mcpServers["claude-buddy"] (not registered)`);
       }
     } catch {
-      err(`Failed to parse ~/.claude.json`);
+      err(`Failed to parse ${CLAUDE_JSON}`);
     }
   }
 
@@ -109,21 +118,21 @@ function createBackup(): string {
   if (skill) {
     writeFileSync(join(dir, "SKILL.md"), skill);
     manifest.files.push("SKILL.md");
-    ok(`Backed up: ~/.claude/skills/buddy/SKILL.md`);
+    ok(`Backed up: ${SKILL}`);
   } else {
-    warn(`Skipped: ~/.claude/skills/buddy/SKILL.md (not found)`);
+    warn(`Skipped: ${SKILL} (not found)`);
   }
 
-  // 4-6. ~/.claude-buddy/ state files (don't back up the backups dir itself)
+  // 4+. ~/.claude-buddy/ state files (don't back up the backups dir itself)
   const stateDestDir = join(dir, "claude-buddy");
   mkdirSync(stateDestDir, { recursive: true });
-  const stateFiles = ["companion.json", "status.json", "reaction.json"];
+  const stateFiles = ["menagerie.json", "config.json", "status.json", "events.json", "unlocked.json", "active_days.json"];
   for (const f of stateFiles) {
     const src = join(STATE_DIR, f);
     if (existsSync(src)) {
       copyFileSync(src, join(stateDestDir, f));
       manifest.files.push(`claude-buddy/${f}`);
-      ok(`Backed up: ~/.claude-buddy/${f}`);
+      ok(`Backed up: ${join(STATE_DIR, f)}`);
     }
   }
 
@@ -141,7 +150,7 @@ function cmdList() {
     info(`Run '${BOLD}bun run backup${NC}' to create one.`);
     return;
   }
-  console.log(`\n${BOLD}claude-buddy backups${NC}\n`);
+  console.log(`\n${BOLD}coding-buddy backups${NC}\n`);
   for (const ts of backups) {
     const manifestPath = join(BACKUPS_DIR, ts, "manifest.json");
     const manifest = tryRead(manifestPath);
@@ -196,29 +205,32 @@ function restoreBackup(ts: string) {
   if (existsSync(settingsBak)) {
     mkdirSync(dirname(SETTINGS), { recursive: true });
     copyFileSync(settingsBak, SETTINGS);
-    ok("Restored: ~/.claude/settings.json");
+    ok(`Restored: ${SETTINGS}`);
   }
 
   // 2. claude.json mcpServers — merge our entry back in
   const mcpBak = join(dir, "mcpserver.json");
   if (existsSync(mcpBak)) {
     const ourMcp = JSON.parse(readFileSync(mcpBak, "utf8"));
-    let claudeJson: { mcpServers?: Record<string, unknown> } = {};
+    let claudeJson: Record<string, any> = {};
     try {
-      claudeJson = JSON.parse(readFileSync(CLAUDE_JSON, "utf8")) as { mcpServers?: Record<string, unknown> };
+      claudeJson = JSON.parse(readFileSync(CLAUDE_JSON, "utf8"));
     } catch { /* empty */ }
     if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
     claudeJson.mcpServers["claude-buddy"] = ourMcp;
+    // Under CLAUDE_CONFIG_DIR the parent dir is not guaranteed to exist
+    // if settings.json wasn't in this backup (and so step 1 was skipped).
+    mkdirSync(dirname(CLAUDE_JSON), { recursive: true });
     writeFileSync(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2));
-    ok("Restored: ~/.claude.json → mcpServers[\"claude-buddy\"]");
+    ok(`Restored: ${CLAUDE_JSON} → mcpServers["claude-buddy"]`);
   }
 
   // 3. SKILL.md
   const skillBak = join(dir, "SKILL.md");
   if (existsSync(skillBak)) {
-    mkdirSync(dirname(SKILL), { recursive: true });
+    mkdirSync(SKILL_DIR, { recursive: true });
     copyFileSync(skillBak, SKILL);
-    ok("Restored: ~/.claude/skills/buddy/SKILL.md");
+    ok(`Restored: ${SKILL}`);
   }
 
   // 4. ~/.claude-buddy/ state files
@@ -227,7 +239,7 @@ function restoreBackup(ts: string) {
     mkdirSync(STATE_DIR, { recursive: true });
     for (const f of readdirSync(stateDir)) {
       copyFileSync(join(stateDir, f), join(STATE_DIR, f));
-      ok(`Restored: ~/.claude-buddy/${f}`);
+      ok(`Restored: ${join(STATE_DIR, f)}`);
     }
   }
 
@@ -254,7 +266,7 @@ const arg = process.argv[3];
 switch (action) {
   case "create":
   case undefined: {
-    console.log(`\n${BOLD}Creating claude-buddy backup...${NC}\n`);
+    console.log(`\n${BOLD}Creating coding-buddy backup...${NC}\n`);
     const ts = createBackup();
     console.log(`\n${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
     console.log(`${GREEN}  Backup created: ${ts}${NC}`);
@@ -307,7 +319,7 @@ switch (action) {
   case "--help":
   case "-h":
     console.log(`
-${BOLD}claude-buddy backup${NC} — snapshot and restore all claude-buddy state
+${BOLD}coding-buddy backup${NC} — snapshot and restore all coding-buddy state
 
 ${BOLD}Commands:${NC}
   bun run backup                 Create a new snapshot
@@ -318,12 +330,15 @@ ${BOLD}Commands:${NC}
   bun run backup delete <ts>     Delete a specific backup
 
 ${BOLD}What gets backed up:${NC}
-  - ~/.claude/settings.json (full)
-  - ~/.claude.json mcpServers["claude-buddy"] (only our entry)
-  - ~/.claude/skills/buddy/SKILL.md
-  - ~/.claude-buddy/companion.json
-  - ~/.claude-buddy/status.json
-  - ~/.claude-buddy/reaction.json
+  - ${SETTINGS}
+  - ${CLAUDE_JSON} mcpServers["claude-buddy"] (only our entry)
+  - ${SKILL}
+  - ${STATE_DIR}/menagerie.json
+  - ${STATE_DIR}/config.json
+  - ${STATE_DIR}/status.json
+  - ${STATE_DIR}/events.json
+  - ${STATE_DIR}/unlocked.json
+  - ${STATE_DIR}/active_days.json
 
 ${BOLD}Backup location:${NC}
   ${BACKUPS_DIR}/<timestamp>/

package/cli/biomes.ts

@@ -0,0 +1,309 @@
+/**
+ * biomes.ts — landscape themes for the buddy panel
+ *
+ * 5 default biomes (mapped to rarity) + 10 extra biomes selectable via --biome flag.
+ *
+ * Usage:
+ *   npx tsx cli/buddy-shell.ts claude                    # auto-detect by rarity
+ *   npx tsx cli/buddy-shell.ts claude --biome volcano    # force a specific biome
+ *   npx tsx cli/buddy-shell.ts --biomes                  # list all available biomes
+ */
+
+const ESC = "\x1b";
+const CSI = `${ESC}[`;
+const NC = `${CSI}0m`;
+
+function c(r: number, g: number, b: number): string {
+  return `${CSI}38;2;${r};${g};${b}m`;
+}
+
+// ─── Biome definition ───────────────────────────────────────────────────────
+
+export interface Biome {
+  name: string;
+  sky: string;
+  ground: string;
+  particle: { color: string; chars: string[] };
+  groundChars: string[];
+  structure: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DEFAULT BIOMES (by rarity)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const meadow: Biome = {
+  name: "meadow",
+  sky: c(40, 40, 60),
+  ground: c(60, 90, 40),
+  particle: { color: c(150, 150, 130), chars: ["✦", "·", "·"] },
+  groundChars: ["▄", "▄", "▄", "▓", "▄", "▒"],
+  structure: [
+    `${c(120, 80, 60)}         ░░${NC}`,
+    `${c(160, 60, 50)}   ▄████████▄${NC}`,
+    `${c(160, 60, 50)}  ▟${c(140, 90, 50)}██${c(200, 200, 100)}▪▪${c(140, 90, 50)}██${c(200, 200, 100)}▪▪${c(140, 90, 50)}██${c(160, 60, 50)}▙${NC}`,
+    `${c(140, 90, 50)}  ██${c(200, 200, 100)}▪▪${c(140, 90, 50)}██${c(200, 200, 100)}▪▪${c(140, 90, 50)}████${NC}`,
+    `${c(140, 90, 50)}  ██${c(200, 200, 100)}▪▪${c(140, 90, 50)}█${c(100, 60, 30)}▐██▌${c(140, 90, 50)}█${c(200, 200, 100)}▪▪${c(140, 90, 50)}██${NC}`,
+    `${c(140, 90, 50)}  ██${c(200, 200, 100)}▪▪${c(140, 90, 50)}█${c(100, 60, 30)}▐██▌${c(140, 90, 50)}█${c(200, 200, 100)}▪▪${c(140, 90, 50)}██${NC}`,
+  ],
+};
+
+const forest: Biome = {
+  name: "forest",
+  sky: c(15, 35, 25),
+  ground: c(30, 80, 35),
+  particle: { color: c(80, 160, 80), chars: ["✦", "·", "·"] },
+  groundChars: ["▄", "▄", "▓", "▄", "▒", "▄"],
+  structure: [
+    `${c(40, 110, 40)}  ▄██████▄${NC}`,
+    `${c(50, 130, 50)}▄██${c(200, 50, 30)}●${c(50, 130, 50)}███${c(200, 50, 30)}●${c(50, 130, 50)}██▄${NC}`,
+    `${c(60, 150, 60)}████${c(200, 50, 30)}●${c(60, 150, 60)}███████${NC}`,
+    `${c(60, 150, 60)}██████${c(200, 50, 30)}●${c(60, 150, 60)}████${NC}`,
+    `${c(50, 130, 50)} ▀████████▀${NC}`,
+    `${c(80, 60, 40)}  ▟${c(60, 100, 50)}██${c(200, 200, 100)}▪▪${c(60, 100, 50)}██${c(80, 60, 40)}▙${NC}`,
+    `${c(80, 60, 40)}  ║${c(60, 100, 50)}██${c(200, 200, 100)}▪▪${c(60, 100, 50)}██${c(80, 60, 40)}║${NC}`,
+    `${c(80, 60, 40)}  ║██${c(100, 60, 30)}▐██▌${c(80, 60, 40)}██║${NC}`,
+  ],
+};
+
+const ocean: Biome = {
+  name: "ocean",
+  sky: c(15, 20, 55),
+  ground: c(40, 90, 140),
+  particle: { color: c(100, 140, 220), chars: ["✦", "·", "~"] },
+  groundChars: ["▄", "~", "≈", "▄", "~", "▄"],
+  structure: [
+    `${c(200, 200, 100)}      ◉${NC}`,
+    `${c(200, 50, 50)}    ▄███▄${NC}`,
+    `${c(220, 220, 220)}   ▐${c(200, 50, 50)}█${c(220, 220, 220)}███${c(200, 50, 50)}█${c(220, 220, 220)}▌${NC}`,
+    `${c(220, 220, 220)}   ▐█████▌${NC}`,
+    `${c(220, 220, 220)}   ▐█████▌${NC}`,
+    `${c(180, 180, 180)}  ▟███████▙${NC}`,
+  ],
+};
+
+const cyberpunk: Biome = {
+  name: "cyberpunk",
+  sky: c(20, 10, 35),
+  ground: c(40, 30, 60),
+  particle: { color: c(180, 80, 220), chars: ["✦", "·", "░"] },
+  groundChars: ["▀", "▄", "█", "▀", "▄", "░"],
+  structure: [
+    `${c(255, 0, 100)}  ▄${c(0, 255, 200)}█${c(255, 0, 100)}█${c(0, 255, 200)}█${c(255, 0, 100)}▄${NC}`,
+    `${c(80, 60, 100)}  █${c(0, 255, 200)}▪${c(80, 60, 100)}█${c(255, 0, 100)}▪${c(80, 60, 100)}█${NC}`,
+    `${c(80, 60, 100)}  █${c(255, 0, 100)}▪${c(80, 60, 100)}█${c(0, 255, 200)}▪${c(80, 60, 100)}█${NC}`,
+    `${c(80, 60, 100)}  █${c(0, 255, 200)}▪${c(80, 60, 100)}█${c(255, 0, 100)}▪${c(80, 60, 100)}█${NC}`,
+    `${c(80, 60, 100)} ██${c(0, 255, 200)}▪${c(80, 60, 100)}█${c(255, 0, 100)}▪${c(80, 60, 100)}██${NC}`,
+    `${c(80, 60, 100)} ██${c(255, 200, 0)}▐▌${c(80, 60, 100)}█${c(255, 200, 0)}▐▌${c(80, 60, 100)}██${NC}`,
+  ],
+};
+
+const space: Biome = {
+  name: "space",
+  sky: c(8, 5, 20),
+  ground: c(50, 40, 70),
+  particle: { color: c(255, 200, 50), chars: ["✦", "·", "·", "✧"] },
+  groundChars: ["▄", "░", "▒", "▄", "▓", "░"],
+  structure: [
+    `${c(255, 200, 50)}     ✨${NC}`,
+    `${c(100, 80, 150)}   ▄████▄${NC}`,
+    `${c(120, 100, 170)}  ▟${c(150, 130, 200)}██${c(255, 220, 100)}◆◆${c(150, 130, 200)}██${c(120, 100, 170)}▙${NC}`,
+    `${c(150, 130, 200)}  ██${c(255, 220, 100)}◆◆${c(150, 130, 200)}████${NC}`,
+    `${c(150, 130, 200)}  ██${c(255, 220, 100)}◆◆${c(150, 130, 200)}█${c(200, 180, 255)}▐██▌${c(150, 130, 200)}██${NC}`,
+    `${c(150, 130, 200)}  ████████████${NC}`,
+  ],
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXTRA BIOMES (selectable via --biome flag)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const volcano: Biome = {
+  name: "volcano",
+  sky: c(50, 15, 5),
+  ground: c(80, 30, 10),
+  particle: { color: c(255, 120, 20), chars: ["✦", "·", "▪"] },
+  groundChars: ["▄", "▓", "▄", "█", "▒", "▄"],
+  structure: [
+    `${c(255, 80, 0)}      ▓${NC}`,
+    `${c(255, 120, 20)}     ▄${c(200, 50, 10)}█${c(255, 120, 20)}▄${NC}`,
+    `${c(200, 50, 10)}    ▟███▙${NC}`,
+    `${c(150, 40, 10)}   ▟█████▙${NC}`,
+    `${c(120, 30, 10)}  ▟███████▙${NC}`,
+    `${c(100, 25, 8)} ▟█████████▙${NC}`,
+  ],
+};
+
+const arctic: Biome = {
+  name: "arctic",
+  sky: c(20, 30, 50),
+  ground: c(180, 200, 220),
+  particle: { color: c(200, 220, 255), chars: ["❄", "·", "✧"] },
+  groundChars: ["▄", "▄", "░", "▄", "▄", "▒"],
+  structure: [
+    `${c(200, 220, 240)}     ▄▄▄${NC}`,
+    `${c(200, 220, 240)}   ▄█████▄${NC}`,
+    `${c(220, 230, 245)}  █████████${NC}`,
+    `${c(220, 230, 245)}  ███${c(60, 80, 120)}▐██▌${c(220, 230, 245)}███${NC}`,
+    `${c(220, 230, 245)}  █████████${NC}`,
+    `${c(200, 220, 240)}  █████████${NC}`,
+  ],
+};
+
+const desert: Biome = {
+  name: "desert",
+  sky: c(40, 25, 15),
+  ground: c(180, 150, 80),
+  particle: { color: c(200, 180, 100), chars: ["✦", "·", "·"] },
+  groundChars: ["▄", "░", "▄", "▄", "░", "▄"],
+  structure: [
+    `${c(200, 180, 100)}      ▲${NC}`,
+    `${c(200, 180, 100)}     ▟█▙${NC}`,
+    `${c(190, 170, 90)}    ▟███▙${NC}`,
+    `${c(180, 160, 80)}   ▟█████▙${NC}`,
+    `${c(170, 150, 70)}  ▟███████▙${NC}`,
+    `${c(160, 140, 60)} ▟█████████▙${NC}`,
+  ],
+};
+
+const haunted: Biome = {
+  name: "haunted",
+  sky: c(15, 10, 25),
+  ground: c(40, 35, 50),
+  particle: { color: c(100, 80, 140), chars: ["✦", "·", "👻"] },
+  groundChars: ["▄", "▒", "▄", "▓", "▄", "▒"],
+  structure: [
+    `${c(60, 50, 80)}     ▄█▄${NC}`,
+    `${c(60, 50, 80)}   ▄█████▄${NC}`,
+    `${c(50, 40, 70)}   ██${c(200, 50, 50)}▪▪▪${c(50, 40, 70)}██${NC}`,
+    `${c(50, 40, 70)}   ██${c(200, 50, 50)}▪▪▪${c(50, 40, 70)}██${NC}`,
+    `${c(50, 40, 70)}  ████${c(30, 20, 40)}▐▌${c(50, 40, 70)}████${NC}`,
+    `${c(40, 30, 60)} ████████████${NC}`,
+  ],
+};
+
+const sakura: Biome = {
+  name: "sakura",
+  sky: c(40, 20, 35),
+  ground: c(80, 60, 50),
+  particle: { color: c(255, 150, 180), chars: ["✿", "·", "✦"] },
+  groundChars: ["▄", "▄", "▓", "▄", "▄", "▒"],
+  structure: [
+    `${c(200, 50, 80)}    ▄▄▄▄▄${NC}`,
+    `${c(200, 50, 80)}  ▄███████▄${NC}`,
+    `${c(160, 40, 60)}  ▀███████▀${NC}`,
+    `${c(120, 70, 50)}     ║║${NC}`,
+    `${c(120, 70, 50)}     ║║${NC}`,
+    `${c(120, 70, 50)}   ▄▄║║▄▄${NC}`,
+  ],
+};
+
+const underwater: Biome = {
+  name: "underwater",
+  sky: c(10, 30, 60),
+  ground: c(40, 80, 60),
+  particle: { color: c(80, 180, 220), chars: ["°", "·", "○"] },
+  groundChars: ["▄", "▒", "▓", "▄", "▒", "▄"],
+  structure: [
+    `${c(80, 200, 100)}   \\│//${NC}`,
+    `${c(80, 200, 100)}    \\│/${NC}`,
+    `${c(80, 200, 100)}     │${NC}`,
+    `${c(255, 100, 80)}   ▄███▄${NC}`,
+    `${c(255, 80, 60)}  ▟█████▙${NC}`,
+    `${c(255, 60, 40)} ▟███████▙${NC}`,
+  ],
+};
+
+const candyland: Biome = {
+  name: "candyland",
+  sky: c(50, 20, 50),
+  ground: c(200, 100, 150),
+  particle: { color: c(255, 150, 200), chars: ["✦", "♥", "·"] },
+  groundChars: ["▄", "▄", "░", "▄", "▄", "▒"],
+  structure: [
+    `${c(255, 200, 100)}     ★${NC}`,
+    `${c(200, 100, 50)}  ▄█████▄${NC}`,
+    `${c(220, 150, 100)}  █${c(255, 100, 150)}▪${c(100, 200, 255)}▪${c(255, 255, 100)}▪${c(100, 255, 100)}▪${c(255, 100, 150)}▪${c(220, 150, 100)}█${NC}`,
+    `${c(220, 150, 100)}  █${c(100, 255, 100)}▪${c(255, 100, 150)}▪${c(100, 200, 255)}▪${c(255, 255, 100)}▪${c(100, 255, 100)}▪${c(220, 150, 100)}█${NC}`,
+    `${c(220, 150, 100)}  █████${c(180, 80, 50)}▐▌${c(220, 150, 100)}████${NC}`,
+    `${c(220, 150, 100)}  █████████████${NC}`,
+  ],
+};
+
+const dungeon: Biome = {
+  name: "dungeon",
+  sky: c(20, 18, 15),
+  ground: c(60, 55, 45),
+  particle: { color: c(255, 150, 30), chars: ["✦", "·", "·"] },
+  groundChars: ["▄", "█", "▄", "▓", "▄", "█"],
+  structure: [
+    `${c(80, 75, 65)}  ▄█▄█▄█▄█▄${NC}`,
+    `${c(80, 75, 65)}  ██████████${NC}`,
+    `${c(70, 65, 55)}  ██${c(255, 150, 30)}▪▪${c(70, 65, 55)}██${c(255, 150, 30)}▪▪${c(70, 65, 55)}██${NC}`,
+    `${c(70, 65, 55)}  ██████████${NC}`,
+    `${c(70, 65, 55)}  ██${c(40, 35, 25)}▐██▌${c(70, 65, 55)}████${NC}`,
+    `${c(60, 55, 45)}  ██████████${NC}`,
+  ],
+};
+
+const cloudkingdom: Biome = {
+  name: "cloudkingdom",
+  sky: c(30, 40, 70),
+  ground: c(180, 190, 220),
+  particle: { color: c(200, 210, 240), chars: ["✦", "☁", "·"] },
+  groundChars: ["▄", "░", "▄", "▄", "░", "░"],
+  structure: [
+    `${c(200, 180, 255)}     ▲${NC}`,
+    `${c(200, 180, 255)}    ▟█▙${NC}`,
+    `${c(180, 160, 240)}   ▟███▙${NC}`,
+    `${c(180, 160, 240)}   █${c(255, 220, 100)}◆◆${c(180, 160, 240)}██${NC}`,
+    `${c(180, 160, 240)}   █████${NC}`,
+    `${c(200, 200, 230)} ▟█████████▙${NC}`,
+  ],
+};
+
+const matrix: Biome = {
+  name: "matrix",
+  sky: c(0, 10, 0),
+  ground: c(0, 40, 0),
+  particle: { color: c(0, 200, 0), chars: ["0", "1", "·"] },
+  groundChars: ["▄", "█", "▄", "▀", "▄", "█"],
+  structure: [
+    `${c(0, 150, 0)}  ▄██████▄${NC}`,
+    `${c(0, 120, 0)}  █${c(0, 255, 0)}01${c(0, 120, 0)}██${c(0, 255, 0)}10${c(0, 120, 0)}█${NC}`,
+    `${c(0, 120, 0)}  █${c(0, 255, 0)}10${c(0, 120, 0)}██${c(0, 255, 0)}01${c(0, 120, 0)}█${NC}`,
+    `${c(0, 120, 0)}  █${c(0, 255, 0)}01${c(0, 120, 0)}██${c(0, 255, 0)}10${c(0, 120, 0)}█${NC}`,
+    `${c(0, 100, 0)}  █${c(0, 200, 0)}▐▌${c(0, 100, 0)}██${c(0, 200, 0)}▐▌${c(0, 100, 0)}█${NC}`,
+    `${c(0, 80, 0)}  ▀██████▀${NC}`,
+  ],
+};
+
+// ─── Registry ───────────────────────────────────────────────────────────────
+
+const RARITY_BIOMES: Record<string, Biome> = {
+  common: meadow,
+  uncommon: forest,
+  rare: ocean,
+  epic: cyberpunk,
+  legendary: space,
+};
+
+const ALL_BIOMES: Record<string, Biome> = {
+  // Defaults (by rarity name)
+  meadow, forest, ocean, cyberpunk, space,
+  // Extras
+  volcano, arctic, desert, haunted, sakura,
+  underwater, candyland, dungeon, cloudkingdom, matrix,
+};
+
+export function getBiome(rarity: string, override?: string): Biome {
+  if (override && ALL_BIOMES[override]) return ALL_BIOMES[override];
+  return RARITY_BIOMES[rarity] ?? meadow;
+}
+
+export function listBiomes(): { name: string; isDefault: boolean }[] {
+  return Object.keys(ALL_BIOMES).map(name => ({
+    name,
+    isDefault: Object.values(RARITY_BIOMES).some(b => b.name === name),
+  }));
+}