@umang-boss/claudemon 1.2.1 → 1.4.0

package/dist/src/server/tools/train.js

@@ -0,0 +1,144 @@
+/**
+ * buddy_train tool — Train your active Pokemon's coding stats.
+ * Has a 30-minute cooldown. Awards +3 to a stat and +5 XP.
+ */
+import { z } from "zod";
+import { CODING_STATS } from "../../engine/types.js";
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { STAT_DISPLAY_NAMES } from "../../engine/constants.js";
+import { addXp } from "../../engine/xp.js";
+import { applyStatBoost, renderStatBar } from "../../engine/stats.js";
+import { StateManager } from "../../state/state-manager.js";
+/** Cooldown: 30 minutes in milliseconds. */
+const TRAIN_COOLDOWN_MS = 1_800_000;
+/** Stat boost per training session. */
+const TRAIN_STAT_BOOST = 3;
+/** XP awarded per training session. */
+const TRAIN_XP_AWARD = 5;
+/** Pick a random element from a non-empty array. */
+function randomPick(arr) {
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index];
+}
+/** Format remaining cooldown as "Xm Ys". */
+function formatCooldownRemaining(remainingMs) {
+    const totalSeconds = Math.ceil(remainingMs / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes > 0 && seconds > 0) {
+        return `${minutes}m ${seconds}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+/** Registers the buddy_train tool on the MCP server. */
+export function registerTrainTool(server) {
+    server.tool("buddy_train", "Train your active Pokemon's coding stats. Optionally specify a stat (debugging, stability, velocity, wisdom, stamina). 30-minute cooldown.", {
+        stat: z
+            .string()
+            .optional()
+            .describe("Stat to train: debugging, stability, velocity, wisdom, or stamina. Random if omitted."),
+    }, async ({ stat: statInput }) => {
+        const stateManager = StateManager.getInstance();
+        const state = await stateManager.load();
+        if (!state || state.party.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You don't have a Pokemon yet! Use buddy_starter to pick your first companion.",
+                    },
+                ],
+            };
+        }
+        const active = stateManager.getActivePokemon();
+        if (!active) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No active Pokemon found. Use buddy_party to set one active.",
+                    },
+                ],
+            };
+        }
+        const species = POKEMON_BY_ID.get(active.pokemonId);
+        if (!species) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Could not find species data for Pokemon ID ${active.pokemonId}.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Check cooldown
+        const now = Date.now();
+        const elapsed = now - state.lastTrainedAt;
+        if (elapsed < TRAIN_COOLDOWN_MS) {
+            const remaining = TRAIN_COOLDOWN_MS - elapsed;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Still resting from training! Try again in ${formatCooldownRemaining(remaining)}.`,
+                    },
+                ],
+            };
+        }
+        // Determine which stat to train
+        let targetStat;
+        if (statInput !== undefined && statInput !== "") {
+            const normalized = statInput.toLowerCase().trim();
+            if (!CODING_STATS.includes(normalized)) {
+                const validStats = CODING_STATS.map((s) => STAT_DISPLAY_NAMES[s].toLowerCase()).join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid stat "${statInput}". Valid stats: ${validStats}`,
+                        },
+                    ],
+                };
+            }
+            targetStat = normalized;
+        }
+        else {
+            targetStat = randomPick(CODING_STATS);
+        }
+        const displayName = active.nickname ?? species.name;
+        // Record stat before boost for display
+        const statBefore = active.codingStats[targetStat];
+        // Apply stat boost
+        applyStatBoost(active, targetStat, TRAIN_STAT_BOOST);
+        const statAfter = active.codingStats[targetStat];
+        // Award XP
+        const levelUp = addXp(active, TRAIN_XP_AWARD, species);
+        // Set mood to energetic
+        state.mood = "energetic";
+        state.moodSetAt = now;
+        // Record train timestamp
+        state.lastTrainedAt = now;
+        // Save state and update status line
+        await stateManager.save();
+        await stateManager.writeStatus();
+        // Build response
+        const statDisplayName = STAT_DISPLAY_NAMES[targetStat];
+        const lines = [];
+        lines.push(`*${displayName} trains its ${statDisplayName}! +${TRAIN_STAT_BOOST}*`);
+        lines.push("");
+        lines.push(`${statDisplayName}: ${statBefore} \u2192 ${statAfter}  ${renderStatBar(statAfter)}`);
+        lines.push(`+${TRAIN_XP_AWARD} XP`);
+        if (levelUp) {
+            lines.push("");
+            lines.push(`*** ${displayName} grew to Lv.${levelUp.newLevel}! ***`);
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+}

package/dist/src/state/schemas.js

@@ -3,7 +3,7 @@
  * Catches disk corruption early at load boundaries.
  */
 import { z } from "zod";
-import { BADGE_TYPES, CODING_STATS, EVENT_COUNTER_KEYS, } from "../engine/types.js";
+import { BADGE_TYPES, CODING_STATS, EVENT_COUNTER_KEYS, MOOD_TYPES, } from "../engine/types.js";
 // ---- Shared Primitives ----
 const BadgeTypeSchema = z.enum(BADGE_TYPES);
 // ---- Coding Stats ----
@@ -47,6 +47,7 @@ export const BuddyConfigSchema = z.object({
     reactionCooldownMs: z.number().int().min(0).default(30_000),
     statusLineEnabled: z.boolean().default(true),
     bellEnabled: z.boolean().default(true),
+    encounterSpeed: z.enum(["fast", "normal", "slow"]).default("normal"),
 });
 // ---- Pokedex ----
 export const PokedexEntrySchema = z.object({
@@ -65,6 +66,13 @@ export const UnlockedAchievementSchema = z.object({
     achievementId: z.string(),
     unlockedAt: z.string(),
 });
+// ---- Pending Quiz ----
+export const PendingQuizSchema = z.object({
+    type: z.enum(["type_matchup", "stat_compare", "evolution", "pokedex_trivia"]),
+    question: z.string(),
+    options: z.array(z.string()),
+    correctAnswer: z.number().int().min(1).max(4),
+});
 // ---- Catch Condition ----
 export const CatchConditionSchema = z.object({
     requiredStat: z.enum(CODING_STATS).nullable(),
@@ -94,4 +102,12 @@ export const PlayerStateSchema = z.object({
     totalSessions: z.number().int().min(0).default(0),
     pendingEncounter: WildEncounterSchema.nullable().default(null),
     xpSinceLastEncounter: z.number().int().min(0).default(0),
+    recentToolTypes: z.array(z.string()).default([]),
+    lastEncounterTime: z.number().int().min(0).default(0),
+    mood: z.enum(MOOD_TYPES).default("neutral"),
+    moodSetAt: z.number().default(0),
+    lastFedAt: z.number().default(0),
+    lastTrainedAt: z.number().default(0),
+    lastPlayedAt: z.number().default(0),
+    pendingQuiz: PendingQuizSchema.nullable().default(null),
 });

package/dist/src/state/state-manager.js

@@ -30,6 +30,7 @@ function defaultConfig() {
         reactionCooldownMs: 30_000,
         statusLineEnabled: true,
         bellEnabled: true,
+        encounterSpeed: "normal",
     };
 }
 /** Build empty pokedex */
@@ -150,6 +151,14 @@ export class StateManager {
             totalSessions: 0,
             pendingEncounter: null,
             xpSinceLastEncounter: 0,
+            recentToolTypes: [],
+            lastEncounterTime: 0,
+            mood: "neutral",
+            moodSetAt: 0,
+            lastFedAt: 0,
+            lastTrainedAt: 0,
+            lastPlayedAt: 0,
+            pendingQuiz: null,
         };
         this.state = state;
         await this.save();
@@ -168,17 +177,19 @@ export class StateManager {
         state.counters[key] += amount;
         await this.save();
     }
-    /** Update daily streak based on today vs lastActiveDate, then save */
+    /**
+     * Update daily streak with weekend grace period.
+     * Allows up to 2 days off without breaking the streak (covers weekends).
+     * Streak counts "coding days" not "consecutive calendar days".
+     */
     async updateStreak() {
         const state = this.getState();
         const today = todayDateString();
         const { streak } = state;
         if (streak.lastActiveDate === today) {
-            // Already recorded today, nothing to do
             return;
         }
         if (streak.lastActiveDate === null) {
-            // First ever activity
             streak.currentStreak = 1;
             streak.totalDaysActive = 1;
         }
@@ -187,12 +198,15 @@ export class StateManager {
             const now = new Date(today);
             const diffMs = now.getTime() - last.getTime();
             const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));
-            if (diffDays === 1) {
-                // Consecutive day
+            // Grace period: up to 2 days off (covers weekends)
+            // 1 day gap = next day (consecutive) ✓
+            // 2 day gap = skipped 1 day (e.g., Friday → Sunday) ✓
+            // 3 day gap = skipped 2 days (e.g., Friday → Monday) ✓
+            // 4+ day gap = streak broken
+            if (diffDays <= 3) {
                 streak.currentStreak += 1;
             }
             else {
-                // Streak broken
                 streak.currentStreak = 1;
             }
             streak.totalDaysActive += 1;
@@ -209,6 +223,7 @@ export class StateManager {
         if (!active) {
             return;
         }
+        const state = this.getState();
         // XP percent is currentXp as a rough percentage toward next level
         // Exact formula depends on exp group; use a simple ratio for the status line
         const xpPercent = active.level >= 100 ? 100 : Math.min(100, Math.floor((active.currentXp / Math.max(1, active.currentXp + 50)) * 100));
@@ -225,6 +240,7 @@ export class StateManager {
             xpPercent,
             speciesId: active.pokemonId,
             evolutionReady,
+            mood: state.mood ?? "neutral",
         };
         const stateDir = getStateDir();
         await ensureDir(stateDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umang-boss/claudemon",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Pokemon coding companion for Claude Code — Gotta code 'em all!",
   "type": "module",
   "main": "dist/src/server/index.js",
@@ -33,8 +33,7 @@
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"src/**/*.ts\" \"cli/**/*.ts\" \"scripts/**/*.ts\" \"tests/**/*.ts\" --ignore-unknown",
-    "format:check": "prettier --check \"src/**/*.ts\" \"cli/**/*.ts\" \"scripts/**/*.ts\" \"tests/**/*.ts\" --ignore-unknown",
-    "prepare": "husky"
+    "format:check": "prettier --check \"src/**/*.ts\" \"cli/**/*.ts\" \"scripts/**/*.ts\" \"tests/**/*.ts\" --ignore-unknown"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/skills/buddy/SKILL.md

@@ -41,6 +41,21 @@ This ensures first-time users get the starter selection flow automatically.
 | `rename` (empty) | `buddy_rename` with name="" — reset to species name |
 | `hide` | `buddy_hide` — hide sprite from status line |
 | `unhide` | `buddy_unhide` — show sprite in status line |
+| `feed` | `buddy_feed` — feed your Pokemon (+10 happiness, 1h cooldown) |
+| `train` | `buddy_train` — train a random stat (+3 stat, +5 XP, 30m cooldown) |
+| `train debugging` | `buddy_train` with stat="debugging" |
+| `train stability` | `buddy_train` with stat="stability" |
+| `train velocity` | `buddy_train` with stat="velocity" |
+| `train wisdom` | `buddy_train` with stat="wisdom" |
+| `train stamina` | `buddy_train` with stat="stamina" |
+| `play` | `buddy_play` — start a Pokemon trivia quiz (15m cooldown after completion) |
+| `play answer 1` | `buddy_play` with answer=1 |
+| `play answer 2` | `buddy_play` with answer=2 |
+| `play answer 3` | `buddy_play` with answer=3 |
+| `play answer 4` | `buddy_play` with answer=4 |
+| `settings encounter-speed fast` | `buddy_settings` with setting="encounter-speed", value="fast" — fastest encounters (100 XP) |
+| `settings encounter-speed normal` | `buddy_settings` with setting="encounter-speed", value="normal" — default (250 XP) |
+| `settings encounter-speed slow` | `buddy_settings` with setting="encounter-speed", value="slow" — less interruptions (500 XP) |
 | `help` | List all available /buddy commands |
 
 Pass $ARGUMENTS to determine which subcommand to route to.

package/src/engine/constants.ts

@@ -46,8 +46,17 @@ export const STAT_DISPLAY_NAMES: Record<CodingStat, string> = {
 
 // ── Encounter Rate ─────────────────────────────────────────
 
-/** XP earned between wild encounters */
-export const XP_PER_ENCOUNTER = 500;
+/** XP thresholds for encounter triggers by speed setting */
+export const ENCOUNTER_THRESHOLDS = {
+  fast: 100,
+  normal: 250,
+  slow: 500,
+} as const;
+
+export type EncounterSpeed = keyof typeof ENCOUNTER_THRESHOLDS;
+
+/** Default encounter speed */
+export const DEFAULT_ENCOUNTER_SPEED: EncounterSpeed = "normal";
 
 // ── Reaction Cooldown ──────────────────────────────────────
 
@@ -92,7 +101,7 @@ export const BADGES: readonly Badge[] = [
   {
     type: "lunar",
     name: "Lunar Badge",
-    description: "Maintain a 30-day coding streak — unlocks Moon Stone evolutions",
+    description: "Code for 30 days (weekends off OK) — unlocks Moon Stone evolutions",
     condition: { type: "streak", minDays: 30 },
   },
   {

package/src/engine/encounters.ts

@@ -1,7 +1,8 @@
 /**
  * Wild encounter system.
- * Pokemon appear based on coding activity type and are catchable
- * based on the active Pokemon's stats and level.
+ * Pokemon appear based on coding activity type, streak bonuses,
+ * tool diversity, and time-of-day biases. Catch eligibility is
+ * determined by the active Pokemon's stats and level.
  */
 
 import type {
@@ -14,7 +15,8 @@ import type {
   CodingStat,
   RarityTier,
 } from "./types.js";
-import { XP_PER_ENCOUNTER } from "./constants.js";
+import { ENCOUNTER_THRESHOLDS } from "./constants.js";
+import type { EncounterSpeed } from "./constants.js";
 import { POKEMON_BY_ID } from "./pokemon-data.js";
 import { TYPE_POOLS } from "./encounter-pool.js";
 
@@ -41,14 +43,55 @@ export function getEncounterTypes(eventType: XpEventType): readonly PokemonType[
   return ENCOUNTER_TYPE_MAP[eventType];
 }
 
+// ── Encounter Context ─────────────────────────────────────────
+
+export interface EncounterContext {
+  xpSinceLastEncounter: number;
+  encounterSpeed: EncounterSpeed;
+  currentStreak: number;
+  recentToolTypes: string[]; // tool types used recently
+  currentHour: number; // 0-23
+}
+
 // ── Encounter Trigger ─────────────────────────────────────────
 
 /**
- * Check if a wild encounter should trigger based on XP earned since last encounter.
- * Returns true roughly every XP_PER_ENCOUNTER (500) XP.
+ * Check if a wild encounter should trigger based on XP earned,
+ * encounter speed setting, and streak bonus.
+ * Streak bonus: 7+ day streak halves the threshold.
  */
-export function shouldTriggerEncounter(xpSinceLastEncounter: number): boolean {
-  return xpSinceLastEncounter >= XP_PER_ENCOUNTER;
+export function shouldTriggerEncounter(ctx: EncounterContext): boolean {
+  const threshold = ENCOUNTER_THRESHOLDS[ctx.encounterSpeed];
+
+  // Streak bonus: 7+ day streak = halve the threshold
+  const streakMultiplier = ctx.currentStreak >= 7 ? 0.5 : 1;
+  const effectiveThreshold = Math.floor(threshold * streakMultiplier);
+
+  if (ctx.xpSinceLastEncounter < effectiveThreshold) return false;
+
+  return true;
+}
+
+/** Check for bonus encounter (10% chance after a regular encounter). */
+export function shouldBonusEncounter(): boolean {
+  return Math.random() < 0.1;
+}
+
+/** Check for activity diversity bonus (3+ unique tool types in recent history). */
+export function shouldDiversityBonus(recentToolTypes: string[]): boolean {
+  const uniqueTypes = new Set(recentToolTypes);
+  return uniqueTypes.size >= 3;
+}
+
+// ── Time-of-Day Bias ──────────────────────────────────────────
+
+/** Get time-of-day type biases for encounter generation. */
+export function getTimeOfDayBias(hour: number): PokemonType[] {
+  if (hour >= 22 || hour < 5) return ["Ghost", "Poison"]; // Night: Ghost types
+  if (hour >= 5 && hour < 9) return ["Grass", "Bug"]; // Morning: Grass types
+  if (hour >= 12 && hour < 14) return ["Fire", "Rock"]; // Midday: Fire types
+  if (hour >= 17 && hour < 20) return ["Water", "Flying"]; // Evening: Water types
+  return []; // No bias
 }
 
 // ── Rarity Weights ────────────────────────────────────────────
@@ -235,14 +278,27 @@ function determineEncounterLevel(state: PlayerState, seed: number): number {
 /**
  * Generate a wild encounter based on the activity type.
  * Picks a Pokemon from the matching type pool, weighted by rarity.
- * Excludes Pokemon already in the player's party/box (unless duplicates are common tier).
+ * If time-of-day bias types are provided, there is a 40% chance to
+ * use those types instead of the activity-based types.
+ * Excludes Pokemon already in the player's party/box (unless common tier).
  * Returns null if no eligible Pokemon found.
  */
 export function generateEncounter(
   eventType: XpEventType,
   state: PlayerState,
+  timeOfDayTypes?: readonly PokemonType[],
 ): WildEncounter | null {
-  const types = getEncounterTypes(eventType);
+  let types = getEncounterTypes(eventType);
+
+  // 40% chance to use time-of-day biased types if available
+  if (timeOfDayTypes && timeOfDayTypes.length > 0) {
+    const seed = Math.floor(Date.now() / 1000);
+    const biasRoll = seededRandom(seed + 42);
+    if (biasRoll < 0.4) {
+      types = timeOfDayTypes;
+    }
+  }
+
   const candidates = buildCandidatePool(types, state);
 
   if (candidates.length === 0) return null;

package/src/engine/mood.ts

@@ -0,0 +1,220 @@
+/**
+ * Mood engine for Claudemon.
+ * Pure functions that calculate mood based on recent events, time of day,
+ * and special triggers (evolution, achievements, catches).
+ */
+
+import type { MoodType, EventCounters } from "./types.js";
+
+// ── Mood Decay Durations (milliseconds) ───────────────────
+
+/** How long each mood lasts before decaying back to neutral */
+const MOOD_DECAY_MS: Record<MoodType, number> = {
+  happy: 600_000, // 10 minutes
+  worried: 300_000, // 5 minutes
+  sleepy: Infinity, // Resets based on time-of-day, not duration
+  energetic: 900_000, // 15 minutes
+  proud: 600_000, // 10 minutes
+  neutral: Infinity, // Never decays (it IS the default)
+};
+
+// ── XP Event Types That Trigger Moods ─────────────────────
+
+const POSITIVE_EVENTS = new Set(["test_pass", "build_success", "commit"]);
+
+const NEGATIVE_EVENTS = new Set(["test_fail", "build_fail", "error"]);
+
+// ── Mood Calculation ──────────────────────────────────────
+
+/**
+ * Calculate the current mood based on recent events, time, and special triggers.
+ *
+ * Priority order:
+ * 1. Sleepy (midnight to 5 AM)
+ * 2. Proud (just evolved/achieved/caught)
+ * 3. Worried (recent negative event)
+ * 4. Happy (recent positive event)
+ * 5. Energetic (morning + active streak)
+ * 6. Keep current mood if it hasn't decayed
+ * 7. Neutral (default fallback)
+ *
+ * @param recentEvent - The last XP event type, or null
+ * @param counters - Current event counters (for context)
+ * @param currentHour - Hour of day (0-23)
+ * @param lastMood - The previous mood
+ * @param moodSetAt - Timestamp when last mood was set
+ * @param hadEvolution - Whether the Pokemon just evolved
+ * @param hadAchievement - Whether the player just unlocked an achievement
+ * @param hadCatch - Whether the player just caught a Pokemon
+ * @returns The calculated mood
+ */
+export function calculateMood(
+  recentEvent: string | null,
+  counters: EventCounters,
+  currentHour: number,
+  lastMood: MoodType,
+  moodSetAt: number,
+  hadEvolution: boolean,
+  hadAchievement: boolean,
+  hadCatch: boolean,
+): MoodType {
+  // 1. Sleepy: midnight to 5 AM (hours 0-4)
+  if (currentHour >= 0 && currentHour < 5) {
+    return "sleepy";
+  }
+
+  // 2. Proud: just evolved, achieved, or caught a Pokemon
+  if (hadEvolution || hadAchievement || hadCatch) {
+    return "proud";
+  }
+
+  // 3. Worried: recent negative event
+  if (recentEvent !== null && NEGATIVE_EVENTS.has(recentEvent)) {
+    return "worried";
+  }
+
+  // 4. Happy: recent positive event
+  if (recentEvent !== null && POSITIVE_EVENTS.has(recentEvent)) {
+    return "happy";
+  }
+
+  // 5. Energetic: morning coding (5 AM - 10 AM) with an active streak
+  if (currentHour >= 5 && currentHour < 10) {
+    // Use a simple heuristic: if there have been any sessions, consider it an active streak
+    const hasStreak = counters.sessions > 0;
+    if (hasStreak) {
+      return "energetic";
+    }
+  }
+
+  // 6. Keep current mood if it hasn't decayed
+  if (!hasMoodDecayed(lastMood, moodSetAt, Date.now())) {
+    return lastMood;
+  }
+
+  // 7. Default fallback
+  return "neutral";
+}
+
+/**
+ * Check whether a mood has expired based on its decay duration.
+ *
+ * @param mood - The mood to check
+ * @param setAt - Timestamp when the mood was set
+ * @param now - Current timestamp
+ * @returns true if the mood has decayed (expired)
+ */
+export function hasMoodDecayed(mood: MoodType, setAt: number, now: number): boolean {
+  const duration = MOOD_DECAY_MS[mood];
+  if (duration === Infinity) {
+    // Sleepy decays when it's no longer midnight-5 AM (handled in calculateMood)
+    // Neutral never decays
+    return false;
+  }
+  return now - setAt >= duration;
+}
+
+// ── Mood Speeches ─────────────────────────────────────────
+
+/** Mood-specific speech lines for the status line. Name placeholder {name} is replaced at call time. */
+const MOOD_SPEECHES: Record<MoodType, readonly string[]> = {
+  happy: [
+    "*{name} is beaming with pride!*",
+    "*{name} does a little victory dance*",
+    "*{name} radiates positive energy*",
+    "*{name} bounces happily*",
+    "*{name} gives you a thumbs up*",
+  ],
+  worried: [
+    "*{name} looks concerned...*",
+    "*{name} nervously watches the errors*",
+    "*{name} hides behind the terminal*",
+    "*{name} paces back and forth*",
+    "*{name} offers you a virtual hug*",
+  ],
+  sleepy: [
+    "*{name} yawns widely*",
+    "*{name} dozes off... zzz*",
+    "*{name} rubs its eyes*",
+    "*{name} curls up near the keyboard*",
+    "*{name} mumbles in its sleep*",
+  ],
+  energetic: [
+    "*{name} is fired up! Let's go!*",
+    "*{name} bounces off the walls*",
+    "*{name} can't sit still!*",
+    "*{name} is ready to code all day!*",
+    "*{name} stretches and flexes*",
+  ],
+  proud: [
+    "*{name} puffs up with pride*",
+    "*{name} strikes a victory pose*",
+    "*{name} shows off to everyone*",
+    "*{name} earned bragging rights!*",
+    "*{name} stands tall and proud*",
+  ],
+  neutral: [
+    "*{name} looks at your code curiously*",
+    "*{name} nods along as you type*",
+    "*{name} is watching closely*",
+    "*{name} hums softly*",
+    "*{name} waits patiently*",
+    "*{name} tilts head at the screen*",
+    "*{name} chirps encouragingly*",
+    "*{name} peers at a variable name*",
+  ],
+};
+
+/**
+ * Get mood-specific speech messages with the Pokemon's name filled in.
+ *
+ * @param name - The Pokemon's display name
+ * @param mood - The current mood
+ * @returns Array of speech strings with the name interpolated
+ */
+export function getMoodSpeeches(name: string, mood: MoodType): string[] {
+  const templates = MOOD_SPEECHES[mood];
+  return templates.map((t) => t.replace("{name}", name));
+}
+
+// ── Mood Display Helpers ──────────────────────────────────
+
+/** Emoji representation for each mood */
+const MOOD_EMOJIS: Record<MoodType, string> = {
+  happy: "\u{1F60A}", // 😊
+  worried: "\u{1F61F}", // 😟
+  sleepy: "\u{1F634}", // 😴
+  energetic: "\u{26A1}", // ⚡
+  proud: "\u{1F451}", // 👑
+  neutral: "\u{1F610}", // 😐
+};
+
+/** Human-readable mood descriptions */
+const MOOD_DESCRIPTIONS: Record<MoodType, string> = {
+  happy: "Happy",
+  worried: "Worried",
+  sleepy: "Sleepy",
+  energetic: "Energetic",
+  proud: "Proud",
+  neutral: "Neutral",
+};
+
+/**
+ * Get the emoji for a mood.
+ *
+ * @param mood - The mood type
+ * @returns The emoji string
+ */
+export function getMoodEmoji(mood: MoodType): string {
+  return MOOD_EMOJIS[mood];
+}
+
+/**
+ * Get a human-readable description for a mood.
+ *
+ * @param mood - The mood type
+ * @returns The description string (e.g. "Happy")
+ */
+export function getMoodDescription(mood: MoodType): string {
+  return MOOD_DESCRIPTIONS[mood];
+}