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

package/cli/tui.tsx

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * cli/tui.tsx — fullscreen 3-pane dashboard for claude-buddy (Ink/React)
+ * cli/tui.tsx — fullscreen 3-pane dashboard for coding-buddy (Ink/React)
  *
  * Layout: persistent sidebar | content list | detail preview
  * The sidebar is always visible. Selecting a section opens the
@@ -35,7 +35,7 @@ import {
   RARITY_STARS, STAT_NAMES, SPECIES, RARITIES, generateBones, searchBuddy,
   type Companion, type StatName, type Species, type Rarity,
   type SearchCriteria, type SearchResult, type BuddyBones,
-} from "../server/engine.ts";
+} from "../core/engine.ts";
 import { getArtFrame, HAT_ART } from "../server/art.ts";
 import {
   ACHIEVEMENTS, loadUnlocked, loadEvents,
@@ -139,7 +139,7 @@ const SIDEBAR_ITEMS: SidebarItem[] = [
     key: "backup", icon: "💾", label: "Backup",
     description: [
       "Create and browse snapshots of your",
-      "claude-buddy state — settings, hooks,",
+      "coding-buddy state — settings, hooks,",
       "skill, menagerie, status, and config.",
       "",
       "Restore is currently manual (copy from",
@@ -149,7 +149,7 @@ const SIDEBAR_ITEMS: SidebarItem[] = [
   {
     key: "system", icon: "🚨", label: "System",
     description: [
-      "Manage claude-buddy's installation:",
+      "Manage coding-buddy's installation:",
       "",
       "• Re-Enable — runs install-buddy",
       "• Disable  — keeps data, removes MCP",
@@ -167,7 +167,7 @@ function Sidebar({ cursor, section, focus }: {
   const isFocused = focus === "sidebar";
   return (
     <Box flexDirection="column" paddingX={1}>
-      <Text bold color="cyan">{" 🐢 claude-buddy"}</Text>
+      <Text bold color="cyan">{" 🐢 coding-buddy"}</Text>
       <Text>{""}</Text>
       {SIDEBAR_ITEMS.map((item, i) => {
         const isActive = item.key === section && focus !== "sidebar";
@@ -306,35 +306,123 @@ const ACHIEVEMENT_PROGRESS: Record<string, { counter: keyof EventCounters; thres
   first_steps: null,
   good_boy: { counter: "pets", threshold: 10 },
   best_friend: { counter: "pets", threshold: 50 },
+  pet_overflow: { counter: "pets", threshold: 100 },
+  pet_legend: { counter: "pets", threshold: 250 },
+  pet_obsessed: { counter: "pets", threshold: 500 },
+  pet_god: { counter: "pets", threshold: 1000 },
   bug_spotter: { counter: "errors_seen", threshold: 1 },
   error_whisperer: { counter: "errors_seen", threshold: 25 },
   battle_scarred: { counter: "errors_seen", threshold: 100 },
+  error_titan: { counter: "errors_seen", threshold: 500 },
+  error_god: { counter: "errors_seen", threshold: 1000 },
+  error_apocalypse: { counter: "errors_seen", threshold: 5000 },
   test_witness: { counter: "tests_failed", threshold: 1 },
   test_veteran: { counter: "tests_failed", threshold: 50 },
+  test_survivor: { counter: "tests_failed", threshold: 200 },
+  test_masochist: { counter: "tests_failed", threshold: 500 },
+  test_immortal: { counter: "tests_failed", threshold: 1000 },
   big_mover: { counter: "large_diffs", threshold: 1 },
   refactor_machine: { counter: "large_diffs", threshold: 10 },
+  massive_mover: { counter: "large_diffs", threshold: 25 },
+  earth_mover: { counter: "large_diffs", threshold: 50 },
+  continental_drift: { counter: "large_diffs", threshold: 100 },
+  tectonic_shift: { counter: "large_diffs", threshold: 250 },
   chatterbox: { counter: "reactions_given", threshold: 100 },
+  social_butterfly: { counter: "reactions_given", threshold: 250 },
+  hypersocial: { counter: "reactions_given", threshold: 500 },
+  never_shuts_up: { counter: "reactions_given", threshold: 1000 },
+  chatterbox_elite: { counter: "reactions_given", threshold: 2500 },
+  no_off_switch: { counter: "reactions_given", threshold: 5000 },
   week_streak: { counter: "days_active", threshold: 7 },
+  two_week_streak: { counter: "days_active", threshold: 14 },
   month_streak: { counter: "days_active", threshold: 30 },
+  quarter_streak: { counter: "days_active", threshold: 90 },
+  hundred_days: { counter: "days_active", threshold: 100 },
+  year_streak: { counter: "days_active", threshold: 365 },
   power_user: { counter: "commands_run", threshold: 50 },
+  commander: { counter: "commands_run", threshold: 200 },
+  command_overlord: { counter: "commands_run", threshold: 500 },
+  command_addict: { counter: "commands_run", threshold: 1000 },
+  command_deity: { counter: "commands_run", threshold: 2500 },
   dedicated: { counter: "turns", threshold: 200 },
   thousand_turns: { counter: "turns", threshold: 1000 },
+  five_thousand_turns: { counter: "turns", threshold: 5000 },
+  ten_thousand_turns: { counter: "turns", threshold: 10000 },
+  twenty_five_k_turns: { counter: "turns", threshold: 25000 },
+  fifty_k_turns: { counter: "turns", threshold: 50000 },
+  session_regular: { counter: "sessions", threshold: 10 },
+  session_veteran: { counter: "sessions", threshold: 50 },
+  session_centurion: { counter: "sessions", threshold: 100 },
+  session_addict: { counter: "sessions", threshold: 250 },
+  session_machine: { counter: "sessions", threshold: 500 },
+  collector: { counter: "buddies_collected", threshold: 3 },
+  zookeeper: { counter: "buddies_collected", threshold: 5 },
+  menagerie: { counter: "buddies_collected", threshold: 10 },
+  buddy_hoarder: { counter: "buddies_collected", threshold: 20 },
+  buddy_tycoon: { counter: "buddies_collected", threshold: 50 },
+  identity_crisis: { counter: "renames", threshold: 1 },
+  name_chameleon: { counter: "renames", threshold: 5 },
+  serial_renamer: { counter: "renames", threshold: 10 },
+  identity_thief: { counter: "renames", threshold: 25 },
+  method_acting: { counter: "personalities_set", threshold: 1 },
+  fashionista: { counter: "personalities_set", threshold: 3 },
+  personality_crisis: { counter: "personalities_set", threshold: 10 },
+  silent_treatment: { counter: "mutes", threshold: 1 },
+  prodigal: { counter: "summons", threshold: 1 },
+  menagerie_hop: { counter: "summons", threshold: 10 },
+  menagerie_hopper: { counter: "summons", threshold: 25 },
+  summoner: { counter: "summons", threshold: 50 },
+  heartbreaker: { counter: "dismissals", threshold: 1 },
+  serial_dumper: { counter: "dismissals", threshold: 5 },
+  cold_blooded: { counter: "dismissals", threshold: 10 },
+  show_off: { counter: "shows", threshold: 10 },
+  exhibitionist: { counter: "shows", threshold: 50 },
+  help_me: { counter: "helps", threshold: 1 },
+  help_addict: { counter: "helps", threshold: 10 },
+  achievement_hunter: { counter: "achievement_views", threshold: 5 },
+  achievement_stalker: { counter: "achievement_views", threshold: 25 },
+  pack_rat: { counter: "saves", threshold: 1 },
+  compulsive_saver: { counter: "saves", threshold: 10 },
+  roster_check: { counter: "lists", threshold: 1 },
+  roster_obsessed: { counter: "lists", threshold: 10 },
+  completionist: { counter: "achievements_unlocked", threshold: ACHIEVEMENTS.length - 1 },
+  // Compound checks (multiple counters) — no single-counter progress bar.
+  on_off: null,
+  indecisive: null,
+  troubled: null,
+  disaster_zone: null,
+  apocalypse_survivor: null,
+  well_rounded: null,
+  renaissance: null,
+  big_and_broken: null,
+  collector_and_destroyer: null,
 };
 
-function AchievementsListPane({ cursor, unlockedIds, focused }: {
-  cursor: number; unlockedIds: Set<string>; focused: boolean;
+function AchievementsListPane({ cursor, unlockedIds, focused, rows }: {
+  cursor: number; unlockedIds: Set<string>; focused: boolean; rows: number;
 }) {
   const total = ACHIEVEMENTS.length;
   const done = ACHIEVEMENTS.filter(a => unlockedIds.has(a.id)).length;
+
+  // Each bordered row costs ~3 lines; header + indicators + chrome ~8.
+  const visibleCount = Math.max(3, Math.min(total, Math.floor((rows - 8) / 3)));
+  let start = cursor - Math.floor(visibleCount / 2);
+  start = Math.max(0, Math.min(start, total - visibleCount));
+  const end = Math.min(total, start + visibleCount);
+  const above = start;
+  const below = total - end;
+
   return (
     <Box flexDirection="column" paddingX={1}>
       <Text bold color={focused ? "cyan" : "gray"}>{" 🏆 Achievements"}</Text>
       <Text dimColor>{"  "}{done}/{total} unlocked</Text>
       <Text>{""}</Text>
-      {ACHIEVEMENTS.map((a, i) => {
+      {above > 0 ? <Text dimColor>{"  ▲ "}{above}{" more"}</Text> : null}
+      {ACHIEVEMENTS.slice(start, end).map((a, i) => {
+        const absIdx = start + i;
         const isUnlocked = unlockedIds.has(a.id);
         const isHidden = a.secret && !isUnlocked;
-        const isCursor = focused && i === cursor;
+        const isCursor = focused && absIdx === cursor;
         const name = isHidden ? "???" : a.name;
         const icon = isHidden ? "🔒" : a.icon;
         return (
@@ -350,6 +438,7 @@ function AchievementsListPane({ cursor, unlockedIds, focused }: {
           </Box>
         );
       })}
+      {below > 0 ? <Text dimColor>{"  ▼ "}{below}{" more"}</Text> : null}
     </Box>
   );
 }
@@ -695,7 +784,7 @@ function BackupDetailPane({ backups, cursor }: {
         <Text bold color="cyan">➕ Create Backup</Text>
         <Text>{""}</Text>
         <Text dimColor>Creates a snapshot of all</Text>
-        <Text dimColor>claude-buddy state files:</Text>
+        <Text dimColor>coding-buddy state files:</Text>
         <Text>{""}</Text>
         <Text>{" "}• settings.json</Text>
         <Text>{" "}• MCP server config</Text>
@@ -857,7 +946,7 @@ function EnableDetailPane({ result, running }: {
   return (
     <Box flexDirection="column" paddingLeft={1}>
       <Text>{""}</Text>
-      <Text bold color="green">🔄 Re-Enable claude-buddy</Text>
+      <Text bold color="green">🔄 Re-Enable coding-buddy</Text>
       <Text>{""}</Text>
       <Text dimColor>This will register:</Text>
       <Text>{"  "}• MCP server in {CLAUDE_JSON}</Text>
@@ -913,7 +1002,7 @@ function UninstallDetailPane({ stage, typed, result, keepState }: {
   return (
     <Box flexDirection="column" paddingLeft={1}>
       <Text>{""}</Text>
-      <Text bold color="red">💥 Uninstall claude-buddy</Text>
+      <Text bold color="red">💥 Uninstall coding-buddy</Text>
       <Text>{""}</Text>
       <Text color="yellow">⚠  This will remove:</Text>
       <Text>{"  "}• MCP server registration</Text>
@@ -956,7 +1045,7 @@ function DisableConfirmPane({ result, confirming }: {
   return (
     <Box flexDirection="column" paddingLeft={1}>
       <Text>{""}</Text>
-      <Text bold color="red">☠ Disable claude-buddy</Text>
+      <Text bold color="red">☠ Disable coding-buddy</Text>
       <Text>{""}</Text>
       <Text dimColor>This will remove:</Text>
       <Text>{"  "}• MCP server from {CLAUDE_JSON}</Text>
@@ -1018,7 +1107,7 @@ function disableBuddy(): DisableResult {
         if (settings.hooks[hookType]) {
           const before = settings.hooks[hookType].length;
           settings.hooks[hookType] = settings.hooks[hookType].filter(
-            (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("claude-buddy")),
+            (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("coding-buddy") || hh.command?.includes("claude-buddy")),
           );
           if (settings.hooks[hookType].length < before) changed = true;
           if (settings.hooks[hookType].length === 0) delete settings.hooks[hookType];
@@ -2100,7 +2189,7 @@ function App() {
       middlePane = <SettingsListPane cursor={settCursor} config={config} focused={focus === "list"} />;
       rightPane = <SettingDetailPane settingIndex={settCursor} config={config} editing={focus === "edit"} numInput={numInput} optCursor={optCursor} />;
     } else if (section === "achievements") {
-      middlePane = <AchievementsListPane cursor={listCursor} unlockedIds={unlockedIds} focused={focus === "list"} />;
+      middlePane = <AchievementsListPane cursor={listCursor} unlockedIds={unlockedIds} focused={focus === "list"} rows={rows} />;
       if (ACHIEVEMENTS[listCursor]) {
         rightPane = <AchievementDetailPane
           achievement={ACHIEVEMENTS[listCursor]}
@@ -2205,7 +2294,7 @@ function App() {
   return (
     <Box flexDirection="column" height={rows}>
       <Box>
-        <Text color="cyan" bold>{"─ claude-buddy "}{"─".repeat(Math.max(0, cols - 17))}</Text>
+        <Text color="cyan" bold>{"─ coding-buddy "}{"─".repeat(Math.max(0, cols - 17))}</Text>
       </Box>
       <Box flexGrow={1}>
         <Box width={sidebarWidth} flexDirection="column" borderStyle="single" borderColor={focus === "sidebar" ? "cyan" : "gray"}>
@@ -2237,7 +2326,7 @@ function App() {
 // ─── Entry ──────────────────────────────────────────────────────────────────
 
 if (!process.stdin.isTTY) {
-  console.error("claude-buddy tui requires an interactive terminal (TTY)");
+  console.error("coding-buddy tui requires an interactive terminal (TTY)");
   process.exit(1);
 }
 

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

@@ -1,32 +1,15 @@
-#!/usr/bin/env bun
 /**
- * claude-buddy uninstall — remove all integrations
+ * coding-buddy uninstall — remove all integrations
  */
 
 import { readFileSync, writeFileSync, existsSync, rmSync, readdirSync } from "fs";
 import { join } from "path";
-import { cleanupPluginState } from "../storage/settings.ts";
-import { getBuddySkillDir, getBuddyStateDir, getClaudeJsonPath, getClaudeSettingsPath } from "../storage/paths.ts";
-
-interface HookCommand {
-  type: "command";
-  command: string;
-}
-
-interface HookMatcherEntry {
-  matcher?: string;
-  hooks?: HookCommand[];
-}
-
-interface ClaudeSettings {
-  statusLine?: { command?: string };
-  hooks?: Record<string, HookMatcherEntry[]>;
-  [key: string]: unknown;
-}
-
-function hasBuddyHook(entry: HookMatcherEntry): boolean {
-  return (entry.hooks ?? []).some((hook) => hook.command.includes("claude-buddy"));
-}
+import {
+  buddyStateDir,
+  claudeSettingsPath,
+  claudeSkillDir,
+  claudeUserConfigPath,
+} from "../server/path.ts";
 
 const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
@@ -35,47 +18,56 @@ const NC = "\x1b[0m";
 function ok(msg: string) { console.log(`${GREEN}✓${NC}  ${msg}`); }
 function warn(msg: string) { console.log(`${YELLOW}⚠${NC}  ${msg}`); }
 
-const SETTINGS_FILE = getClaudeSettingsPath();
-const SKILL_DIR = getBuddySkillDir();
-const STATE_DIR = getBuddyStateDir();
-const CLAUDE_JSON = getClaudeJsonPath();
+const SETTINGS_FILE = claudeSettingsPath();
+const SKILL_DIR = claudeSkillDir("buddy");
+const STATE_DIR = buddyStateDir();
+const CLAUDE_JSON_PATH = claudeUserConfigPath();
 
-console.log("\nclaude-buddy uninstall\n");
+console.log("\ncoding-buddy uninstall\n");
 
+// Stop all popup reopen loops and close any running popup
 try {
   if (existsSync(STATE_DIR)) {
-    for (const f of readdirSync(STATE_DIR).filter((f) => f.startsWith("popup-reopen-pid."))) {
+    // Kill all session popup loops (popup-reopen-pid.*)
+    for (const f of readdirSync(STATE_DIR).filter(f => f.startsWith("popup-reopen-pid."))) {
       const pidPath = join(STATE_DIR, f);
       const pid = parseInt(readFileSync(pidPath, "utf8").trim(), 10);
-      if (pid > 0) {
-        try { process.kill(pid); } catch {}
-      }
+      if (pid > 0) { try { process.kill(pid); } catch { /* already dead */ } }
       rmSync(pidPath, { force: true });
     }
+    // Clean up all session-scoped files
+    const patterns = ["popup-stop.", "popup-resize.", "popup-env.", "popup-scroll.",
+                      "reaction.", ".last_reaction.", ".last_comment."];
+    for (const f of readdirSync(STATE_DIR)) {
+      if (patterns.some(p => f.startsWith(p))) {
+        rmSync(join(STATE_DIR, f), { force: true });
+      }
+    }
   }
+  // Close any open popup
   if (process.env.TMUX) {
     const { execSync } = await import("child_process");
     execSync("tmux display-popup -C 2>/dev/null", { stdio: "ignore" });
   }
   ok("Popup stopped");
-} catch {
-  // noop
-}
+} catch { /* not in tmux or no popup */ }
 
+// Remove MCP server from Claude's user config
 try {
-  const claudeJson = JSON.parse(readFileSync(CLAUDE_JSON, "utf8"));
+  const claudeJson = JSON.parse(readFileSync(CLAUDE_JSON_PATH, "utf8"));
   if (claudeJson.mcpServers?.["claude-buddy"]) {
     delete claudeJson.mcpServers["claude-buddy"];
     if (Object.keys(claudeJson.mcpServers).length === 0) delete claudeJson.mcpServers;
-    writeFileSync(CLAUDE_JSON, JSON.stringify(claudeJson, null, 2));
-    ok(`MCP server removed from ${CLAUDE_JSON}`);
+    writeFileSync(CLAUDE_JSON_PATH, JSON.stringify(claudeJson, null, 2));
+    ok(`MCP server removed from ${CLAUDE_JSON_PATH}`);
   }
 } catch {
-  warn(`Could not update ${CLAUDE_JSON}`);
+  warn(`Could not update ${CLAUDE_JSON_PATH}`);
 }
 
+// Remove hooks and statusline from settings.json
 try {
-  const settings = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as ClaudeSettings;
+  const settings = JSON.parse(readFileSync(SETTINGS_FILE, "utf8"));
   let changed = false;
 
   if (settings.statusLine?.command?.includes("buddy")) {
@@ -87,7 +79,9 @@ try {
   for (const hookType of ["PostToolUse", "Stop", "SessionStart", "SessionEnd", "UserPromptSubmit"] as const) {
     if (settings.hooks?.[hookType]) {
       const before = settings.hooks[hookType].length;
-      settings.hooks[hookType] = settings.hooks[hookType].filter((h) => !hasBuddyHook(h));
+      settings.hooks[hookType] = settings.hooks[hookType].filter(
+        (h: any) => !h.hooks?.some((hh: any) => hh.command?.includes("coding-buddy") || hh.command?.includes("claude-buddy")),
+      );
       if (settings.hooks[hookType].length < before) {
         ok(`${hookType} hooks removed`);
         changed = true;
@@ -104,11 +98,7 @@ try {
   warn("Could not update settings.json");
 }
 
-const cleanup = cleanupPluginState(SETTINGS_FILE, STATE_DIR);
-if (cleanup.transientFilesRemoved > 0) {
-  ok(`Removed ${cleanup.transientFilesRemoved} transient session files`);
-}
-
+// Remove skill
 if (existsSync(SKILL_DIR)) {
   rmSync(SKILL_DIR, { recursive: true });
   ok("Skill removed");
@@ -116,6 +106,9 @@ if (existsSync(SKILL_DIR)) {
   warn("Skill not found (already removed)");
 }
 
+// Keep state dir (companion data) — user might want it back.
+// This is profile-scoped when CLAUDE_CONFIG_DIR is set, so other
+// profiles' buddies are unaffected.
 if (existsSync(STATE_DIR)) {
   warn(`Companion data kept at ${STATE_DIR} — delete manually if not needed`);
 }

package/cli/upgrade.ts

@@ -40,7 +40,7 @@ function getCurrentVersion(): string {
 function banner() {
   console.log(`
 ${CYAN}╔══════════════════════════════════════════════════════════╗${NC}
-${CYAN}║${NC}  ${BOLD}claude-buddy upgrade${NC}                                    ${CYAN}║${NC}
+${CYAN}║${NC}  ${BOLD}coding-buddy upgrade${NC}                                    ${CYAN}║${NC}
 ${CYAN}╚══════════════════════════════════════════════════════════╝${NC}
 `);
 }
@@ -48,7 +48,7 @@ ${CYAN}╚═══════════════════════
 function checkGitRepo(): boolean {
   const isRepo = tryExec("git rev-parse --is-inside-work-tree 2>/dev/null");
   if (isRepo !== "true") {
-    err("Not inside a git repository. Upgrade requires a git clone of claude-buddy.");
+    err("Not inside a git repository. Upgrade requires a git clone of coding-buddy.");
     return false;
   }
   return true;

package/cli/validate-species.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env bun
+/**
+ * Validate species art format.
+ *
+ * Usage:
+ *   bun run cli/validate-species.ts <path>
+ *   bun run cli/validate-species.ts --check-species <name>
+ *
+ * Exits 0 if valid, 1 if invalid (with error messages to stderr).
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+const EYE_PLACEHOLDER = "{E}";
+
+/** Check a string for ANSI escape sequences */
+function hasAnsiCodes(s: string): boolean {
+  return s.includes("\x1b[");
+}
+
+/** Strip ANSI codes from a string */
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[^m]*m/g, "");
+}
+
+/** Validate a single art frame (must be exactly 5 lines) */
+function validateFrame(
+  species: string,
+  frameIndex: number,
+  lines: string[],
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (lines.length !== 5) {
+    errors.push(
+      `  Species "${species}" frame ${frameIndex}: expected 5 lines, got ${lines.length}`,
+    );
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const rawLen = line.length;
+    const displayLen = stripAnsi(line).length;
+
+    if (hasAnsiCodes(line)) {
+      errors.push(
+        `  Species "${species}" frame ${frameIndex} line ${i + 1}: contains ANSI escape sequences (not allowed)`,
+      );
+    }
+
+    if (displayLen > 14) {
+      errors.push(
+        `  Species "${species}" frame ${frameIndex} line ${i + 1}: display width ${displayLen} exceeds max 14 chars`,
+      );
+    }
+
+    // Each species art should have the eye placeholder in at least one line
+    // (not strictly required but warn if missing)
+    if (!line.includes(EYE_PLACEHOLDER) && i === 1) {
+      warnings.push(
+        `  Species "${species}" frame ${frameIndex} line ${i + 1}: missing ${EYE_PLACEHOLDER} eye placeholder (recommended for line 2)`,
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/** Validate art structure from parsed JSON */
+function validateSpeciesArt(
+  species: string,
+  art: string[][],
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!Array.isArray(art)) {
+    errors.push(`Species "${species}": art must be an array of frames`);
+    return { valid: false, errors, warnings };
+  }
+
+  if (art.length !== 3) {
+    errors.push(
+      `Species "${species}": expected 3 animation frames, got ${art.length}`,
+    );
+  }
+
+  for (let i = 0; i < art.length; i++) {
+    const frame = art[i];
+    const result = validateFrame(species, i, frame);
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/** Validate a face template — must contain at least one eye placeholder */
+function validateFaceTemplate(
+  species: string,
+  face: string,
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (face.length > 20) {
+    errors.push(
+      `Species "${species}" face template: display width ${face.length} exceeds max 20 chars`,
+    );
+  }
+
+  if (!face.includes(EYE_PLACEHOLDER)) {
+    errors.push(
+      `Species "${species}" face template: missing ${EYE_PLACEHOLDER} eye placeholder`,
+    );
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Main validation function — validates a species JSON file or inline art.
+ * Returns exit code (0 = valid, 1 = invalid).
+ */
+export function validateSpeciesFile(filePath: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  let data: Record<string, unknown>;
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    data = JSON.parse(raw);
+  } catch (e) {
+    return {
+      valid: false,
+      errors: [`Failed to read or parse JSON file: ${filePath}`],
+      warnings: [],
+    };
+  }
+
+  const species = data.name as string | undefined;
+  if (!species || typeof species !== "string") {
+    errors.push("Species must have a 'name' field (string)");
+  }
+
+  const art = data.art as string[][] | undefined;
+  if (!art) {
+    errors.push("Species must have an 'art' field (string[][] — 3 frames × 5 lines)");
+  } else {
+    const artResult = validateSpeciesArt(species ?? "unknown", art);
+    errors.push(...artResult.errors);
+    warnings.push(...artResult.warnings);
+  }
+
+  const face = data.face as string | undefined;
+  if (face) {
+    const faceResult = validateFaceTemplate(species ?? "unknown", face);
+    errors.push(...faceResult.errors);
+    warnings.push(...faceResult.warnings);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/** Print results and exit with appropriate code */
+function main(): never {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error("Usage: bun run cli/validate-species.ts <path-to-species-json>");
+    console.error("  Validates art format, ANSI codes, and eye placeholder.");
+    console.error("");
+    console.error("Example:");
+    console.error("  bun run cli/validate-species.ts ./my-species.json");
+    process.exit(1);
+  }
+
+  const filePath = args[0].startsWith("/") ? args[0] : join(process.cwd(), args[0]);
+  const result = validateSpeciesFile(filePath);
+
+  if (result.warnings.length > 0) {
+    console.warn("Warnings:");
+    for (const w of result.warnings) {
+      console.warn(w);
+    }
+    console.warn("");
+  }
+
+  if (result.valid) {
+    console.log(`✓ ${args[0]}: valid`);
+    process.exit(0);
+  } else {
+    console.error("Errors:");
+    for (const e of result.errors) {
+      console.error(e);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/cli/verify.ts

@@ -1,9 +1,9 @@
 /**
- * claude-buddy verify — show what buddy a user ID produces
+ * coding-buddy verify — show what buddy a user ID produces
  */
 
-import { generateBones, renderBuddy, STAT_NAMES } from "../core/engine.ts";
-import { resolveUserId } from "../adapters/claude/storage/identity.ts";
+import { generateBones, renderBuddy, STAT_NAMES } from "../core/engine.ts"
+import { resolveUserId } from "../server/state.ts";
 
 const userId = process.argv[3] || resolveUserId();