@genex-ai/cli-demo 0.61.0-dev.141 → 0.62.0-dev.144

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.61.0-dev.141",
+  "version": "0.62.0-dev.144",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/character/meshy/meshy-loader.ts

@@ -12,6 +12,7 @@ export type MeshyMotionPolicy =
 export type MeshyLocomotionBindingMode = "loop" | "one-shot" | "pose";
 
 export interface MeshyLocomotionBinding {
+  actionId?: number;
   clip: string;
   mode: MeshyLocomotionBindingMode;
   phase?: number;
@@ -23,7 +24,20 @@ export interface MeshyCharacterManifest {
   revision: number;
   manifestVersion: number;
   rig: "meshy-biped";
-  controllerPack?: { key: string; version: number };
+  controllerPack?: {
+    key: string;
+    version: number;
+    fingerprint?: string;
+    actionIds?: number[];
+  };
+  provenance?: {
+    provider: "meshy";
+    aiModel: "meshy-6";
+    apiVersion?: string;
+    poseMode: "a-pose" | "t-pose";
+    shouldRemesh: boolean;
+    targetPolycount: number;
+  };
   model: {
     url: string;
     heightMeters: number | null;

package/templates/skills/genex-ai-character/SKILL.md

@@ -16,10 +16,12 @@ crossfades, transition rules, and multiplayer authority contract.
 npx genex character "stylized desert courier, practical layered clothing"
 ```
 
-The default request uses Meshy 6 to generate and texture an A-pose humanoid,
-validates the rig's arm pose, and retries the full generation once in a strict
-T-pose before requesting controller-pack animations when the A-pose is invalid.
-It remeshes and rigs the accepted model, adds the preview-reviewed neutral-v2
+The default request uses Meshy 6 to generate, texture, remesh, and rig an
+A-pose humanoid. It generates the required controller-pack actions for that
+candidate and rejects bad structural or native motion instead of repairing it.
+If any required check fails, it retries the complete workflow once in a strict
+T-pose; optional actions start only after a full candidate passes. It remeshes
+and rigs the accepted model, adds the immutable preview-reviewed neutral-v3
 idle/walk/run/crouch/jump controller pack,
 and stores every successful model
 and clip at permanent Genex asset URLs. It prints the complete Genex-credit
@@ -83,6 +85,17 @@ after preview without asking the player to disable cache.
 `playOneShot()` returns false and emits one warning when a requested clip is
 absent; treat that as an installation failure, not a successful action.
 
+Meshy limb rotations are played unchanged. Never freeze hand tracks or apply
+post-mixer arm, leg, or foot corrections. A bad native rig or clip must be
+rejected and regenerated. Only horizontal root/hip translation is normalized
+so Rapier remains authoritative.
+
+A controller pack is an immutable exact action set. If a required binding is
+absent, installation fails instead of substituting Meshy's rig-basic Walking
+or Running animation. During Meshy validation, record the action ID actually
+bound to every slot. A public preview is not evidence when the game is playing
+a different clip or a rig-basic fallback.
+
 Load `$genex-threejs-character-controller` for the actual wiring. The install
 command copies the shared controller plus `character/meshy/meshy-loader.ts`.
 The manifest points at the current rigged model and compact animation-only GLBs
@@ -93,6 +106,8 @@ durations, nominal speeds, trajectories, and gameplay requirements.
 
 - Meshy clips play only on the exact character revision whose skeleton
   signature matches. There is no runtime retargeting in this lane.
+- Do not repair hands, arms, or legs at runtime. Verify the installed manifest's
+  exact slot-to-action mappings; stop and regenerate when a native pose is bad.
 - Rapier owns the player transform. Animation tracks are normalized
   horizontally in place; never move the rendered character root separately.
 - `controller-loop` clips follow controller-local intent and measured speed.

package/templates/skills/genex-ai-menu/SKILL.md

@@ -126,6 +126,19 @@ after the UI plan gate, enqueue the video with `--no-wait`, ship the CSS menu
 (R2) — permanent, public, CORS-open; you load them straight from the printed
 URLs, nothing is downloaded or committed.
 
+**Two failed video attempts = ship the still. Hard stop.** Video is the one
+generation that fails server-side with real frequency (render timeouts), and
+every attempt costs minutes of waiting. One retry is fair — shorten the clip
+(4–6 s) and simplify the motion prompt. After a SECOND failure, stop
+generating: keep the key-art still as the menu background and give it life
+for free with a slow CSS pan/zoom (`transform: scale(1.06)` over ~20 s,
+alternating), tell the user in one plain line ("the animated menu backdrop
+kept failing, so your menu uses the key art — looks great, costs nothing"),
+and spend those minutes in the game. A third attempt is how half an hour
+disappears into chrome — the CLI counts failures and reminds you at the
+second one. The still-image menu is a real menu: this rule is the built-in
+fallback, not a downgrade to apologize for.
+
 ## Wire it as a phase screen
 
 The menu is one `data-phase` screen in the `$genex-threejs-game-ui`

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -50,6 +50,13 @@ after preview without asking the player to disable cache. `playOneShot()`
 returns false and emits one warning when a requested clip is absent; treat
 that as an installation failure, not a successful action.
 
+Meshy limb rotations are played unchanged. Never freeze hand tracks or apply
+post-mixer arm, leg, or foot corrections. A bad native rig or clip must be
+rejected and regenerated. Only horizontal root/hip translation is normalized
+so Rapier remains authoritative. A controller pack is an immutable exact
+action set: if a required binding is absent, installation fails instead of
+substituting Meshy's rig-basic Walking or Running animation.
+
 Because these files are game-owned, never run `genex controller character --force` over an edited
 fork as a migration strategy. Install a fresh copy elsewhere and port only the named changes.
 
@@ -200,6 +207,10 @@ slots, fallbacks, and cadence data. UAL clips still land in
 genre hints, `playOneShot` options, overrides, foot IK, and remote-player
 animation.
 
+For Meshy characters, do not repair hands, arms, or legs at runtime. Verify
+that the installed manifest binds the expected action IDs; if a native pose
+is bad or a required binding is missing, stop and regenerate the character.
+
 ## Crouch (built in)
 
 `C` toggles crouch (capsule shrinks, speed drops to `crouchSpeedRatio ×

package/templates/skills/genex-threejs-character-controller/references/animations.md

@@ -110,6 +110,11 @@ const anims = new CharacterAnimations(native.scene, native.clips, {
 });
 ```
 
+During Meshy validation, record the action ID actually bound to every slot.
+A public preview is not evidence when the game is playing a different clip or
+a rig-basic fallback. The native loader plays every limb quaternion unchanged;
+never freeze hand tracks or add post-mixer arm, leg, or foot corrections.
+
 The loader rejects clips whose manifest skeleton signature differs from the
 current model revision or whose tracks target missing bones. This is deliberate
 same-rig playback, not runtime retargeting. After adding an action, rerun the

package/templates/skills/genex-threejs-game-content/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: genex-threejs-game-content
+description: Turn a content-shaped request — quests, NPCs, dialogue, shops, loot, XP — into a countable content contract and the data-driven systems that ship it. Use when the ask names game content in the plural or a content genre (RPG, adventure, story, open world), BEFORE the asset batch, and before calling such a game done.
+---
+
+# Genex Three.js Game Content
+
+The most common way a content-shaped request fails is not bad code — it is the
+ask silently shrinking: "quests" ships as one hardcoded integer, "NPCs" as
+empty textured huts, "a big world" as one small fogged plane, while every
+visual floor passes, because content is invisible to a screenshot. This skill
+gives content the same teeth the look has: a countable contract written up
+front, data-driven systems that make each contract line cheap to ship, and a
+floor that gates publish.
+
+## The content contract — write it before the asset batch
+
+Run this the moment the game concept is locked, in the SAME plan message as
+`$genex-threejs-game-ui`'s UI gate, whenever the request names content in the
+plural (quests, enemies, bosses, locations, spells, items, factions…) or a
+content genre (an RPG, an adventure, an open world, a story game, a survival
+game). **Walk every plural noun of the request and make each one a countable
+line.** The template:
+
+```
+CONTENT CONTRACT — <game>
+world:       <size class, as a number: one arena | a district (~500 m) | open world (km-class — $genex-threejs-open-world)>
+locations:   <N, named: village, crypt, bandit camp, watchtower, boss lair…>
+quests:      <N total — a main chain of M gated steps + side quests; each giver named>
+NPCs:        <N speaking (quest givers, merchants) + M flavor villagers>
+enemies:     <N types + where they spawn; which are bosses and what makes each boss FIGHT differently>
+progression: <what grows: XP/levels, gear tiers, learnable abilities — the numbers and their rewards>
+economy:     <currency sources AND sinks — what the player earns and what they spend it on>
+minute ten:  <one sentence: what is the player DOING ten minutes in, and why is it different from minute one?>
+```
+
+Rules that make the contract real:
+
+- **It comes before the asset batch.** The asset set derives from the
+  contract — a world with six locations and four enemy types needs a
+  different `npx genex model` list than one arena, and finding that out after
+  the batch means the world gets shaped around the wrong assets.
+- **Every line is a floor.** Publish and the final handoff wait for the
+  contract's countables exactly the way they wait for the sprite HUD: a
+  request that said "quests" is not done with one; a request that said "big
+  world" is not done with an arena.
+- **Scope belongs to the user.** Building a small first slice is the right
+  ORDER (`$genex-threejs-game-ui`'s v0 beat still applies) — but the slice is
+  a milestone on the way to the contract, never a quiet replacement for it.
+  If the full ask genuinely doesn't fit, shrinking any line is a structured
+  question to the user with real options — never a silent cut justified as
+  "standard practice".
+- **Minute ten is the design test.** If the honest answer is "the same sixty
+  seconds, again", the contract needs another beat (a new area unlocks, a
+  quest chain escalates, a build comes online) before any polish work.
+
+## Data-driven, or you won't finish in one session
+
+The reason a solo agent can ship seven quests and seventeen items in an
+afternoon is architecture, not typing speed:
+
+- **Systems read tables; content lives in tables.** The quest engine, the
+  dialogue walker, the merchant screen, and the spawner are each written
+  ONCE; quest #5, item #12, and enemy #4 are table rows. If adding a quest
+  means touching engine code, the engine is wrong.
+- **Hand-author the beats, table-drive the bulk, seed the placement.** Quest
+  prose, boss mechanics, and location identities deserve human-quality
+  authoring; stats, stocks, and rewards are data; trees, rocks, and chest
+  scatter come from a seeded RNG so "more world" costs zero authoring.
+- **One event bus.** Quests advance on events the game already emits
+  (`enemy:died`, `item:pickup`, `chest:opened`, `npc:talked`, `zone:entered`)
+  — the quest system subscribes; combat and loot never know quests exist.
+  This is also what makes quest logic testable in isolation.
+
+The full engine — quest defs + state machine, dialogue trees with quest
+hooks, merchant stocks, XP curve — is in
+[references/content-tables.md](references/content-tables.md) as copy-paste
+modules. Copy them and fill the tables; don't re-derive the shape.
+
+## Quests: defs + events, never an integer
+
+The minimum honest quest system is a table of defs and an event-driven state
+machine (`locked → available → active → ready → done`), with prereq gating for
+the main chain:
+
+```ts
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;            // NPC id — every quest has a face, not a board
+  prereq?: string;          // quest id that must be done first (main chain)
+  title: string;
+  brief: string;            // 2–3 sentences of authored prose, not filler
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+```
+
+Progress comes only from the event bus (see the reference for the ~60-line
+engine). A tracked quest gets a compass/journal marker
+(`$genex-threejs-game-ui` inventories the journal as a screen element), and
+turn-in happens in dialogue — handing in a quest should feel like talking to
+a person, not watching a counter flip.
+
+## Dialogue: trees with quest hooks
+
+Quest givers and merchants speak. The walker is a dozen lines (reference file)
+over nodes of `{ text, options: [{ label, next | action }] }`; what makes it a
+QUEST system is three dynamic option states injected per NPC: **offer** (quest
+available → "I might have work for you"), **remind** (active → restate the
+objective), **turn-in** (ready → hand rewards, open the next chain link). Add
+a couple of lore branches per named NPC — three authored lines is the
+difference between a person and a signpost. A quest board is an acceptable
+extra for arcade-shaped games; it is never the replacement for speaking
+NPCs when the ask said "NPCs".
+
+## Items, shops, and an economy that closes
+
+An item catalog (id, kind, price, stats), stack-based inventory, and merchant
+stock tables per vendor NPC — all data (reference file). The rule that keeps
+it a game: **currency needs sinks.** Gold the player can only accumulate is a
+score with a coin icon; gold that buys potions, a better sword, and a spell
+tome is an economy. Price the first upgrade to be affordable after the first
+quest, and let drops + chest loot + quest rewards all feed the same wallet.
+
+## Progression: something must grow
+
+Pick at least one growth axis and wire its rewards into the quest/enemy
+tables: an XP curve (`xpNext = 100 * level ** 1.4` is a fine default) with
+flat stat gains per level, gear tiers on the merchant, or learnable abilities
+gated behind tomes/trainers. The contract names which; "nothing grows" is what
+makes minute ten feel like minute one.
+
+## NPCs: the minimum that reads as alive
+
+A named NPC with a role, a home spot, an idle bob, a face-the-player turn
+within a few meters, and dialogue reads as a person — schedules and pathing
+are optional upgrades, speech is not. Place speaking NPCs (givers, merchants)
+by hand at their locations; scatter flavor villagers with one-line barks from
+a table. An empty textured hut village fails the "NPCs" line of any contract.
+For host-simulated NPCs/enemies in multiplayer, `$genex-threejs-multiplayer`
+owns the authority rules.
+
+## Content that can't dead-end — check before shipping
+
+- A kill/collect quest counts progress made BEFORE acceptance (or the brief
+  says why not) — "kill 5 bandits" accepted after clearing the camp must not
+  strand at 0/5.
+- A quest item from a unique source (a boss drop, a one-time chest) must
+  persist until picked up — the source never respawns, so expiring the drop
+  dead-ends the chain.
+- The main chain gates on prereqs, not on geography alone — reaching the
+  final lair early should show a locked door or a warning, not a sequence
+  break that skips the story.
+- The turn-in NPC is reachable after the objective (didn't die in the wave,
+  isn't locked behind the boss arena).
+- Saves restore quest state AND its world side-effects — the opened chest
+  stays open, the armed boss stays armed. Quest stages, inventory, XP, and
+  gold go in the per-player slot via `$genex-threejs-embed-auth`.
+
+## Wiring into the rest of the pack
+
+- World layout, terrain, and location placement at scale:
+  `$genex-threejs-open-world` (the contract's `world:` line decides whether
+  it loads).
+- Quest journal, tracker, toasts, vendor screens: inventory them at
+  `$genex-threejs-game-ui`'s gate — they are screen elements like any other.
+- Level-ups, quest completion, and boss kills are exactly the "moments" the
+  feel pass layers feedback on: `$genex-threejs-game-feel` + a real
+  `npx genex sfx` fanfare (`$genex-ai-sfx`).
+- Location set pieces and speaking-NPC meshes: `$genex-ai-model` /
+  `$genex-ai-character` — generated assets decorate the contract's landmarks;
+  they never decide how many exist.
+
+## Failure modes to catch
+
+- "Quests" (plural, in the ask) shipped as one quest — a stage integer with
+  hardcoded strings and no giver.
+- A village of textured huts where nobody speaks.
+- A gold counter with nothing to spend it on.
+- No growth axis: the player at minute thirty plays exactly like minute one.
+- The contract posted, then quietly abandoned when the first slice previewed
+  well — the slice is a milestone, not the destination.
+- Contract lines silently shrunk without a structured question to the user.

package/templates/skills/genex-threejs-game-content/references/content-tables.md

@@ -0,0 +1,269 @@
+# Genex game content — copy-paste systems
+
+Four small modules that turn contract lines into shipped content: an event
+bus, a quest engine, a dialogue walker with quest hooks, and items/economy +
+XP. Copy them, fill the tables, and keep content OUT of engine code — adding
+a quest, an item, or a vendor must always be a table edit.
+
+All snippets are plain vanilla-ts (no enums, no decorators) and assume a
+single shared game-state object `G` you already have (player stats, wallet,
+the scene). Adapt names, not shapes.
+
+## 1. Event bus — the only coupling
+
+```ts
+// events.ts — combat, loot, and movement EMIT; quests and UI SUBSCRIBE.
+type GameEvent =
+  | { type: "enemy:died"; enemyKind: string }
+  | { type: "item:pickup"; item: string; count: number }
+  | { type: "chest:opened"; chestId: string }
+  | { type: "npc:talked"; npc: string }
+  | { type: "zone:entered"; location: string };
+
+type Handler = (e: GameEvent) => void;
+const handlers: Handler[] = [];
+
+export function onEvent(h: Handler): void {
+  handlers.push(h);
+}
+export function emit(e: GameEvent): void {
+  for (const h of handlers) h(e);
+}
+```
+
+## 2. Quest engine — defs are data, progress is events
+
+```ts
+// quests.ts
+import { onEvent } from "./events.ts";
+
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;
+  prereq?: string;
+  title: string;
+  brief: string;
+  turnIn: string; // authored prose for the hand-in moment
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+
+// CONTENT — the whole quest list lives here. Main chain via prereq; the
+// prose is authored, not generated filler. Counts must match the contract.
+export const QUESTS: QuestDef[] = [
+  {
+    id: "q_wolves",
+    giver: "elder",
+    title: "Teeth in the Tall Grass",
+    brief:
+      "Wolves have taken the shepherd's flock and now they circle the palisade at dusk. Thin the pack before someone's child is next.",
+    turnIn: "Five pelts. The flock sleeps easy tonight — and so do we. Take this.",
+    objective: { kind: "kill", target: "wolf", count: 5 },
+    rewards: { gold: 40, xp: 60 },
+  },
+  {
+    id: "q_amulet",
+    giver: "elder",
+    prereq: "q_wolves",
+    title: "What the Crypt Keeps",
+    brief:
+      "Our founder's amulet lies in the old crypt east of the fields. The dead have grown restless around it — bring it back, and mind the narrow dark.",
+    turnIn: "The amulet… after all these years. You have the village's gratitude, and its coin.",
+    objective: { kind: "collect", item: "founder_amulet", count: 1 },
+    rewards: { gold: 80, xp: 120, items: ["potion_health"] },
+  },
+  // …side quests: no prereq, different givers, different objective kinds.
+];
+
+type QuestStatus = "locked" | "available" | "active" | "ready" | "done";
+type QuestState = { status: QuestStatus; progress: number };
+
+export const questState = new Map<string, QuestState>();
+for (const q of QUESTS) {
+  questState.set(q.id, { status: q.prereq ? "locked" : "available", progress: 0 });
+}
+
+const def = (id: string): QuestDef => QUESTS.find((q) => q.id === id)!;
+
+export function accept(id: string): void {
+  const s = questState.get(id)!;
+  if (s.status !== "available") return;
+  s.status = "active";
+  // Contract check "can't dead-end": count pre-acceptance progress where the
+  // fiction allows it (kills already made), or reset knowingly.
+}
+
+export function turnIn(id: string): { gold: number; xp: number; items: string[] } | null {
+  const s = questState.get(id)!;
+  if (s.status !== "ready") return null;
+  s.status = "done";
+  for (const q of QUESTS) {
+    if (q.prereq === id && questState.get(q.id)!.status === "locked") {
+      questState.get(q.id)!.status = "available"; // next chain link opens
+    }
+  }
+  const r = def(id).rewards;
+  return { gold: r.gold ?? 0, xp: r.xp ?? 0, items: r.items ?? [] };
+}
+
+function bump(q: QuestDef, s: QuestState, amount = 1): void {
+  const needed = "count" in q.objective ? q.objective.count : 1;
+  s.progress = Math.min(needed, s.progress + amount);
+  if (s.progress >= needed) s.status = "ready"; // journal + marker flip to "return"
+}
+
+onEvent((e) => {
+  for (const q of QUESTS) {
+    const s = questState.get(q.id)!;
+    if (s.status !== "active") continue;
+    const o = q.objective;
+    if (o.kind === "kill" && e.type === "enemy:died" && e.enemyKind === o.target) bump(q, s);
+    if (o.kind === "collect" && e.type === "item:pickup" && e.item === o.item) bump(q, s, e.count);
+    if (o.kind === "reach" && e.type === "zone:entered" && e.location === o.location) bump(q, s);
+    if (o.kind === "talk" && e.type === "npc:talked" && e.npc === o.npc) bump(q, s);
+  }
+});
+```
+
+Journal UI, the tracked-quest compass marker, and toasts subscribe to the
+same state — inventory them as screen elements at `$genex-threejs-game-ui`'s
+gate. Persist `[...questState]` (plus world side-effects like opened chests)
+in the per-player slot via `$genex-threejs-embed-auth`.
+
+## 3. Dialogue walker — quest states become options
+
+```ts
+// dialogue.ts
+import { QUESTS, questState, accept, turnIn } from "./quests.ts";
+
+type DialogueOption = { label: string; next?: DialogueNode; action?: () => void };
+type DialogueNode = { text: string; options: DialogueOption[] };
+
+// CONTENT — per-NPC roots: greeting + a couple of authored lore branches.
+// Three real lines is the difference between a person and a signpost.
+const ROOTS: Record<string, DialogueNode> = {
+  elder: {
+    text: "Maren watches the road as she talks. “Strangers used to mean trade. Lately they mean trouble.”",
+    options: [
+      {
+        label: "Tell me about this village.",
+        next: {
+          text: "“Three generations behind this palisade. The crypt east of here is older than all of it — and lately, louder.”",
+          options: [],
+        },
+      },
+    ],
+  },
+  // blacksmith, herbalist… — every giver and merchant has a root.
+};
+
+// The whole walker: render node.text + numbered options; a click (or the
+// 1–9 key) runs option.action?.(), then shows option.next or closes. Emit
+// { type: "npc:talked", npc } when a conversation OPENS — that's what "talk"
+// objectives listen for.
+export function pickOption(node: DialogueNode, index: number): DialogueNode | null {
+  const opt = node.options[index];
+  if (!opt) return node;
+  opt.action?.();
+  return opt.next ?? null; // null = close the dialogue panel
+}
+
+export function openDialogue(npc: string): DialogueNode {
+  const root = ROOTS[npc];
+  const options = [...root.options];
+  for (const q of QUESTS) {
+    if (q.giver !== npc) continue;
+    const s = questState.get(q.id)!;
+    if (s.status === "available") {
+      options.unshift({
+        label: `[Quest] ${q.title}`,
+        next: {
+          text: q.brief,
+          options: [
+            { label: "I'll do it.", action: () => accept(q.id) },
+            { label: "Not now." },
+          ],
+        },
+      });
+    } else if (s.status === "active") {
+      options.unshift({ label: `[${q.title}] Remind me.`, next: { text: q.brief, options: [] } });
+    } else if (s.status === "ready") {
+      options.unshift({
+        label: `[Complete] ${q.title}`,
+        next: { text: q.turnIn, options: [] },
+        action: () => {
+          const r = turnIn(q.id);
+          // …grant r.gold / r.xp / r.items through your wallet + inventory.
+        },
+      });
+    }
+  }
+  return { text: root.text, options };
+}
+```
+
+## 4. Items, merchants, XP — the economy that closes
+
+```ts
+// items.ts
+type ItemDef = {
+  id: string;
+  kind: "weapon" | "armor" | "potion" | "quest" | "tome";
+  name: string;
+  price: number; // what merchants charge — the SINK side of the economy
+  stats?: { dmg?: number; armor?: number; heal?: number };
+};
+
+export const ITEMS: ItemDef[] = [
+  { id: "sword_iron", kind: "weapon", name: "Iron Sword", price: 120, stats: { dmg: 18 } },
+  { id: "potion_health", kind: "potion", name: "Health Draught", price: 25, stats: { heal: 40 } },
+  { id: "founder_amulet", kind: "quest", name: "Founder's Amulet", price: 0 },
+  // …the catalog. Price the first upgrade to land right after the first quest's gold.
+];
+
+// Merchant stock is per-NPC data — a second vendor is one more entry.
+export const STOCKS: Record<string, string[]> = {
+  blacksmith: ["sword_iron", "armor_leather"],
+  herbalist: ["potion_health", "potion_mana"],
+};
+
+// XP curve + level rewards: one growth axis, wired to quest/enemy rewards.
+export const xpNext = (level: number): number => Math.round(100 * level ** 1.4);
+export function addXp(player: { level: number; xp: number; maxHp: number; hp: number }, amount: number): void {
+  player.xp += amount;
+  while (player.xp >= xpNext(player.level)) {
+    player.xp -= xpNext(player.level);
+    player.level += 1;
+    player.maxHp += 12;
+    player.hp = player.maxHp; // level-up heals — a reward the player FEELS
+  }
+}
+```
+
+## Seeded placement — bulk content for free
+
+Scatter the non-authored bulk (chests, camps, flavor spawns) with a seeded
+RNG so the world is deterministic across loads and machines:
+
+```ts
+export function seededRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 0xffffffff;
+  };
+}
+// const rng = seededRng(1337): place 10 chests at rng()-driven offsets around
+// locations, skip water/steep slopes via the world's height/biome lookups
+// ($genex-threejs-open-world), and hand-place only the authored few.
+```
+
+Hand-authored where it matters (quest prose, boss mechanics, unique loot),
+tables for the bulk, seeds for the scatter — that split is what lets one
+session ship the whole contract.