Deploy Karate Wiener (kimodo kata maker)

app.py

@@ -4700,7 +4700,7 @@ _COMPOSE_JS = r"""
       if (byEl) {
         const k = composeCurrentKata; const bits = [];
         if (!k.local && k.contributor) bits.push('by ' + k.contributor);
-        if (k.forked_from) bits.push('⑂ ' + (k.forked_from.contributor_name || k.forked_from.contributor || 'forked'));
+        if (k.forked_from) bits.push('⑂ ' + (k.forked_from.contributor_name || 'anonymous'));
         byEl.textContent = bits.join('  ·  ');
       }
       box.classList.add('show');
@@ -4792,7 +4792,10 @@ _COMPOSE_JS = r"""
       // count all descendants (not just the spine) + 1 for the root
       const all = {}; const stack = [rid];
       while (stack.length) { const x = stack.pop(); (children[x] || []).forEach((c) => { if (!all[c]) { all[c] = 1; stack.push(c); } }); }
-      const recipe = m.compose_recipe || null;
+      // Recipe = the most complete one stamped along the chain (every move stamps the
+      // recipe-so-far; the LAST move holds them all — the root's is truncated to move 1).
+      let recipe = m.compose_recipe || null;
+      for (const sid of path) { const sm = byId[sid]; const r = sm && sm.compose_recipe; if (r && r.length && (!recipe || r.length > recipe.length)) recipe = r; }
       let label = recipe && recipe.length ? recipeLabel(recipe) : (m.prompt || rid);
       // Attribution: the root's creator name, else the first spine move that has one
       // (older roots were built anonymously but their later moves may carry a name).
@@ -4853,7 +4856,7 @@ _COMPOSE_JS = r"""
       // Attribution: who made it (Community), and fork lineage if any.
       const meta = document.createElement('div'); meta.className = 'kimodo-cz-katameta';
       if (!k.local) { const by = document.createElement('div'); by.className = 'kimodo-cz-kataby'; by.textContent = 'by ' + (k.contributor || 'anonymous'); meta.appendChild(by); }
-      if (k.forked_from) { const ff = document.createElement('div'); ff.className = 'kimodo-cz-katafrom'; ff.textContent = '⑂ forked from ' + (k.forked_from.contributor_name || k.forked_from.contributor || 'unknown'); meta.appendChild(ff); }
+      if (k.forked_from) { const ff = document.createElement('div'); ff.className = 'kimodo-cz-katafrom'; ff.textContent = '⑂ forked from ' + (k.forked_from.contributor_name || 'anonymous'); meta.appendChild(ff); }
       // filmstrip: the recipe's stance poses (start/end accented), else the spine clips
       const film = document.createElement('div'); film.className = 'kimodo-cz-film';
       const frames = k.recipe && k.recipe.length ? k.recipe.map((r) => r.id) : k.ids;
@@ -5029,14 +5032,23 @@ _COMPOSE_JS = r"""
   // Fork a community kata into My Katas: copy its recipe + spine (clips are reused so it
   // plays instantly), keep attribution to the original author, and open it editable.
   function forkKata(k) {
-    if (!k || !k.recipe || !k.recipe.length) { setComposeStatus('This kata has no editable recipe to fork.'); return; }
-    const recipe = JSON.parse(JSON.stringify(k.recipe));
-    const ids = Array.isArray(k.ids) ? k.ids.slice() : null;
+    const ids = Array.isArray(k.ids) ? k.ids.slice() : [];
+    let recipe = (k.recipe && k.recipe.length) ? JSON.parse(JSON.stringify(k.recipe)) : [];
+    // The COMPLETE kata is the spine (ids). Older/community katas often stamped only a
+    // truncated recipe (the first move's stances) or none at all — reconstruct the
+    // missing moves from the spine clips so the fork has ALL moves. A recipe needs
+    // ids.length + 1 stances (stance i-1 → i = move i, clip ids[i-1]).
+    if (!recipe.length && ids.length) recipe.push({ id: ids[0], name: 'start', prompt: '', seconds: 2.2, tx: 0, tz: 0, rot: 0 });
+    while (recipe.length < ids.length + 1) {
+      const i = recipe.length; const cid = ids[i - 1] || ids[ids.length - 1] || ('m' + i);
+      recipe.push({ id: cid, name: 'move ' + i, prompt: '', seconds: 2.2, tx: 0, tz: 0, rot: 0 });
+    }
+    if (!recipe.length) { setComposeStatus('This kata can’t be forked (no moves found).'); return; }
     const forked_from = { root: k.root || null, contributor: k.contributor_id || '', contributor_name: k.contributor || '' };
     const entry = { lid: 'k' + Date.now().toString(36), name: (k.label || 'Kata') + ' (fork)', recipe, ids, root: (ids && ids[0]) || null, forked_from, ts: Date.now() };
     const a = loadMyKatas(); a.unshift(entry); saveMyKatas(a);
     composeScope = 'mine';
-    setComposeStatus('Forked “' + (k.label || 'kata') + '” into My Katas.');
+    setComposeStatus('Forked “' + (k.label || 'kata') + '” into My Katas (' + ids.length + ' move' + (ids.length === 1 ? '' : 's') + ').');
     playKata({ lid: entry.lid, root: entry.root, label: entry.name, count: recipe.length, recipe, ids, forked_from, local: true });
   }
   // Space per-move bridge: hand ONE move (its two pinned stances + the already-built
@@ -5052,7 +5064,8 @@ _COMPOSE_JS = r"""
     const prefix = [];
     for (let k = 1; k < i; k++) { const pc = composeStrip[k]; if (pc.clipId && !pc.dirty) prefix.push(pc.clipId); else break; }
     const payload = { move: Object.assign({ index: i }, move), prefix_ids: prefix };
-    if (!prefix.length) { payload.recipe = composeRecipe(); payload.owner = myAnonId(); if (composeCurrentKata && composeCurrentKata.forked_from) payload.forked_from = composeCurrentKata.forked_from; }   // root move stamps the recipe + fork lineage
+    payload.recipe = composeRecipe();   // stamp the FULL recipe-so-far on EVERY move, so the chain's last move always holds the complete kata (the root's is captured before later moves exist)
+    if (!prefix.length) { payload.owner = myAnonId(); if (composeCurrentKata && composeCurrentKata.forked_from) payload.forked_from = composeCurrentKata.forked_from; }   // root move stamps owner + fork lineage
     ta.value = JSON.stringify(payload); ta.dispatchEvent(new Event('input', { bubbles: true }));
     composePending = true;
     setTimeout(() => btn.click(), 50);
@@ -6497,15 +6510,15 @@ def _compose_single_move_logged_in(
     kfs = mv.get("keyframes") or []
     if len(kfs) < 2:
         raise gr.Error("move needs 2 keyframes (start + end stance)")
-    # Recipe (+ owning browser) is stamped on the ROOT move so MY KARATE can reopen it.
+    # The recipe-so-far is stamped on EVERY move (so the chain's LAST move always holds
+    # the complete kata — the root captured it before later moves existed). Owner + fork
+    # lineage stay on the ROOT only. MY KARATE / community read the longest recipe in the chain.
     root_extra = {}
+    if parsed.get("recipe"):
+        root_extra["compose_recipe"] = parsed["recipe"]
     if is_root:
-        if parsed.get("recipe"):
-            root_extra["compose_recipe"] = parsed["recipe"]
         if parsed.get("owner"):
             root_extra["compose_owner"] = str(parsed["owner"])[:64]
-        # Fork lineage (set when this kata was forked from a community kata) — keeps
-        # attribution to the original author in the published data.
         ff = parsed.get("forked_from")
         if isinstance(ff, dict) and (ff.get("root") or ff.get("contributor")):
             root_extra["compose_forked_from"] = {
@@ -6525,7 +6538,7 @@ def _compose_single_move_logged_in(
     prev_id = prefix_ids[-1] if prefix_ids else None
     meta, npz_path, payload, record = _generate_between_uncached(
         prompt, seconds, steps, seed, record_id, kfs, prev_id, generation_model, creator or {},
-        root_extra=(root_extra if is_root else None),
+        root_extra=(root_extra if root_extra else None),
     )
     if not isinstance(payload, dict) or record is None:
         err = meta.get("error") if isinstance(meta, dict) else "generation failed"

docs/comic_pipeline_plan.md

@@ -0,0 +1,91 @@
+# Path B plan — script engine + stance cards (tiny-aya edition)
+
+Decided 2026-06-12. Scriptwright = **tiny-aya** (`CohereLabs/tiny-aya-global` on
+`polats/tiny-army-tiny-aya-zerogpu`) — already integrated in this Space for the dojo
+prompt helper (`app.py` ~3598: gradio_client → `/generate(system, user, max_tokens,
+temperature)`; `/generate_stream` also available for the chat drawer later). This
+REPLACES the earlier in-Space-GGUF plan for script generation: same plumbing as dojo,
+no new runtime, on-theme small model.
+
+## The workflow
+
+```
+stance record (kmd_…)                          chat context (MY STANCES drawer)
+  │ posed_joints[0], tags, source                │ last few lines
+  ▼                                              ▼
+[1] stance_features.py ─► FACTS (all computed, no LLM):
+      pose phrase   "right leg extended high, support leg straight, fists guarding"
+      gag facts     why the worst candidate lost ("arms drooped", "barely left ground")
+      card stats    HEIGHT/REACH/SPREAD/DEPTH/BALANCE 0-99
+  ▼
+[2] premise bank — offline-authored JSON (~50 "Weiner misreads X as Y" scenarios in
+      the user's reference-comic voice, each a 4-beat skeleton with stance slots).
+      3 random premises sampled per call → aya picks/adapts ONE (selection, not improv).
+  ▼
+[3] tiny-aya /generate
+      system: Weiner scriptwright persona + output schema + 2 few-shot scripts
+      user:   stance name + facts + sampled premises + chat excerpt + nonce (dojo trick)
+      out:    JSON { premise_id, panels: [ {scene, caption, speaker, sfx?} x4 ],
+                     flavor }            ← flavor = one-line card epithet
+      parse:  persona_parse-style bracket-balanced extraction; caption length caps;
+              TEMPLATE FALLBACK on any failure (comic never blocks on the LLM)
+  ▼
+[4] klein prompt builder (code): "KW1ENER. A 4-panel comic strip in a 2x2 grid…"
+      + per-panel scene lines from the script
+      + panel 4 scene = THE REAL POSE PHRASE from [1]  ← comic stays honest
+      + "No text, no speech bubbles anywhere."  (trigger-led, NO style words — proven)
+  ▼
+[5] klein sidecar + Weiner LoRA (lora='weiner')
+      distilled 4-step  = in-chat preview (seconds)
+      base 50-step g4   = final "inscribe the scroll" render (pending Path A verdict)
+  ▼
+[6] compositor: exact captions/SFX into bubbles at quadrant anchors
+      (comic_compose.py now; JS canvas port for the Space)
+  ├─► comics/{stance_id}.png + .json (script, facts, premise_id, transcript) → dataset
+  ▼
+[7] STANCE CARD composer → cards/{stance_id}.png + manifest entry → library card
+```
+
+## Stance card
+
+One artifact per learned stance: trading-card layout, stats = the SAME features the
+sensei judged candidates by (numbers close the loop: features → judging → card).
+
+```
+┌──────────────────────────┐
+│ SIDE KICK APEX (RIGHT)   │   name = stance_name
+│ ┌──────────────────────┐ │
+│ │  card art: panel-4   │ │   art = comic panel-4 crop (Weiner doing the
+│ │  crop OR dedicated   │ │         actual learned pose), fallback: one
+│ │  KW1ENER hero render │ │         dedicated klein render w/ pose phrase
+│ └──────────────────────┘ │
+│ “The sky bows first.”    │   flavor line ← tiny-aya
+│ HEIGHT ██████████████ 99 │
+│ REACH  █████████░░░░░ 62 │   stats ← stance_features (0-99 scaled)
+│ SPREAD █████████░░░░░ 66 │
+│ DEPTH  █░░░░░░░░░░░░░  5 │
+│ #kick #right  ·  @polats │   tags + creator (existing record fields)
+│ scroll #017 · 📖 comic   │   links: comic + stance id (loads pose in viewer)
+└──────────────────────────┘
+```
+
+- Computed demo (real record kmd_1f952002fc964515): pose phrase "right leg extended
+  high, support leg straight, fists guarding"; stats HEIGHT 99, REACH 62, SPREAD 66, DEPTH 5.
+- Card face doubles as the MY STANCES library tile (replaces bare skeleton-canvas thumb
+  for stances that have been "carded"); tap → stance pose loads in the 3D viewer,
+  📖 → comic.
+
+## Build order
+
+1. `stance_features.py` + phrase table + card stats (shared module — also Phase-1 scorer lib)
+2. Premise bank (`docs/premises.json`, ~50 entries) + aya system prompt + few-shots
+3. `_comic_script_test.py`: 8-10 stances → aya scripts → parse-rate + quality eyeball
+4. `_comic_e2e_test.py`: scripts → klein+LoRA → composite → first no-human comics sheet
+5. Card composer (`stance_card.py`) → cards for the same stances
+6. Wire into app.py backend (extension point) + MY STANCES drawer UI
+
+## Open
+
+- Path A verdict decides the final-render tier (distilled vs base 50-step).
+- Premise-bank voice check: sample 10 premises past the user before writing all 50.
+- aya temperature: dojo helper uses 1.05 + nonce for variety; scripts likely want ~0.9.

docs/premises_sample.json

@@ -0,0 +1,125 @@
+{
+  "_about": "Karate Weiner 4-koma premise bank — SAMPLE 10 for voice calibration. Formula: earnest absurd claim -> commitment to the bit -> reality flatly intrudes -> Weiner reframes reality as confirmation of mastery. {stance} = the learned stance's name; beats are skeletons for tiny-aya to adapt, not final captions.",
+  "premises": [
+    {
+      "id": "roomba",
+      "foil": "a robot vacuum",
+      "misread": "a tireless student of footwork",
+      "setting": "living room",
+      "beats": [
+        "Weiner presents his most devoted student, circling the room without rest",
+        "Weiner demonstrates the {stance}; the vacuum continues, unmoved by greatness",
+        "the vacuum bumps the same wall for the third time",
+        "\"He patrols. I strike. The dojo is balanced.\""
+      ]
+    },
+    {
+      "id": "sprinkler",
+      "foil": "a lawn sprinkler",
+      "misread": "a master of rhythm who cannot be evaded",
+      "setting": "front yard",
+      "beats": [
+        "Weiner vows to pass the sprinkler untouched using the {stance}",
+        "he advances with total confidence",
+        "he is completely soaked mid-pose",
+        "\"I am cleansed. Round two.\""
+      ]
+    },
+    {
+      "id": "squirrel",
+      "foil": "a squirrel",
+      "misread": "a rival speed master",
+      "setting": "park bench",
+      "beats": [
+        "Weiner challenges the squirrel to witness his {stance}",
+        "he performs it flawlessly, eyes closed for effect",
+        "the squirrel has taken his snack and left",
+        "\"He strikes where the guard is weakest. The acorn was bait.\""
+      ]
+    },
+    {
+      "id": "traffic-cone",
+      "foil": "a traffic cone",
+      "misread": "an elder who has held one stance for decades",
+      "setting": "parking lot",
+      "beats": [
+        "Weiner bows to the elder who has never once broken his stance",
+        "Weiner attempts to match him with the {stance}",
+        "Weiner hops in pain after testing the elder's stability with his foot",
+        "\"Nine years he has held it. I lasted nine seconds.\""
+      ]
+    },
+    {
+      "id": "washing-machine",
+      "foil": "a washing machine on spin cycle",
+      "misread": "a drunken-style master",
+      "setting": "laundry room",
+      "beats": [
+        "Weiner recognizes the legendary drunken style at once",
+        "he mirrors the master's trembling form into the {stance}",
+        "Weiner is on the floor; the machine clicks into rinse",
+        "\"We sparred to a draw. It is still standing. Barely.\""
+      ]
+    },
+    {
+      "id": "microwave",
+      "foil": "a microwave",
+      "misread": "an impartial judge of kata",
+      "setting": "kitchen",
+      "beats": [
+        "Weiner performs the {stance} before the unblinking judge",
+        "he holds the final pose, awaiting the verdict",
+        "DING. his leftovers are ready",
+        "\"The bell. A perfect score. The judge does not lie.\""
+      ]
+    },
+    {
+      "id": "pigeon",
+      "foil": "a pigeon standing on one leg",
+      "misread": "the last living master of crane style",
+      "setting": "rooftop",
+      "beats": [
+        "Weiner begs the master to teach him the {stance}",
+        "he copies the master's form exactly",
+        "the pigeon flies away mid-lesson",
+        "\"The final lesson: leave before the student surpasses you.\""
+      ]
+    },
+    {
+      "id": "mirror",
+      "foil": "his own reflection",
+      "misread": "his strongest and most persistent rival",
+      "setting": "dojo mirror wall",
+      "beats": [
+        "Weiner faces the rival who has studied his every technique",
+        "he unleashes the {stance}; the rival matches it instantly",
+        "they glare at each other, neither blinking",
+        "\"Evenly matched. Every time. ...Suspicious.\""
+      ]
+    },
+    {
+      "id": "wind-chime",
+      "foil": "a wind chime",
+      "misread": "a sensei who speaks only in moments of true mastery",
+      "setting": "porch",
+      "beats": [
+        "Weiner performs the {stance} for the silent sensei",
+        "he holds the pose, waiting for the sensei's voice",
+        "the wind does not blow",
+        "\"Silence. The highest praise.\""
+      ]
+    },
+    {
+      "id": "wet-floor-sign",
+      "foil": "a wet floor sign",
+      "misread": "a fellow practitioner of the wide stance",
+      "setting": "supermarket aisle",
+      "beats": [
+        "Weiner salutes a brother of the stance, training even here",
+        "he joins him, sinking into the {stance}",
+        "Weiner is flat on the wet floor beside the unmoved sign",
+        "\"He warned me. A true master teaches without words.\""
+      ]
+    }
+  ]
+}

stance_features.py

@@ -0,0 +1,162 @@
+"""Shared stance feature library: geometric features over one canonical pose frame
+(posed_joints [22,3], SMPL-X 22, y-up, heading 0 = facing +Z, feet grounded at y=0).
+
+Used by: candidate scoring (the sensei's judging spec), pose phrases (LLM/image-prompt
+facts), gag facts (why a candidate lost), and stance-card stats. Pure numpy, no LLM —
+language models consume the OUTPUT of this module and never do spatial reasoning."""
+from __future__ import annotations
+
+import numpy as np
+
+PARENTS = [-1, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 9, 9, 12, 13, 14, 16, 17, 18, 19]
+PEL, LHIP, RHIP, LKNEE, RKNEE, LANK, RANK = 0, 1, 2, 4, 5, 7, 8
+LFOOT, RFOOT, HEAD, LWR, RWR = 10, 11, 15, 20, 21
+
+
+def _angle(P, a, b, c):
+    u, v = P[a] - P[b], P[c] - P[b]
+    cos = np.dot(u, v) / (np.linalg.norm(u) * np.linalg.norm(v) + 1e-9)
+    return float(np.degrees(np.arccos(np.clip(cos, -1, 1))))
+
+
+def compute_features(Pf) -> dict:
+    """All scalar features for one frame. Keys are stable — scoring specs, the
+    phrase table, and card stats all reference them by name."""
+    P = np.asarray(Pf, np.float32)
+    feats = {
+        "pelvis_height": float(P[PEL, 1]),
+        "head_height": float(P[HEAD, 1]),
+        "left_foot_h": float(P[LFOOT, 1]),
+        "right_foot_h": float(P[RFOOT, 1]),
+        "foot_spread": float(np.hypot(P[LFOOT, 0] - P[RFOOT, 0], P[LFOOT, 2] - P[RFOOT, 2])),
+        "fb_separation": float(abs(P[LFOOT, 2] - P[RFOOT, 2])),
+        "knee_angle_l": _angle(P, LHIP, LKNEE, LANK),
+        "knee_angle_r": _angle(P, RHIP, RKNEE, RANK),
+        "reach_l": float(np.linalg.norm(P[LWR] - P[PEL])),
+        "reach_r": float(np.linalg.norm(P[RWR] - P[PEL])),
+        "wrist_h_l": float(P[LWR, 1]),
+        "wrist_h_r": float(P[RWR, 1]),
+        "wrist_fwd_l": float(P[LWR, 2] - P[PEL, 2]),   # +Z = forward at heading 0
+        "wrist_fwd_r": float(P[RWR, 2] - P[PEL, 2]),
+        "wrist_lat_l": float(abs(P[LWR, 0] - P[PEL, 0])),
+        "wrist_lat_r": float(abs(P[RWR, 0] - P[PEL, 0])),
+    }
+    feats["foot_h_max"] = max(feats["left_foot_h"], feats["right_foot_h"])
+    feats["foot_h_min"] = min(feats["left_foot_h"], feats["right_foot_h"])
+    feats["reach_max"] = max(feats["reach_l"], feats["reach_r"])
+    feats["knee_min"] = min(feats["knee_angle_l"], feats["knee_angle_r"])
+    return feats
+
+
+def score(Pf, spec) -> float:
+    """Sensei judging: spec = [{feature, weight, direction: 'max'|'min'}].
+    Linear weighted sum; direction 'min' negates. Same spec format the LLM emits."""
+    feats = compute_features(Pf)
+    total = 0.0
+    for item in spec:
+        v = feats.get(item["feature"], 0.0)
+        w = float(item.get("weight", 1.0))
+        total += -w * v if item.get("direction") == "min" else w * v
+    return total
+
+
+# ------------------------------------------------------------------ pose phrase
+
+def pose_phrase(feats: dict) -> str:
+    """Human/LLM/image-prompt description of the pose. Ordered rules, most
+    salient first, max 4 clauses."""
+    f = feats
+    parts = []
+    inverted = f["head_height"] < f["pelvis_height"] - 0.05
+    # canon() grounds Y_min to 0, so true airborne is undetectable — both feet
+    # clearly off the ground is the closest proxy (tucked/jump poses).
+    airborne = f["foot_h_min"] > 0.25 and f["pelvis_height"] > 0.55
+    # one foot clearly higher than the other = a kick/raise, even if the low
+    # foot isn't exactly at 0 (mid-air kicks post-canon).
+    lifted = f["foot_h_max"] > 0.45 and (f["foot_h_max"] - f["foot_h_min"]) > 0.35
+    if inverted:
+        parts.append("body inverted upside down")
+    elif lifted:
+        side = "left" if f["left_foot_h"] > f["right_foot_h"] else "right"
+        knee = f["knee_angle_l"] if side == "left" else f["knee_angle_r"]
+        kick = f"{side} leg extended high" if knee > 140 else f"{side} knee raised high"
+        if airborne:
+            parts.append(f"leaping in mid-air, {kick}")
+        else:
+            parts.append(kick)
+    elif airborne:
+        parts.append("leaping in mid-air, body tucked")
+    else:
+        if f["pelvis_height"] < 0.45:
+            parts.append("body low to the ground")
+        elif f["pelvis_height"] < 0.88:
+            parts.append("hips low in a deep stance")
+        if f["fb_separation"] > 0.5 and f["fb_separation"] > 0.65 * f["foot_spread"]:
+            parts.append("one foot far forward in a long stance")
+        elif f["foot_spread"] > 1.0:
+            parts.append("feet very wide apart")
+        elif f["foot_spread"] > 0.75:
+            parts.append("feet wide apart")
+    # arms
+    fwd = max(f["wrist_fwd_l"], f["wrist_fwd_r"])
+    if fwd > 0.35 and max(f["wrist_h_l"], f["wrist_h_r"]) > 0.75:
+        side = "left" if f["wrist_fwd_l"] > f["wrist_fwd_r"] else "right"
+        parts.append(f"{side} fist thrust forward")
+    elif fwd > 0.3 and min(f["wrist_h_l"], f["wrist_h_r"]) < 0.55 and not inverted:
+        parts.append("fist swept low across the body")
+    elif f["wrist_lat_l"] > 0.45 and f["wrist_lat_r"] > 0.45:
+        parts.append("arms spread wide")
+    elif f["reach_max"] < 0.45:
+        parts.append("fists guarding")
+    # support leg
+    if not inverted and not airborne and lifted and f["knee_min"] > 155:
+        parts.append("support leg straight")
+    return ", ".join(parts[:4]) if parts else "standing naturally"
+
+
+# ------------------------------------------------------------------- gag facts
+
+_LOW_PHRASES = {
+    "foot_h_max": "the kicking foot barely left the ground",
+    "reach_max": "the arms drooped at his sides",
+    "foot_spread": "the feet stayed timidly together",
+    "fb_separation": "no step forward at all",
+    "wrist_fwd_l": "the punch never left the chest",
+    "wrist_fwd_r": "the punch never left the chest",
+}
+_HIGH_PHRASES = {
+    "pelvis_height": "the hips stayed stubbornly high",
+    "knee_min": "the knees refused to bend",
+}
+
+
+def gag_facts(loser_feats: dict, spec, top_n: int = 2) -> list[str]:
+    """Why the worst candidate lost, in words — feeds the comic's panel-3 gag.
+    Picks the spec features where the loser scored most against the direction."""
+    scored = []
+    for item in spec:
+        k = item["feature"]
+        v = loser_feats.get(k, 0.0)
+        w = float(item.get("weight", 1.0))
+        if item.get("direction") == "min":
+            scored.append((v * w, _HIGH_PHRASES.get(k, f"{k} stayed high")))
+        else:
+            scored.append((-v * w, _LOW_PHRASES.get(k, f"{k} fell short")))
+    scored.sort(reverse=True)
+    return [phrase for _, phrase in scored[:top_n]]
+
+
+# ------------------------------------------------------------------ card stats
+
+def card_stats(feats: dict) -> dict:
+    """0-99 trading-card stats — the same features the sensei judges by."""
+    def clip99(x):
+        return int(np.clip(x, 1, 99))
+    f = feats
+    return {
+        "HEIGHT": clip99(f["foot_h_max"] / 1.5 * 99),
+        "REACH": clip99(f["reach_max"] / 0.85 * 99),
+        "SPREAD": clip99(f["foot_spread"] / 1.2 * 99),
+        "DEPTH": clip99((1.05 - f["pelvis_height"]) / 0.6 * 99),
+        "BALANCE": clip99((f["foot_h_max"] - f["foot_h_min"]) / 0.9 * 99),
+    }