Phase 0: progression state foundations (personaStore + progression util)

Extend the soul schema with level/xp/kills/attributePoints, learnedSkills,
equippedSkills, customSkills, chat.history and an events log — default-filled on
read so the existing v1 roster migrates transparently. Add IndexedDB stores for
skill icons, skill action-art, and per-message chat audio. Add active-hero
selection and a merge-patch helper for hot writes (XP, chat turns). New
web/progression.js holds the XP curve + applyXp + event helpers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/models-to-support.md

@@ -0,0 +1,68 @@
+Prize:
+
+Gradio Workflows
+https://github.com/gradio-app/gradio/tree/main/demo/workflow
+
+Image:
+
+Flux 2 Klein 4B
+https://huggingface.co/spaces/stephenbtl/klein-build-small-starter
+https://huggingface.co/blog/black-forest-labs/flux-2-klein-lora
+
+Voice:
+
+openbmb/VoxCPM
+nemotron 3.5 asr
+
+Text Content / Reasoning / Tool use:
+
+Nemotron 3 Nano 4b
+openbmb/minicpm5-1b and 4.1-8b
+
+
+Coding:
+Nemotron 3 Nano 30b-a3b
+nemotron cascade 2 30b-a3b
+mellum2
+
+multimodal:
+minicpm-v-4.6 / minicpm
+nemotron 3 nano omni 30b-a3b
+
+docs / transcribe:
+tiny-aya / cohere-transcribe
+nemotron parse v1.2
+
+safety:
+nemotron 3.5 content safety
+
+
+openbmb:
+Hi everyone, I'm Zhong from OpenBMB! 👋
+Would you like to win $10,000 OpenBMB Special Awards?
+We're offering $10K in special prizes for the best projects built with MiniCPM models in the Build Small Hackathon, $5K for each track!
+Whether you're participating in Backyard AI or Thousand Token Wood, using MiniCPM models can give you a strong edge.
+Useful Resouces:
+OpenBMB Model Collections: https://huggingface.co/openbmb/collections
+OpenBMB GitHub : https://github.com/OpenBMB
+OpenBMB X: https://x.com/OpenBMB
+OpenBMB YouTube: https://www.youtube.com/channel/UCyDtv4OTmeZ1OYrCHymYGow
+Eligible models:
+MiniCPM5-1B — lightweight text/local 
+MiniCPM-V 4.6 — image/OCR/multimodal 
+MiniCPM-o 4.5 — omni-modal 
+MiniCPM4.1-8B — reasoning
+VoxCPM2 — voice/TTS
+Cookbooks:
+MiniCPM-V / MiniCPM-o Cookbook —GitHub
+MiniCPM-V / MiniCPM-o Cookbook — Website
+MiniCPM-V Apps
+
+MiniCPM-V 4.6 — image/OCR/multimodal
+MiniCPM-o 4.5 — omni-modal
+MiniCPM5-1B — lightweight text/local
+MiniCPM4.1-8B — reasoning
+VoxCPM2 — voice/TTS
+
+https://huggingface.co/openbmb/MiniCPM5-1B
+https://huggingface.co/blog/CohereLabs/build-small-hackathon-with-cohere-models

docs/rpg-progression-plan.md

@@ -0,0 +1,279 @@
+# Tiny Army — RPG Progression, Skill Forge, Character Chat & Voice
+
+**Goal:** turn each fighter from a static persona into a living, evolving character that
+**levels up**, **forges unique skills** (code + flavor + art), and you can **talk to**
+on its character page and **hear it speak**. Mobile-first throughout.
+
+This plan is grounded in the current architecture:
+
+- **Souls persist client-side**: `web/personaStore.js` → `localStorage['tinyarmy.roster.v1']`
+  + IndexedDB (`portraits`, `voices` blob stores). No backend DB; we extend this.
+- **Combat is in the browser**: source in `../auto-battler/src/`, bundled into `web/*.js`
+  by `build.sh` (esbuild). Roam combat = `src/render/comboBattler.js`; resolver =
+  `src/engine/teamBattle.js`; skill IR = `src/engine/skills.js` (`CB_SKILLS`).
+- **Skill IR is a clean object**: `{id, name, profession, attribute, category, target,
+  cost, cast, recharge, requires, effects[]}`, icon at `/gw/skills/<id>.jpg`. This is the
+  exact output contract for the Skill Forge model.
+- **Models wired via facades**: text = `web/runtime.js` + `/text/generate/stream` (SSE);
+  image = `web/imagen.js` + `/portrait` (Klein on :7865); TTS = `web/tts.js`
+  (Kokoro in-browser / Qwen3 / VoxCPM). Code model = **BLS Mini-Code 30B** (the "skill forge").
+- **Context pattern to copy from woid**: `agent-sandbox/pi-bridge/buildContext.js` —
+  static system prompt + dynamic per-turn delta (perception event log, needs/mood line,
+  verbatim memory of recent scenes). We port a single-player, client-side slice of this.
+
+> ⚠️ Two-repo build: engine/skill changes are authored in `../auto-battler/src/**`, then
+> `./build.sh` re-bundles into `tiny-army/web/`. UI shell + endpoints live in tiny-army
+> (`app.py`, `web/*.js`). Verify on the auto-battler dev server (:5173) and the tiny-army
+> server (:7860).
+
+---
+
+## Phase 0 — Foundations: persistent progression state
+
+Everything else depends on the soul being able to *carry* progression. Do this first.
+
+**0.1 Extend the persona schema** (`web/personaStore.js`)
+Add, with a version bump + migration (default-fill on load so existing roster survives):
+```js
+progression: { level: 1, xp: 0, kills: 0, attributePoints: 0 },
+learnedSkills: [],        // skillIds owned by THIS character (refs into customSkills or CB_SKILLS)
+equippedSkills: [],       // up to 3 skillIds → the bar comboBattler reads
+customSkills: {},         // skillId → forged skill IR + {flavor, iconKey, forgedFrom, forgedAt}
+chat: { history: [] },    // [{ role:'user'|'char', text, ts, audioKey? }]
+events: [],               // append-only progression log (see Phase 3 memory)
+```
+New IndexedDB stores: `skillIcons` (PNG blobs, keyed by skillId), `chatAudio` (WAV blobs,
+keyed by message id). Mirror the existing `portraits`/`voices` blob pattern.
+
+**0.2 "Active hero" selection** — a small shared store so the character page, combat, and
+chat all agree on *which* roster member is in play. Persist `tinyarmy.activeHeroId`.
+
+**0.3 XP curve util** (`web/progression.js`) — pure functions:
+`xpToNext(level)`, `applyXp(progression, amount) → {progression, leveledUp, levelsGained}`.
+Single source of truth; no curve math scattered in UI.
+
+**Acceptance:** existing roster loads unchanged; new fields present with defaults; refresh
+preserves a hand-set `xp`/`level`.
+
+---
+
+## Phase 1 — Leveling: defeat enemies → grow
+
+**1.1 Emit a defeat event from combat** (`../auto-battler/src/render/comboBattler.js`)
+The roam loop already tracks foe `.alive` and culls corpses via a `deadAt` map (~L372-377).
+Add a one-shot hook when a foe transitions alive→dead *and* the player dealt the kill:
+`opts.onEnemyDefeated?.({ id, name, enemyClass, x, y, t })`. Fire it once per foe at the
+transition, before culling. Rebuild with `./build.sh`.
+
+**1.2 Award XP in the shell** (`web/comboBattler.js` host / `web/tiny.js` wiring)
+Pass `onEnemyDefeated` from tiny-army. On each defeat: look up enemy XP value
+(small table by enemy class/tier), `applyXp` on the active hero, persist, and if
+`leveledUp` push a `level_up` event + grant `attributePoints`.
+
+**1.3 Level-up feedback (mobile)** — a lightweight toast/banner over the canvas
+("⚔️ {name} reached level {n}!") + a dismissible level-up sheet offering: spend
+attribute point, and (Phase 2) "Forge a new skill." Bottom-sheet style, thumb-reachable.
+
+**1.4 Character page: progression header** (`web/heroCreator.js` barracks card / character sheet)
+Show level, an XP progress bar, kill count, and attribute points available. Reuse existing
+`.persona-*` CSS tokens; keep single-column on ≤768px.
+
+**Acceptance:** killing foes in roam raises the active hero's XP bar; crossing a threshold
+levels them up, persists across refresh, and grants a spendable point.
+
+---
+
+## Phase 2 — Skill Forge: unique skills (code + flavor + art)
+
+Each learned skill is **generated**, not picked from a list — unique IR from the code model,
+flavor text from the text model, an icon from Klein.
+
+**2.1 Skill IR validator** (`web/skillSchema.js`, mirrors `src/engine/skills.js`)
+Whitelist of legal `category`, `target`, `effects[].op`, `condition`, and `cost` keys, with
+numeric clamps (so a forged skill can't be game-breaking or crash the resolver). The engine
+is the source of truth — keep the whitelist in sync with `CB_SKILLS` ops
+(`apply_condition`, `bonus_damage`, `interrupt`, `lose_all_adrenaline`, …). Assign a fresh
+non-colliding `id` (e.g. `9000+`) so icons/refs don't clash with the canon 0–~700 range.
+
+**2.2 Forge endpoint** (`app.py` → `POST /skill/forge`, SSE)
+Input: `{ heroId, persona, level, theme? }`. Pipeline:
+1. **Code model (BLS Mini-Code 30B / `TINY_BLS_CODE_SPACE`)** — system prompt embeds the
+   skill IR spec + 2-3 `CB_SKILLS` examples; asked to emit **one JSON skill object** themed
+   to the character's class/persona/specialty. Strip the model's reasoning block (already
+   handled for BLS in `llm.py`). Validate via 2.1; **one retry** on invalid with the error
+   fed back; fall back to a templated mutation of a canon skill if still invalid (never block
+   a level-up on model failure).
+2. **Text model** — short **flavor text** (1-2 sentences, in-world) for the skill, using the
+   persona's voice fields.
+3. **Klein (`/portrait` reuse or `/skill-icon`)** — generate a square icon from a prompt
+   built off skill name + flavor + class palette; store blob in `skillIcons` IndexedDB.
+Stream progress events (`forging-code`, `forging-flavor`, `forging-art`, `done`) so the UI
+shows a live "forging…" state.
+
+**2.3 Save + learn** — write the IR into `customSkills[id]`, push id to `learnedSkills`,
+log a `skill_learned` event. Offer to **equip** (into the ≤3 `equippedSkills`). `comboBattler`
+already reads `player.unit.skills` (L320) — feed it `equippedSkills` resolved against
+`customSkills` ∪ `CB_SKILLS`.
+
+**2.4 Two Klein renders per skill — icon + action shot.** The forge generates **two** images:
+1. **Icon** — square, for the skill card (prompt: skill name + flavor + class palette).
+2. **Action illustration** — a larger scene of **this character performing the skill**, built
+   from the persona's appearance/portrait fields + the skill's flavor + effect (e.g. "{name},
+   a {class}, mid-{skill} — {flavor}, motion + impact"). Stored in `skillIcons` (or a sibling
+   `skillArt`) IndexedDB store keyed by skillId. Generate the action shot lazily (on first
+   detail open) so forging stays fast, then cache.
+
+**2.5 Character page: Skills tab + detail sheet (mobile)** — a grid of skill **cards** (icon,
+name, compact effect summary via the engine's effect-label helper, e.g. `+bleeding`). Tap a
+card → a **larger skill detail sheet**: the **action illustration** up top (the character
+performing the skill), then name, full flavor text, effect breakdown, cost/attribute, and
+equip/unequip (cap 3). Bottom-sheet style; single-column on phones; lazy-load art from IndexedDB.
+
+**Acceptance:** on level-up you can forge a skill; it appears as a card with a unique Klein
+icon + flavor; opening it shows a bigger detail screen with a Klein image of the character
+performing the skill; equipping it makes it usable on the bar in roam combat; all survives refresh.
+
+---
+
+## Phase 3 — Character Chat: talk to your fighter (woid-style context)
+
+Port a **single-player, client-assembled** slice of woid's `buildContext.js`: a static
+**system prompt** (identity) + a dynamic **state turn** ("what's happening to you now") +
+**verbatim memory** of the recent conversation. No Colyseus/needs-decay complexity — just the
+context-assembly shape.
+
+**3.1 Context builder** (`web/characterContext.js`, modeled on woid `buildContext.js`)
+- `buildSystemPrompt(persona)` — name, class, `about`, personality/vibe/specialty, plus a
+  "stay in voice, you are a real fighter who lived these events" rule. Built once per session.
+- `buildStateTurn(persona, userMsg)` — the **delta**: current `level`, recent `events`
+  (battles won, skills forged, level-ups — woid's "perception log", here from `persona.events`),
+  equipped skills, last battle outcome / current HP if mid-roam. One compact block, like
+  woid's needs/mood/trigger lines.
+- `buildMemory(persona.chat.history)` — verbatim last N turns (woid drops summarization;
+  we do too), char-budgeted.
+
+**3.2 Chat endpoint** (`app.py` → `POST /chat/stream`, SSE)
+Thin wrapper over the existing `/text/generate/stream` path (souls are client-side, so the
+**client sends the assembled system + turn**; the server just streams the chosen text model —
+Tiny Aya / MiniCPM / Mellum via `runtime.js`). Append the streamed reply to `chat.history`.
+
+**3.3 Chat UI on the character screen (mobile)** — a message thread under the character
+sheet: bubbles, a sticky bottom input + send (thumb zone), streamed tokens appear live (reuse
+the SSE parser pattern from `personaStream.js`). Persist history in `chat.history`.
+
+**Acceptance:** on a character's page you can ask "how was that last fight?" and get an
+in-voice reply that references real state (their level, a skill they forged, the enemy they
+just beat); the thread persists across refresh.
+
+---
+
+## Phase 4 — Voice: hear them speak
+
+**4.1 Per-message play button** — every character chat bubble gets a ▶ button. On tap, run
+the existing TTS narrator (`web/tts.js`) with the persona's `voiceId`/`voice` design fields
+(the same pipeline the diary + persona preview already use). Show a loading→playing→replay
+state on the button.
+
+**4.2 Cache audio** — store generated WAV in the `chatAudio` IndexedDB store keyed by message
+id (mirror `voices`/`portraits`); replay is instant and offline. Skip regeneration if cached.
+
+**4.3 (Optional) auto-speak toggle** — a per-character setting to auto-play replies as they
+finish streaming.
+
+**Acceptance:** tapping ▶ on a reply speaks it in the character's voice; replays from cache
+with no re-synth; works on mobile (respects the tap-to-unlock-audio gesture).
+
+---
+
+## Phase 5 — Emotes: condition-driven character/enemy reactions
+
+Heroes **and** enemies pop a little emote bubble above their sprite when something happens
+(took a hit, killed a foe, low HP, afflicted, leveled, idle). Uses the **Minifantasy UI
+Overhaul "Character_Emotions"** pack already in the repo — no model needed.
+
+**Assets (already present in `../auto-battler/public/assets/.../Character_Emotions/`):**
+- `_Emotions.png` (152×104) — a sheet of **8×8px** emoticon faces: angry, happy, sad,
+  surprised, dizzy/dazed, ❤ love, 💤 sleepy, ♪ music, sweat/fear, sick, etc.
+- `_Bubble.png` (280×72) — speech-bubble frames with the tail pointing 8 directions, so the
+  bubble can sit above a sprite. (`Bubble_Only` / `Bubble_Outline` variants too.)
+
+**5.1 Curate the pack into tiny-army** — add the emote + bubble PNGs to `curate_assets.py`'s
+keep-list so `./build.sh` copies them into `web/assets/`. They're tiny (KBs).
+
+**5.2 Emote sheet decoder** (`../auto-battler/src/render/emotes.js`, bundled to `web/`)
+Decode `_Emotions.png` as an 8×8 grid → a named map (`{ angry, happy, sad, surprised, dizzy,
+love, sleepy, music, sweat, sick, ... }`), and the bubble frame by tail direction. Mirror the
+existing `spriteSheet.js`/`sheet.js` decode pattern (rows×cols, nearest-neighbor scale).
+
+**5.3 Emote render layer** (`../auto-battler/src/render/comboBattler.js` + sprite scene)
+A small overlay attached to each actor sprite: `showEmote(actorId, key, { ms })` spawns the
+bubble + 8×8 icon above the sprite (scaled to match `groundScale`), auto-expires, and is
+culled with the actor. Pixel-snapped, no blur. One emote at a time per actor (latest wins).
+
+**5.4 Condition → emote mapping** (engine events → render)
+Drive it off events the resolver/roam loop already produces (`teamBattle.js` logs hits,
+conditions, deaths; `comboBattler` knows `.alive`/HP). A small, tunable table, e.g.:
+
+| Trigger (condition)            | Hero emote | Enemy emote |
+|--------------------------------|-----------|-------------|
+| Took a hit / `dmg`             | 😠 angry  | 😠 angry    |
+| Afflicted (`bleeding`/`poison`)| 😣 sick   | 😣 sick     |
+| Stunned / `interrupt` / dazed  | 😵 dizzy  | 😵 dizzy    |
+| HP crosses low threshold       | 😨 sweat  | 😨 sweat    |
+| Killed a foe                   | 😄 happy  | —           |
+| On death                       | —         | 💀/😵 dizzy |
+| Level-up (hero, Phase 1)       | ❤ love    | —           |
+| Idle a while / out of combat   | 💤 sleepy | 💤 sleepy   |
+
+Debounce so a flurry of hits doesn't strobe (min interval per actor). Keep the table in one
+place so it's easy to retune. Rebuild via `./build.sh`.
+
+**5.5 (small) Settings toggle** — an "emotes" on/off in the existing settings; default on.
+
+**Acceptance:** in roam combat, taking damage, getting bled/stunned, dropping low, and killing
+foes each pop the right 8×8 emote bubble over the correct sprite (hero and enemies); a level-up
+shows the ❤ emote; the bubble scales correctly on mobile and is pixel-crisp.
+
+---
+
+## Cross-cutting
+
+- **Mobile-first**: every new surface is single-column ≤768px, controls in the thumb zone,
+  bottom-sheets over modals, lazy-loaded media. Matches the existing joystick/attack mobile work.
+- **Graceful degradation**: any model call (forge/chat/voice) can fail → always a non-blocking
+  fallback (templated skill, text-only reply, silent button). The app already degrades when
+  sidecars are down; preserve that.
+- **Build discipline**: engine/skill edits → `../auto-battler/src` → `./build.sh` → verify.
+  Run local model sidecars with `./run_sidecars.sh` (Aya :7864, Klein :7865); BLS code model
+  via its space/sidecar.
+- **Persistence is client-side** by design (hackathon). If cross-device sync is ever needed,
+  the one new thing required is a `/personas` GET/POST backend store — out of scope here.
+
+## Dependency order
+```
+Phase 0 (state)  ──►  Phase 1 (leveling)  ──►  Phase 2 (skill forge + detail art)
+                 └─►  Phase 3 (chat) ──► Phase 4 (voice)
+
+Phase 5 (emotes) ── needs only engine/render access; richer once Phase 1 events exist.
+                    Can be built in parallel; level-up emote depends on Phase 1.
+```
+Phase 1, 3, and 5 can proceed in parallel once Phase 0 lands (chat doesn't need leveling but
+reads richer state once leveling/forge exist; emotes are mostly self-contained render work).
+
+## Model assignments
+| Capability        | Model                          | Path |
+|-------------------|--------------------------------|------|
+| Skill code (IR)   | BLS Mini-Code 30B              | `TINY_BLS_CODE_SPACE`, reasoning stripped |
+| Skill flavor      | Tiny Aya / MiniCPM / Mellum    | `/text/generate/stream` |
+| Skill icon + action shot | FLUX.2 Klein 4B          | `/portrait` (:7865) — icon (square) + character-performing-skill illustration |
+| Emote graphics    | none (Minifantasy art pack)    | `Character_Emotions/_Emotions.png` (8×8) + `_Bubble.png` |
+| Character chat     | Tiny Aya / MiniCPM / Mellum   | `/chat/stream` → `/text/generate/stream` |
+| Voice             | Kokoro / Qwen3-TTS / VoxCPM    | `web/tts.js` |
+
+## Open decisions (pick before/while building)
+1. **XP source**: kills-only (simplest), or also reward skill use / survival? → start kills-only.
+2. **Forge trigger**: auto-offer one skill per level, or a spendable "forge token"? → token, so
+   forging is a deliberate, art-worthy moment.
+3. **Equipped cap**: keep the engine's 3-skill bar, or expand? → keep 3 for balance + UI fit.
+4. **Chat state breadth**: how much game state in the turn (just stats, or full recent event
+   log)? → start with stats + last 5 events; expand if replies feel thin.

kimodo_pose.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""kimodo motion -> OpenPose control image, for driving the weiner Klein LoRA.
+
+The kimodo motion API (http://HOST:7862) returns, per clip, `posed_joints` [T,22,3]:
+world-space 3D positions of the 22 SMPL-X body joints (y-up, metres). This module
+projects a chosen frame to 2D and draws a canonical OpenPose (COCO-18) colored
+skeleton — the abstract pose anchor that FLUX.2 Klein follows WITHOUT donating any
+material (unlike a textured mannequin), so the weiner identity/LoRA supplies looks.
+
+Pipeline:  kimodo /animations/{id}  ->  openpose_png(frame)  ->  klein /generate
+           image=[skeleton, weiner_identity_shot], lora=weiner
+
+CLI:
+    python kimodo_pose.py <anim_id> <out.png> [--frame N | --peak foot|hand] [--view front|side|auto]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import urllib.request
+
+import numpy as np
+from PIL import Image, ImageDraw
+
+KIMODO_URL = "http://127.0.0.1:7862"
+
+# SMPL-X 22-joint order returned by the kimodo API (see /info bone_names).
+SMPLX = {
+    "pelvis": 0, "left_hip": 1, "right_hip": 2, "spine1": 3, "left_knee": 4,
+    "right_knee": 5, "spine2": 6, "left_ankle": 7, "right_ankle": 8, "spine3": 9,
+    "left_foot": 10, "right_foot": 11, "neck": 12, "left_collar": 13,
+    "right_collar": 14, "head": 15, "left_shoulder": 16, "right_shoulder": 17,
+    "left_elbow": 18, "right_elbow": 19, "left_wrist": 20, "right_wrist": 21,
+}
+
+# OpenPose COCO-18 keypoint index -> source SMPL-X joint (eyes/ears synthesized below).
+OP_FROM_SMPLX = {
+    0: "head",            # nose ~ head
+    1: "neck", 2: "right_shoulder", 3: "right_elbow", 4: "right_wrist",
+    5: "left_shoulder", 6: "left_elbow", 7: "left_wrist",
+    8: "right_hip", 9: "right_knee", 10: "right_ankle",
+    11: "left_hip", 12: "left_knee", 13: "left_ankle",
+}
+# OpenPose limb pairs (COCO-18) + canonical colors (R,G,B).
+OP_LIMBS = [
+    (1, 2, (255, 0, 0)), (1, 5, (255, 85, 0)), (2, 3, (255, 170, 0)),
+    (3, 4, (255, 255, 0)), (5, 6, (170, 255, 0)), (6, 7, (85, 255, 0)),
+    (1, 8, (0, 255, 0)), (8, 9, (0, 255, 85)), (9, 10, (0, 255, 170)),
+    (1, 11, (0, 255, 255)), (11, 12, (0, 170, 255)), (12, 13, (0, 85, 255)),
+    (1, 0, (0, 0, 255)), (0, 14, (85, 0, 255)), (14, 16, (170, 0, 255)),
+    (0, 15, (255, 0, 255)), (15, 17, (255, 0, 170)),
+]
+OP_POINT_COLOR = [
+    (255, 0, 0), (255, 85, 0), (255, 170, 0), (255, 255, 0), (170, 255, 0),
+    (85, 255, 0), (0, 255, 0), (0, 255, 85), (0, 255, 170), (0, 255, 255),
+    (0, 170, 255), (0, 85, 255), (0, 0, 255), (85, 0, 255), (170, 0, 255),
+    (255, 0, 255), (255, 0, 170), (255, 0, 85),
+]
+
+
+def fetch(anim_id: str, url: str = KIMODO_URL) -> dict:
+    return json.load(urllib.request.urlopen(f"{url}/animations/{anim_id}", timeout=30))
+
+
+def peak_frame(P: np.ndarray, what: str = "foot") -> int:
+    """Frame where the action reads clearest: foot/hand at max height (kick/punch peak)."""
+    idx = [SMPLX["left_foot"], SMPLX["right_foot"], SMPLX["left_ankle"], SMPLX["right_ankle"]] \
+        if what == "foot" else [SMPLX["left_wrist"], SMPLX["right_wrist"]]
+    return int(P[:, idx, 1].max(axis=1).argmax())
+
+
+def _project(J: np.ndarray, view: str):
+    """3D world joints [22,3] (y up) -> 2D [22,2] in image space. front: x-y; side: z-y."""
+    x, y, z = J[:, 0], J[:, 1], J[:, 2]
+    if view == "auto":
+        view = "side" if z.std() > x.std() * 1.15 else "front"
+    h = x if view == "front" else z
+    return np.stack([h, y], axis=1), view  # (horizontal, vertical-up)
+
+
+def openpose_image(P_frame: np.ndarray, size: int = 1024, view: str = "auto",
+                   pad: float = 0.14) -> Image.Image:
+    """Draw a COCO-18 OpenPose skeleton for one frame's [22,3] joints on black."""
+    pts2d, _ = _project(P_frame, view)
+    # build the 18 OpenPose keypoints
+    kp = np.full((18, 2), np.nan)
+    for op_i, name in OP_FROM_SMPLX.items():
+        kp[op_i] = pts2d[SMPLX[name]]
+    # synthesize eyes/ears around the head so the face limbs render
+    head, neck = pts2d[SMPLX["head"]], pts2d[SMPLX["neck"]]
+    up = (head - neck); span = np.linalg.norm(up) + 1e-6; up = up / span
+    side = np.array([-up[1], up[0]]) * span * 0.25
+    kp[0] = head + up * span * 0.15                 # nose
+    kp[14], kp[15] = head + side * 0.6, head - side * 0.6   # R/L eye
+    kp[16], kp[17] = head + side, head - side              # R/L ear
+
+    # normalize into the canvas (preserve aspect, feet at bottom, head at top)
+    valid = kp[~np.isnan(kp).any(axis=1)]
+    hmin, hmax = valid[:, 0].min(), valid[:, 0].max()
+    vmin, vmax = valid[:, 1].min(), valid[:, 1].max()
+    s = (1 - 2 * pad) * size / max(hmax - hmin, vmax - vmin, 1e-6)
+    cu = size / 2 - (hmin + hmax) / 2 * s
+    cv = size / 2 + (vmin + vmax) / 2 * s
+
+    def to_px(p):
+        return (cu + p[0] * s, cv - p[1] * s)  # flip vertical (y-up -> image-down)
+
+    img = Image.new("RGB", (size, size), (0, 0, 0))
+    d = ImageDraw.Draw(img)
+    lw = max(4, size // 160)
+    for a, b, c in OP_LIMBS:
+        if np.isnan(kp[a]).any() or np.isnan(kp[b]).any():
+            continue
+        d.line([to_px(kp[a]), to_px(kp[b])], fill=c, width=lw)
+    r = max(4, size // 200)
+    for i, p in enumerate(kp):
+        if np.isnan(p).any():
+            continue
+        x, y = to_px(p)
+        d.ellipse([x - r, y - r, x + r, y + r], fill=OP_POINT_COLOR[i])
+    return img
+
+
+def render_anim_frame(anim_id, out, frame=None, peak="foot", view="auto", url=KIMODO_URL):
+    rec = fetch(anim_id, url)
+    P = np.array(rec["posed_joints"])
+    f = peak_frame(P, peak) if frame is None else int(frame)
+    img = openpose_image(P[f], view=view)
+    img.save(out)
+    print(f"saved {out}  anim={anim_id} frame={f}/{P.shape[0]} view={view} prompt={rec.get('prompt','')[:60]!r}")
+    return f
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("anim_id")
+    ap.add_argument("out")
+    ap.add_argument("--frame", type=int, default=None)
+    ap.add_argument("--peak", choices=["foot", "hand"], default="foot")
+    ap.add_argument("--view", choices=["front", "side", "auto"], default="auto")
+    ap.add_argument("--url", default=KIMODO_URL)
+    a = ap.parse_args()
+    render_anim_frame(a.anim_id, a.out, a.frame, a.peak, a.view, a.url)

spaces/klein-zerogpu/app.py

@@ -46,6 +46,7 @@ def GPU(*dargs, **dkwargs):  # noqa: N802
 import gradio as gr
 import torch
 from diffusers import Flux2KleinPipeline
+from PIL import Image
 
 MODEL_ID = os.environ.get("TINY_KLEIN_MODEL", "black-forest-labs/FLUX.2-klein-4B")
 STEPS = int(os.environ.get("TINY_KLEIN_STEPS", "4"))
@@ -118,8 +119,15 @@ if torch.cuda.is_available():
     _offload_enabled = True
 
 
+def _to_img(x):
+    if x is None:
+        return None
+    img = x if isinstance(x, Image.Image) else Image.open(x)
+    return img.convert("RGB").resize((1024, 1024))
+
+
 @GPU(duration=60)
-def generate(prompt: str, seed: int = 42, lora: str = DEFAULT_LORA):
+def generate(prompt: str, seed: int = 42, lora: str = DEFAULT_LORA, ref_image=None, ref_image2=None):
     if not prompt or not prompt.strip():
         raise gr.Error("prompt required")
     _ensure_lora(lora)
@@ -128,14 +136,23 @@ def generate(prompt: str, seed: int = 42, lora: str = DEFAULT_LORA):
     dev = "cuda" if torch.cuda.is_available() else "cpu"
     if seed is None or int(seed) < 0:
         seed = random.randint(0, MAX_SEED)
-    img = pipe(
+    kwargs = dict(
         prompt=prompt.strip(),
         width=1024,
         height=1024,
         num_inference_steps=STEPS,
         guidance_scale=GUIDANCE,
         generator=torch.Generator(device=dev).manual_seed(int(seed)),
-    ).images[0]
+    )
+    # FLUX.2 native multi-image conditioning: pass [pose anchor, identity ref] as a LIST so the
+    # composition follows one reference (e.g. a mannequin/depth render of a kimodo pose) while
+    # character identity comes from the other. One image -> passed alone (proven single-ref path).
+    refs = [r for r in (_to_img(ref_image), _to_img(ref_image2)) if r is not None]
+    if len(refs) == 1:
+        kwargs["image"] = refs[0]
+    elif refs:
+        kwargs["image"] = refs
+    img = pipe(**kwargs).images[0]
     if dev == "cuda":
         torch.cuda.empty_cache()
     return img
@@ -148,6 +165,8 @@ demo = gr.Interface(
         gr.Number(label="Seed", value=42, precision=0),
         gr.Textbox(label="LoRA", value=DEFAULT_LORA,
                    placeholder="blank = none; weiner / weiner750 / weiner500 / weiner250"),
+        gr.Image(label="Pose reference (optional)", type="pil"),
+        gr.Image(label="Identity reference (optional)", type="pil"),
     ],
     outputs=gr.Image(type="pil", label="Portrait"),
     api_name="generate",

web/personaStore.js

@@ -4,11 +4,32 @@
 // Voice is stored as the design TEXT + quote (re-synthesized on replay) — the audio
 // blob and cross-device sync are the backend's job (see the plan). Future persona data
 // (stats, avatar, xp, relationships) just adds fields to the record.
+//
+// Progression (level/xp/kills, forged skills, chat history, an event log) is additive:
+// `normalize()` default-fills the new fields on read so an existing v1 roster keeps
+// working with no explicit migration step. See docs/rpg-progression-plan.md.
 const KEY = 'tinyarmy.roster.v1'
+const AKEY = 'tinyarmy.activeHeroId'
 
 const listeners = new Set()
+const activeListeners = new Set()
 let _sync = null // optional { push(records), pull() } — wired to a backend later
 
+// Default-fill the progression fields so old records (and partial saves) are always
+// well-shaped. Additive only — never drops unknown fields.
+function normalize(p) {
+  if (!p) return p
+  return {
+    ...p,
+    progression: { level: 1, xp: 0, kills: 0, attributePoints: 0, ...(p.progression || {}) },
+    learnedSkills: Array.isArray(p.learnedSkills) ? p.learnedSkills : [],
+    equippedSkills: Array.isArray(p.equippedSkills) ? p.equippedSkills : [],
+    customSkills: p.customSkills && typeof p.customSkills === 'object' ? p.customSkills : {},
+    chat: { history: Array.isArray(p.chat?.history) ? p.chat.history : [] },
+    events: Array.isArray(p.events) ? p.events : [],
+  }
+}
+
 function read() {
   try { const d = JSON.parse(localStorage.getItem(KEY) || '{}'); return Array.isArray(d.personas) ? d : { personas: [] } }
   catch { return { personas: [] } }
@@ -21,17 +42,21 @@ function write(d) {
 
 const newId = () => 's_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 7)
 
-export function listPersonas() { return read().personas }
-export function getPersona(id) { return read().personas.find((p) => p.id === id) || null }
+export function listPersonas() { return read().personas.map(normalize) }
+export function getPersona(id) { const p = read().personas.find((x) => x.id === id); return p ? normalize(p) : null }
 export function onRosterChange(fn) { listeners.add(fn); return () => listeners.delete(fn) }
 export function setSync(sync) { _sync = sync }
 
-// Insert or update. Returns the stored record (with id + timestamps).
+// Insert or update. Returns the stored record (with id + timestamps). Progression fields
+// are carried from `p` when present, else preserved from the existing record, else defaulted —
+// so saving a persona edit never wipes its level/skills/chat.
 export function savePersona(p) {
   const d = read()
   const now = Date.now()
   const id = p.id || newId()
-  const rec = {
+  const prev = d.personas.find((x) => x.id === id) || {}
+  const pick = (k, dflt) => (p[k] !== undefined ? p[k] : (prev[k] !== undefined ? prev[k] : dflt))
+  const rec = normalize({
     id,
     name: p.name || 'Unnamed hero',
     unitClass: p.unitClass || '',
@@ -54,9 +79,16 @@ export function savePersona(p) {
     // made from, so a reload knows the image is current vs stale (re-generate it).
     appearance: p.appearance || '',
     portraitUsed: p.portraitUsed || '',
+    // ── Progression (carried, not clobbered) ──
+    progression: pick('progression', undefined),
+    learnedSkills: pick('learnedSkills', undefined),
+    equippedSkills: pick('equippedSkills', undefined),
+    customSkills: pick('customSkills', undefined),
+    chat: pick('chat', undefined),
+    events: pick('events', undefined),
     createdAt: now,
     updatedAt: now,
-  }
+  })
   const i = d.personas.findIndex((x) => x.id === id)
   if (i >= 0) { rec.createdAt = d.personas[i].createdAt; d.personas[i] = rec }
   else { d.personas.unshift(rec) }
@@ -64,24 +96,50 @@ export function savePersona(p) {
   return rec
 }
 
+// Shallow-merge a partial update into a stored persona and persist. Use this for hot,
+// frequent writes (XP on a kill, a chat turn) so a partial update never rebuilds — and
+// never drops — the rest of the record. Returns the updated record or null if not found.
+export function patchPersona(id, partial) {
+  const d = read()
+  const i = d.personas.findIndex((x) => x.id === id)
+  if (i < 0) return null
+  d.personas[i] = normalize({ ...d.personas[i], ...partial, id, updatedAt: Date.now() })
+  write(d)
+  return d.personas[i]
+}
+
 export function removePersona(id) {
   const d = read()
   const next = d.personas.filter((x) => x.id !== id)
   if (next.length !== d.personas.length) write({ personas: next })
-  _del(STORE, id); _del(PSTORE, id)
+  if (getActiveHeroId() === id) setActiveHeroId(null)
+  for (const s of [STORE, PSTORE, ICONS, ART, CHATAUDIO]) _del(s, id)
+}
+
+// ── Active hero — the one roster member combat/chat/skills currently operate on ──
+export function getActiveHeroId() { try { return localStorage.getItem(AKEY) || null } catch { return null } }
+export function setActiveHeroId(id) {
+  try { id ? localStorage.setItem(AKEY, id) : localStorage.removeItem(AKEY) } catch { /* ignore */ }
+  for (const fn of activeListeners) { try { fn(id || null) } catch { /* ignore */ } }
 }
+export function getActiveHero() { const id = getActiveHeroId(); return id ? getPersona(id) : null }
+export function onActiveHeroChange(fn) { activeListeners.add(fn); return () => activeListeners.delete(fn) }
 
 // ── Media store (IndexedDB — WAV + PNG blobs are too big for localStorage) ──────
+// v3 adds skill icons, skill action-shot art, and per-message chat audio alongside
+// the original voices + portraits stores.
 const DB = 'tinyarmy', STORE = 'voices', PSTORE = 'portraits'
+const ICONS = 'skillIcons', ART = 'skillArt', CHATAUDIO = 'chatAudio'
 let _dbp = null
 function db() {
   if (!_dbp) {
     _dbp = new Promise((res, rej) => {
-      const r = indexedDB.open(DB, 2) // v2 adds the 'portraits' store alongside 'voices'
+      const r = indexedDB.open(DB, 3)
       r.onupgradeneeded = () => {
         const d = r.result
-        if (!d.objectStoreNames.contains(STORE)) d.createObjectStore(STORE)
-        if (!d.objectStoreNames.contains(PSTORE)) d.createObjectStore(PSTORE)
+        for (const s of [STORE, PSTORE, ICONS, ART, CHATAUDIO]) {
+          if (!d.objectStoreNames.contains(s)) d.createObjectStore(s)
+        }
       }
       r.onsuccess = () => res(r.result)
       r.onerror = () => rej(r.error)
@@ -108,3 +166,10 @@ export const putAudio = (id, blob) => _put(STORE, id, blob)
 export const getAudio = (id) => _get(STORE, id)
 export const putPortrait = (id, blob) => _put(PSTORE, id, blob)
 export const getPortrait = (id) => _get(PSTORE, id)
+// Skill media is keyed by skillId; chat audio by message id.
+export const putSkillIcon = (skillId, blob) => _put(ICONS, skillId, blob)
+export const getSkillIcon = (skillId) => _get(ICONS, skillId)
+export const putSkillArt = (skillId, blob) => _put(ART, skillId, blob)
+export const getSkillArt = (skillId) => _get(ART, skillId)
+export const putChatAudio = (msgId, blob) => _put(CHATAUDIO, msgId, blob)
+export const getChatAudio = (msgId) => _get(CHATAUDIO, msgId)

web/progression.js

@@ -0,0 +1,72 @@
+// Pure progression math + event helpers — the single source of truth for the XP curve
+// so no UI re-derives it. See docs/rpg-progression-plan.md (Phase 0/1).
+//
+// Curve: a gentle quadratic so early levels come fast and later ones slow down.
+// xpToNext(L) = BASE + GROWTH * (L-1)^1.5, rounded to a tidy step.
+
+const BASE = 50
+const GROWTH = 40
+const ATTR_PER_LEVEL = 1
+
+export function xpToNext(level) {
+  const l = Math.max(1, level | 0)
+  return Math.round((BASE + GROWTH * Math.pow(l - 1, 1.5)) / 10) * 10
+}
+
+// Total XP needed to have *reached* a given level from level 1 (handy for bars/among UIs).
+export function xpForLevel(level) {
+  let sum = 0
+  for (let l = 1; l < Math.max(1, level | 0); l++) sum += xpToNext(l)
+  return sum
+}
+
+// Apply `amount` XP to a progression object, rolling over as many levels as the XP covers.
+// Returns a NEW progression object plus what happened, so callers can react (toast, points).
+export function applyXp(progression, amount) {
+  const p = { level: 1, xp: 0, kills: 0, attributePoints: 0, ...(progression || {}) }
+  let { level, xp, attributePoints } = p
+  xp += Math.max(0, amount | 0)
+  let leveledUp = false, levelsGained = 0
+  let need = xpToNext(level)
+  while (xp >= need) {
+    xp -= need
+    level += 1
+    levelsGained += 1
+    attributePoints += ATTR_PER_LEVEL
+    leveledUp = true
+    need = xpToNext(level)
+  }
+  return {
+    progression: { ...p, level, xp, attributePoints },
+    leveledUp,
+    levelsGained,
+    xpToNext: need,
+  }
+}
+
+// Fraction [0,1] toward the next level — for the XP bar.
+export function levelProgress(progression) {
+  const p = progression || {}
+  const need = xpToNext(p.level || 1)
+  return need > 0 ? Math.min(1, Math.max(0, (p.xp || 0) / need)) : 0
+}
+
+// XP a defeated foe is worth. Small table keyed by a coarse tier/class string; unknown
+// enemies fall back to a sane default. Tunable in one place.
+const ENEMY_XP = { weak: 8, normal: 12, tough: 20, elite: 40, boss: 100 }
+export function enemyXpValue(enemy) {
+  if (!enemy) return ENEMY_XP.normal
+  if (typeof enemy.xp === 'number') return enemy.xp
+  const tier = (enemy.tier || enemy.rank || '').toLowerCase()
+  if (ENEMY_XP[tier]) return ENEMY_XP[tier]
+  return ENEMY_XP.normal
+}
+
+// Append a capped, structured event to a persona's log (newest last). Used for the chat
+// "what's happening to you" context (woid-style perception log) and the level-up feed.
+const MAX_EVENTS = 60
+export function appendEvent(events, type, data = {}) {
+  const next = Array.isArray(events) ? events.slice() : []
+  next.push({ type, ...data })
+  return next.length > MAX_EVENTS ? next.slice(next.length - MAX_EVENTS) : next
+}