@maka/maka-cli 5.4.0 → 5.5.0

package/bundle/typescript/src/commands/game/sideQuest/factories/scene-seed-generator.js

@@ -5,417 +5,161 @@ import { Player } from '../models/player.js';
 import { Room } from '../models/room.js';
 import { Logger } from '../utilities/logger.js';
 import { SceneSynthesizer } from './scene-factory.js';
-// The fixer's name is a fixed Shadowrun-lore convention (see the FIXER
-// CONVENTION comment in buildSchemaGuide below), not something generation
-// ever varies -- exported so callers that need to identify "the fixer"
-// specifically (as opposed to whoever a job's winCondition.toNpc happens to
-// be, which no longer has to be the same NPC) can check by name instead of
-// duplicating the literal string.
-export const FIXER_NAME = 'Mr. Johnson';
-function buildSchemaGuide(tier, previousFixerName) {
-    const scope = tier <= 1
-        ? '3 to 4 rooms, exactly 1 NPC, and exactly 1 puzzle'
-        : tier === 2
-            ? '4 to 5 rooms, 2 NPCs, and 1 to 2 puzzles'
-            : '5 to 6 rooms, 2 to 3 NPCs, and 2 puzzles';
-    const continuity = previousFixerName
-        ? `\nThis is a CONTINUATION of an ongoing relationship with the same fixer, "${previousFixerName}" --
-who commissioned the runner's last job and is the one lining up this one too. Reuse
-"${previousFixerName}" as this scene's fixer/job-giver (same name, same voice/personality),
-rather than inventing a new fixer character. Do not reintroduce them as a stranger; the
-runner already knows them.`
-        : '';
-    return `
-You are generating a small, self-contained Shadowrun-flavored text adventure "run" as JSON.
-This is job #${tier} in an ongoing campaign for the same runner -- make it noticeably more
-elaborate and higher-stakes than a first job would be, in proportion to how high the job
-number is.
-${continuity}
-
-Output ONLY raw JSON matching this exact shape -- no markdown fences, no commentary, no
-trailing text before or after the JSON object:
-
-{
-  "name": string,
-  "story": string, // 1-2 SHORT sentences, shown to the player before anything else
-                    // happens. This is a premise teaser, not a briefing -- name the
-                    // general shape of the trouble (a theft, a debt, a betrayal) and
-                    // nothing more. Never reveal the objective, a target's name or
-                    // location, a passphrase, a twist, or anything a player would need
-                    // to actually complete the run -- all of that belongs in the fixer's
-                    // "dialogue" instead, learned by "call"ing them once play begins (see
-                    // the fixer convention below). If this reads like a back-cover blurb
-                    // rather than a full plot summary, it's the right length.
-  "currency": { "type": "nuyen", "authorityRoomTags": ["Bank"] },
-  "residenceTiers": ["Street", "Squatter", "Low", "Middle", "High", "Luxury"],
-  "rooms": [
-    {
-      "name": string,
-      "description": string,
-      "roomType": string,
-      "isStartRoom"?: boolean, // set true on EXACTLY ONE room
-      "owner"?: string, // an NPC's name, if that NPC's room
-      "reachable"?: boolean, // defaults to true; set false ONLY for a fixer/employer's
-                              // remote hideout the player can never physically enter --
-                              // see the fixer convention below
-      "hasNode"?: boolean, // a live Matrix host in this room: a jacked-in player ("jack in")
-                            // can hack it from inside the Matrix to release the room's
-                            // locked doors FOR REAL. Mark 1-2 rooms in any corp/tech
-                            // location; leave street/wilderness rooms without. Ice NPCs
-                            // ("plane": "matrix") and paydata items ("plane": "matrix")
-                            // belong ONLY in hasNode rooms.
-      "warded"?: boolean, // an astral barrier: projecting mages ("project") cannot enter
-                           // this room astrally. Use on magically-secured rooms (a mage's
-                           // sanctum, a corp magical-security floor) -- it makes astral
-                           // scouting a puzzle, not a skeleton key. Use sparingly.
-      "exits": [
-        { "direction": "north"|"east"|"south"|"west"|"up"|"down", "targetRoom": string, "keyRequired"?: string,
-          "puzzle"?: string } // name of a "puzzles[]" entry that guards this door instead of (or as
-                              // well as) "keyRequired" -- see DOORS AS PUZZLES below
-      ]
-    }
-  ],
-  "npcs": [
-    {
-      "plane"?: "meat"|"matrix"|"astral", // default "meat". "matrix" = ICE: a security
-                            // program guarding a hasNode room -- only a jacked-in player
-                            // ever meets it (it fights with Logic-based pools; give it a
-                            // combat block with "logic" 4-7 and set its startLocation to
-                            // the hasNode room). "astral" = a SPIRIT: met only by
-                            // projecting mages -- give it "willpower"/"magic" 4-6 and
-                            // "intuition" 4+. Use at most one or two per scene, and only
-                            // where the location concept earns them.
-      "description": string, // private notes on personality/motives; never shown to the player directly
-      "dialogue": string[], // 2-4 short in-character lines. If this NPC is the fixer/job-giver,
-                             // THIS is where the actual briefing lives -- the objective, the
-                             // target, the stakes -- since "story" deliberately withholds it.
-      "player": { "name": string, "startLocation": string, "lifestyleChoices": [],
-        "combat"?: { "body": number, "agility": number, "reaction": number, "combatSkill": number,
-                     "magic"?: number, "strength"?: number, "willpower"?: number, "logic"?: number,
-                     "intuition"?: number, "charisma"?: number } }
-        // combat is OPTIONAL -- omit it for anyone who'd never be in a fight (a fixer, a
-        // bartender). When set, each attribute is 1-8: a soft civilian 1-2, a street-level
-        // runner 3-4 (the default when omitted), a hardened enforcer or bodyguard 5-6,
-        // elite corp security 7-8. Give a combat block (and an equipped-quality weapon/
-        // armor in "items" heldBy them) to any NPC the story expects might end up in a
-        // firefight -- combat is dice-pool based and gear quality feeds the dice.
-        // "magic" is innate arcane talent: omit (or 0) for the mundane majority. Set 3-6
-        // ONLY for a character whose concept is genuinely a mage/shaman/adept -- they'll
-        // know every spell (manabolt/heal/armor) innately with no gear needed, cast from
-        // raw talent, and should be described accordingly (their "description" should say
-        // they're Awakened). A Focus item still boosts them. Use sparingly: one Awakened
-        // NPC is a memorable threat, a scene full of them is noise.
-        // The optional extended attributes (all default ~3): "strength" (melee damage,
-        // carry), "willpower" (stun track, drain resist -- give mages 5+), "logic"
-        // (first aid, hacking -- a decker/street doc concept wants 5+), "intuition"
-        // (defense, perception), "charisma" (social presence). Set only the ones that
-        // define the character's concept; leave the rest to defaults.
-        // Rarer talents: "resonance" (technomancer -- rides the Matrix with no deck;
-        // use for a technomancer character concept only) and "adept": true (physical
-        // adept -- magic 4-6 channeled into meat combat, no spells, no projection).
-        // Never combine magic-casting, adept, and resonance on one character.
-        // A rival DECKER concept: "logic" 5-7 plus a Cyberdeck item heldBy them --
-        // their AI can then crack the player's PAN mid-fight ("hack <name>": jams
-        // the player's smartgun, cuts their AR). One per scene at most, and only
-        // where a decker belongs.
-    }
-  ],
-  "items": [
-    {
-      "name": string,
-      "description": string,
-      "size": "Tiny"|"Small"|"Medium"|"Large"|"VeryLarge",
-      "category": "Weapon"|"MeleeWeapon"|"RangedWeapon"|"Armor"|"BodyArmor"|"ArmorClothing"|"Helmet"|"Hat"|"LegArmor"|"ArmArmor"|"Gloves"|"Commlink"|"Cyberdeck"|"Drone"|"Credstick"|"CurrencyContainer"|"Key"|"Trinket"|"Document"|"Datachip"|"Vice"|"Book"|"Tool"|"Clothing"|"Glasses"|"Boots"|"Medical"|"StimPatch"|"SpellFormula"|"Grimoire"|"Focus"|"Ammunition",
-      // "Cyberdeck" = the hardware REQUIRED to jack into the Matrix (a Commlink is
-      // calls/AR only). Its "rating" scales program damage, firewall, and its own
-      // damage track. Place one as loot/reward only when the story earns it -- a
-      // dead decker's kit, a smuggled prototype. If the scene has hasNode rooms
-      // with matrix-plane paydata, remember the player may need a deck to get it
-      // (deckers and technomancers bring their own way in).
-      // "Drone" = a launchable surveillance drone: the "drone" command sweeps all
-      // adjacent rooms for occupants/locks/nodes. Rigger flavor; rare loot.
-      // "Ammunition" = a spare clip/magazine: consumed by "reload" to refill a firearm
-      // (guns hold 10 rounds and every shot spends one). If a scene arms its NPCs or
-      // player with guns and expects a real firefight, place 1-2 Ammunition items
-      // somewhere findable.
-      // "Medical" = a single-use healing item (medkit, trauma kit): using it heals
-      // PHYSICAL combat damage, scaling with "rating", and consumes it. If this scene's
-      // story can plausibly end in a firefight (armed NPCs, a "will kill on sight"
-      // guard), place 1-2 Medical items somewhere findable -- a run with combat and no
-      // way to patch up is a meat grinder.
-      // "StimPatch" = a single-use combat drug: recovers STUN damage (spell drain,
-      // knockout track), scaling with "rating", but the crash costs 1 physical box.
-      // Worth placing one wherever magic gear appears, since casters accumulate stun.
-      //
-      // MAGIC GEAR (casting is gear-driven -- no innate mage stat):
-      //   - "SpellFormula": teaches ONE spell; its "name" MUST contain that spell's name.
-      //     The only spells that exist are "Manabolt", "Heal", and "Armor" -- e.g.
-      //     "Spell Formula: Manabolt", "Dog-Eared Heal Formula". Never invent other spells.
-      //   - "Grimoire": a spellbook -- teaches ALL three spells at once. Rarer find.
-      //   - "Focus": an amulet/wand/talisman that boosts casting power, scaling with
-      //     "rating" -- the magic equivalent of a better gun.
-      // Magic is optional flavor: most scenes need none. But if any puzzle here uses
-      // "bypassType": "spell", you MUST place at least one magic item (formula, grimoire,
-      // or focus) somewhere findable -- attempting to cast at a ward now requires magic
-      // gear, so a warded barrier with no magic gear in the scene has no bypass route.
-      // Anything wearable (a hoodie, gloves, a hat, boots...) MUST use one of
-      // the above wearable categories exactly -- never a generic catch-all
-      // like "Trinket" or "Document" for something meant to be worn.
-      "shape": string,
-      "color": string,
-      "texture": string,
-      "rating": "Common"|"Standard"|"Rare"|"Legendary"|"MilitaryGrade",
-      "weight": number, // kilograms, and it's REAL -- actors have a 50kg carry cap. Keep
-                         // items individually realistic (0.05 for a chip, ~1-2 for a pistol,
-                         // ~3-5 for armor); never give a carryable item a silly weight.
-      "currencyAmount"?: number, // only for Credstick/CurrencyContainer items
-      "room"?: string, // set this OR heldBy, never both, and never on a puzzle's reward item
-      "heldBy"?: string, // must be an NPC's name from "npcs", never the player
-      "owner"?: string,
-      "transferable"?: boolean,
-      "plane"?: "meat"|"matrix"|"astral", // default "meat". "matrix" = PAYDATA: a file that
-                          // exists only on the grid -- visible and takeable ONLY while the
-                          // player is jacked in ("jack in"). Place it in a "hasNode" room
-                          // (its "room"), category "Datachip" or "Document", weight 0. A
-                          // matrix-plane win-condition item makes the whole job a datarun:
-                          // the player MUST jack in, likely past ice, to finish. Use it
-                          // when the story is about stealing data, not things.
-      "details"?: string // deeper text shown only when the player closely examines or reads
-                          // this item (via "read", for a Book) -- NOT the same as "description",
-                          // which is always-visible flavor text shown just by looking at or
-                          // listing the item. A puzzle's clue text (see below) MUST go in
-                          // "details", never in "description" -- put it in "description" and the
-                          // player can never actually read it out.
-    }
-  ],
-  "puzzles": [
-    {
-      "name": string,
-      "room"?: string, // must match a room name -- OMIT this instead if "exits[].puzzle" (see DOORS
-                        // AS PUZZLES below) already places this puzzle on a door; a puzzle belongs
-                        // to exactly one of the two, never both and never neither.
-      "riddle": string, // What the player sees when they search this room (or approach this door),
-                         // shown verbatim -- NOT a cryptic riddle or poem to decode. Start with "You
-                         // see" (or "You find", "Set into the wall is", etc.) and name the barrier
-                         // plainly and concretely -- "You see a maglock safe.", "You see a biometric
-                         // scanner beside the door." -- then say what it demands (a code, a
-                         // fingerprint, a name spoken aloud, a passphrase), the way an NPC would
-                         // describe it, never as wordplay. See BYPASS TYPE below.
-      "requiredPhrase": string, // the exact code/passphrase/word that satisfies it -- ALL LOWERCASE, 2-5 plain words, no punctuation
-      "rewardItem"?: string, // must match an item name from "items" with no "room"/"heldBy" set. Required
-                              // for a "room"-anchored puzzle (this IS what solving it gets the player).
-                              // Omit for a door-anchored puzzle (exits[].puzzle) -- unlocking the door is
-                              // already the reward; only add one if there's a genuine bonus find too.
-      "successMessage": string,
-      "failureMessage": string,
-      "requiresPuzzle"?: string, // another puzzle's "name" that must be solved FIRST -- see below
-      "lockedMessage"?: string, // shown if the player tries to solve this before requiresPuzzle is met
-      "bypassType"?: "lockpick"|"hack"|"spell" // see BYPASS TYPE below -- omit if this barrier has no
-                                                // physical/technical/magical route past it
-    }
-  ],
-  // BYPASS TYPE: decide what a puzzle concretely IS before writing its "riddle" --
-  // a maglock, a keypad, a biometric scanner, a matrix node, a warded sigil, a
-  // guard who has to be talked past. That choice drives BOTH fields together:
-  // "riddle" describes THAT thing plainly (never as a cryptic riddle-poem), and
-  // "bypassType" names the matching physical/technical/magical route past it, if
-  // any: a literal lock, maglock, or keypad -> "lockpick", a terminal/console/
-  // matrix node or electronic scanner -> "hack", a ward or arcane sigil -> "spell".
-  // Leave "bypassType" unset only for a barrier with no such route (e.g. a purely
-  // social "convince the guard" puzzle) -- don't force one in just to use the
-  // mechanic, but don't invent a riddle-poem instead of a real barrier either.
-  //
-  // Either way, "requiredPhrase" is always a concrete, literal credential -- the
-  // code, the passphrase, the fingerprint owner's name, the words of the ward --
-  // never a wordplay answer to a puzzle. "riddle" states what the barrier wants
-  // without giving that credential away; the player finds it via a clue (below).
-  // When "bypassType" IS set, that same credential doubles as the safe route:
-  // "solve" with the right answer always works, while "pick"/"hack"/"cast" is
-  // the risky shortcut that skips finding it. That route is player-initiated
-  // and a genuine coin flip -- but failure is FATAL, ending the run outright
-  // (tripped alarm, security response, backlash -- whatever fits the barrier).
-  // Only give a puzzle "bypassType" when a real physical/technical/magical
-  // route past it makes sense; never attach it just to decorate a puzzle,
-  // since it's a real life-or-death choice the player is being offered.
-  //
-  // For EVERY puzzle above, the answer must be discoverable somewhere OTHER
-  // than the puzzle's own room (never the same room -- the player must go
-  // find it elsewhere). Either of these satisfies that, and the second is
-  // usually simpler to get exactly right:
-  //   (a) A companion clue item in "items": category "Book", "room" set to
-  //       a different room, whose "details" field directly states the
-  //       puzzle's exact "requiredPhrase" (a diary entry, scrawled note, or
-  //       manual that gives the answer away once someone reads it).
-  //   (b) The "requiredPhrase" IS a real item's exact "name" (any category),
-  //       placed with "room" set to a different room -- e.g. a riddle whose
-  //       answer is "obsidian keycard" and there's a real item literally
-  //       named "Obsidian Keycard" sitting elsewhere. Finding it and seeing
-  //       its name is the clue; no separate documentation needed.
-  //
-  // DOORS AS PUZZLES: a locked door can be secured by a real puzzle instead of
-  // (or as well as) a physical "keyRequired" item -- set "exits[].puzzle" to
-  // that puzzle's "name", and leave that puzzle's own "room" unset (it
-  // belongs to the door connecting two rooms, not either one). Everything
-  // above still applies exactly the same way -- it needs a "riddle"
-  // description, a discoverable clue elsewhere, and an optional matching
-  // "bypassType" -- the only difference is the payoff: solving or bypassing
-  // it unlocks the door rather than granting an item, so "rewardItem" should
-  // normally be omitted. Use this for a door that's more interesting than a
-  // "find the physical key" errand -- a keypad, a biometric scanner, a
-  // warded threshold -- and keep using plain "keyRequired" for a door that's
-  // just a mundane lock with a key sitting somewhere.
-  //
-  // FIXER CONVENTION: in Shadowrun, a fixer (whoever commissions a run) works
-  // over comms and essentially never meets a runner in person. If this scene's
-  // premise involves a job-giver/employer character (almost always true), name
-  // them EXACTLY "${FIXER_NAME}" -- in "npcs[].player.name", and in
-  // "winCondition.toNpc" too IF he's also the win condition's target (see
-  // BROKER, NOT ALWAYS THE DESTINATION below -- he often isn't). This is
-  // deliberate: in Shadowrun, "${FIXER_NAME}" is the in-universe slang for an
-  // anonymous corporate employer, not a real name -- every job's fixer goes by
-  // it regardless of who's actually behind the alias, and the runner never
-  // learns their real identity. Never invent a different name for this role.
-  // Give him his own room and mark that room "reachable": false -- an office,
-  // den, or safehouse the player will never set foot in. Give that room NO
-  // exits (or only exits to other "reachable": false rooms). "call" is the
-  // only way to reach him, and it requires a commlink on BOTH ends, equipped
-  // by the caller:
-  //   - Give the player a "Commlink"-category item in "startingItems" (or
-  //     placed somewhere findable in a reachable room).
-  //   - Give ${FIXER_NAME} his own "Commlink"-category item with "heldBy" set
-  //     to his name -- without one, he can never be reached at all.
-  //
-  // BROKER, NOT ALWAYS THE DESTINATION: ${FIXER_NAME}'s job is to commission
-  // the run and point the runner at what matters -- he does NOT have to be
-  // "winCondition.toNpc" himself. Often the more interesting choice is a
-  // DIFFERENT NPC entirely: someone ${FIXER_NAME} mentions in his own
-  // "dialogue" (a buyer, a target, a contact on the ground) who the runner
-  // then has to track down, meet, or call to actually finish the job. Both
-  // patterns are valid -- don't default to ${FIXER_NAME} as the
-  // winCondition.toNpc out of habit if the story is more interesting with
-  // someone else in that role. If you do introduce a separate contact this
-  // way, they need everything any other reachable NPC needs (a real
-  // startLocation; a commlink of their own if "call" is how the player is
-  // meant to reach them and their room is "reachable": false).
-  "player": {
-    "name": "Maka",
-    "startLocation": string, // must match the isStartRoom room's name
-    "lifestyleChoices": [{ "type": "residence", "metadata": { "tier": "Street", "location": string } }],
-    "startingItems": [ /* 3-5 items, same shape as above minus room/heldBy/owner */ ]
-  },
-  "winCondition": {
-    "type": "give",
-    "item": string, // must match an items[].name -- a MacGuffin the player must find and deliver
-    "toNpc": string, // must match an npcs[].player.name -- who wants it
-    "rewardItem"?: string, // optional bonus payoff item; must match an items[].name with no room/heldBy
-    "payout": number, // REQUIRED: the job's agreed pay in nuyen. The engine ACTUALLY transfers
-                       // this to the player on completion, and every NPC is told the exact
-                       // figure -- so this IS the number the fixer quotes. A round, streetwise
-                       // figure scaled to the job number: ~2000-6000 for job #1, roughly
-                       // half again more per job after that.
-    "completionMessage": string // shown to the player when they complete the job
-  }
-}
-
-Hard rules (a broken reference here will crash the game on load):
-- Every "exits[].targetRoom" MUST exactly match a "rooms[].name".
-- Every "npcs[].player.startLocation" MUST exactly match a "rooms[].name".
-- Every "items[].room" (if set) MUST exactly match a "rooms[].name".
-- Every "items[].heldBy" (if set) MUST exactly match an "npcs[].player.name".
-- Every puzzle in "puzzles[]" must be placed EXACTLY ONE way: either "puzzles[].room" matches a
-  "rooms[].name", OR exactly one "exits[].puzzle" matches its "name" (DOORS AS PUZZLES above) -- never
-  both, never neither.
-- Every "exits[].puzzle" (if set) MUST exactly match a "puzzles[].name".
-- "puzzles[].rewardItem" (if set) MUST exactly match an "items[].name", and that item must have neither "room" nor
-  "heldBy" set -- it doesn't exist anywhere in the world yet; solving the puzzle is what brings it into the
-  player's possession. If an NPC is guarding this reward, that's already implied by the puzzle needing to be
-  solved in their room -- do NOT ALSO make the reward item "heldBy" that NPC, which would mean two different,
-  disconnected copies of "the same" item end up existing (one granted by solving, one still sitting on the NPC).
-- "puzzles[].rewardItem" must NEVER be the same item as "winCondition.item" -- they need opposite placement
-  (one must have no room/heldBy, the other must have one), so no single item can satisfy both. If the story
-  wants the winCondition macguffin to feel puzzle-guarded, give the puzzle its OWN separate rewardItem instead
-  (a key, a note, access -- something that leads to the macguffin), and place "winCondition.item" itself
-  normally, with "room" or "heldBy" set.
-- Exactly one room must have "isStartRoom": true, and it must match "player.startLocation".
-- EVERY puzzle needs a discoverable clue in a room OTHER than that puzzle's "room" (for a
-  door-anchored puzzle, which has no "room" of its own, any room with the clue satisfies this) --
-  either pattern (a) or (b) above. A puzzle backed by neither, or a room-anchored one whose only
-  clue sits in its own room, is invalid -- the player must always have a discoverable way to find
-  the answer, and finding it must take some legwork.
-- "puzzles[].requiresPuzzle" (if set) MUST exactly match another "puzzles[].name" in this
-  same scene, must not reference itself, and chains must never cycle back on themselves
-  (A requires B requires A). A chain can be any length a puzzle count actually supports.
-- If a puzzle's riddle, clue, or the scene's "story" implies that doing something in one
-  place enables or unlocks something elsewhere (e.g. "cut the power to blind the cameras"),
-  that MUST be modeled as a real two-step (or longer) puzzle chain using "requiresPuzzle" --
-  never write a riddle or clue that implies a mechanic the JSON doesn't actually back up.
-  If there's only one puzzle in this scene, there's nothing to chain -- keep it self-
-  contained and don't reference another location or action that doesn't exist.
-- "winCondition.item" MUST exactly match an "items[].name", and that item MUST have either
-  "room" or "heldBy" set -- it needs a concrete, findable location in the world, exactly
-  like every other item. It must NOT be "heldBy" the "winCondition.toNpc" itself (the
-  player has to find it, not already have delivered it) -- place it in a room, or held by
-  a DIFFERENT NPC.
-- "winCondition.toNpc" MUST exactly match an "npcs[].player.name".
-- "winCondition.rewardItem" (if set) MUST exactly match an "items[].name" with neither
-  "room" nor "heldBy" set (same rule as a puzzle reward item).
-- This win-condition item is the CENTRAL plot object of the run's "story" -- something
-  stolen, owed, or lost that the winCondition.toNpc wants back or wants delivered.
-- "exits[].keyRequired" (if set) MUST exactly match an "items[].name", and that item MUST
-  have "room" or "heldBy" set to a concrete location -- never invent a key name that isn't
-  a real item. Never place that key's item in a room that is ONLY reachable by first going
-  through the very door it unlocks (that's an unsolvable soft-lock). The player must always
-  be able to reach the key through some path that doesn't require already being unlocked.
-- A room may be marked "reachable": false to represent somewhere the player can never
-  physically enter (a fixer's remote hideout, most commonly -- see the fixer convention
-  above). Such a room MUST have no exits, or exits ONLY to other "reachable": false rooms --
-  never an exit connecting it to a normally-reachable room, which would defeat the point.
-- Nothing the player must retrieve to finish the run -- a puzzle, a door's "keyRequired"
-  item, or the "winCondition.item" -- may be placed inside a "reachable": false room. The
-  player can never go get it.
-- If "winCondition.toNpc" is placed in a "reachable": false room, "call" (which requires a
-  commlink on both ends) is the only way to reach them, so BOTH of these must hold: the
-  player must have a way to get a "Commlink"-category item (in "startingItems", or findable
-  in a reachable room), AND "winCondition.toNpc" must itself hold a "Commlink"-category item
-  ("heldBy" set to their name) -- without one, they can never receive a call at all.
-
-Scope: ${scope}. Plus 4 to 6 general world items, one clue item per puzzle, the winCondition
-item and optional reward item, and the player's 3-5 starting items. Give it a gritty, noir
-Shadowrun tone: a fixer, a job, a locked door, a debt, a betrayal -- something in that vein.
-This is a fresh run, distinct from a generic "protect the lock" or "corp blackmail vault"
-premise.
-`.trim();
-}
+import { buildSkeletonPrompt, buildRoomsPrompt, buildNpcsPrompt, buildPuzzlesPrompt, buildItemsPrompt, parseJsonReply, validateSkeleton, normalizeSkeleton, assembleScene, classifyRepair, canBypassUnaided, } from './scene-chunks.js';
+// The fixer name convention and the player dossier live with the prompt
+// builders now (see scene-chunks.ts); re-exported so the existing
+// import sites (call.ts, game.ts) keep working unchanged.
+export { FIXER_NAME } from './scene-chunks.js';
 export class SceneSeedGenerator {
-    static maxAttempts = 3;
+    /** Fresh-skeleton pipeline attempts (structural faults promote to a new one). */
+    static maxPipelineAttempts = 2;
+    /** Per-pipeline chunk repairs before demanding a fresh skeleton. */
+    static maxRepairRounds = 3;
+    /** Attempts per individual AI call (skeleton or one detail chunk). */
+    static maxCallAttempts = 2;
+    // Per-call response budgets. Each is a fraction of a whole scene -- the
+    // point of chunking: no single completion carries everything, so scene
+    // scale is no longer bounded by the provider's output ceiling (a real
+    // session lost four of six whole-scene attempts to JSON truncated
+    // mid-string at the old fixed cap).
+    static SKELETON_TOKENS = 4000;
+    static ROOMS_TOKENS = 3000;
+    static NPCS_TOKENS = 6000;
+    static PUZZLES_TOKENS = 3000;
+    static ITEMS_TOKENS = 6000;
     /**
-     * `tier` is 1 for a first job, 2+ for each successive "continue" --
-     * scales both the scope guidance in the prompt and, indirectly, the
-     * story's stakes. `previousFixerName`, when given, tells the model to
-     * keep using the same job-giver identity rather than inventing a new one
-     * every time "continue" is used.
+     * CHUNKED generation (see scene-chunks.ts for the shapes and prompts):
+     * one compact SKELETON pass fixes the scene's whole structure -- every
+     * cross-reference the validators check -- then small detail passes flesh
+     * out rooms, NPCs, puzzles, and items (items last: clue items bake in
+     * the puzzle passphrases). The assembled scene runs through the same
+     * validators as ever; a failure regenerates only the chunk responsible
+     * (classifyRepair) instead of throwing the whole scene away.
+     *
+     * `tier` scales scope and stakes; `previousFixerName` keeps the same
+     * job-giver identity across "continue"; `player` becomes the dossier
+     * that tailors the job to the runner's archetype and toolkit.
      */
-    static async generate(logFilePath, tier = 1, previousFixerName) {
+    static async generate(logFilePath, tier = 1, previousFixerName, player) {
         if (!AI.isConfigured())
             return null;
         const logger = Logger.getInstance(logFilePath, { children: [], render: () => { } });
+        const playerName = player?.name ?? 'Maka';
+        // Two budgets, deliberately separate: PIPELINE attempts (a fresh
+        // skeleton + full chunk set -- structural faults land here) and, per
+        // pipeline, chunk REPAIR rounds. A real generation burned its whole
+        // repair budget on two skeleton restarts and died with one round left
+        // for an items fault; skeleton restarts no longer eat repair rounds.
+        let carriedError;
+        for (let pipeline = 1; pipeline <= this.maxPipelineAttempts; pipeline++) {
+            try {
+                const skeleton = await this.requestSkeleton(tier, previousFixerName, player, logger, carriedError);
+                const details = await this.requestAllDetails(skeleton, logger);
+                let structuralFault;
+                for (let round = 0; round <= this.maxRepairRounds; round++) {
+                    const candidate = assembleScene(skeleton, details, playerName);
+                    try {
+                        await this.dryRunValidate(candidate, player);
+                        logger.write(`SceneSeedGenerator: assembled valid scene "${candidate.name}" (pipeline ${pipeline}, ${round} repair round(s))`);
+                        this.saveSeedToDisk(candidate, logFilePath, tier, skeleton);
+                        return candidate;
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        const target = classifyRepair(message);
+                        if (target === 'skeleton' || round === this.maxRepairRounds) {
+                            structuralFault = message;
+                            logger.write(`SceneSeedGenerator: pipeline ${pipeline} needs a fresh skeleton (${target === 'skeleton' ? 'structural fault' : 'repair budget exhausted'}): ${message}`);
+                            break;
+                        }
+                        logger.write(`SceneSeedGenerator: validation failed -> repairing ${target}: ${message}`);
+                        if (target === 'rooms') {
+                            details.rooms = await this.requestChunk('rooms', buildRoomsPrompt(skeleton, message), this.ROOMS_TOKENS, logger);
+                        }
+                        else if (target === 'npcs') {
+                            details.npcs = await this.requestChunk('npcs', buildNpcsPrompt(skeleton, message), this.NPCS_TOKENS, logger);
+                        }
+                        else if (target === 'puzzles') {
+                            details.puzzles = await this.requestChunk('puzzles', buildPuzzlesPrompt(skeleton, message), this.PUZZLES_TOKENS, logger);
+                            // New passphrases invalidate the baked-in clue text.
+                            details.items = await this.requestChunk('items', buildItemsPrompt(skeleton, details.puzzles), this.ITEMS_TOKENS, logger);
+                        }
+                        else {
+                            details.items = await this.requestChunk('items', buildItemsPrompt(skeleton, details.puzzles, message), this.ITEMS_TOKENS, logger);
+                        }
+                    }
+                }
+                carriedError = structuralFault;
+            }
+            catch (err) {
+                carriedError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: pipeline ${pipeline} failed: ${carriedError}`);
+            }
+        }
+        logger.write(`SceneSeedGenerator: giving up (${carriedError ?? 'unknown'}) -- falling back to a static scene`);
+        return null;
+    }
+    /** The skeleton pass: structure only, fast-validated before any detail pass builds on it. */
+    static async requestSkeleton(tier, previousFixerName, player, logger, previousError) {
+        let lastError = previousError;
+        for (let attempt = 1; attempt <= this.maxCallAttempts; attempt++) {
+            const reply = await AI.ask(buildSkeletonPrompt(tier, previousFixerName, player, lastError), { maxTokens: this.SKELETON_TOKENS });
+            try {
+                const skeleton = parseJsonReply(reply);
+                skeleton.puzzles = skeleton.puzzles ?? [];
+                for (const note of normalizeSkeleton(skeleton)) {
+                    logger.write(`SceneSeedGenerator: ${note}`);
+                }
+                validateSkeleton(skeleton, player);
+                logger.write(`SceneSeedGenerator: skeleton "${skeleton.name}" -- ${skeleton.rooms.length} rooms, ${skeleton.npcs.length} npcs, ${skeleton.puzzles.length} puzzles, ${skeleton.items.length} items`);
+                return skeleton;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                logger.write(`SceneSeedGenerator: skeleton attempt ${attempt} failed: ${lastError}`);
+                if (attempt === this.maxCallAttempts)
+                    throw err;
+            }
+        }
+        throw new Error('unreachable');
+    }
+    /** One detail chunk: prompt -> JSON, with one retry feeding the parse error back. */
+    static async requestChunk(label, prompt, maxTokens, logger) {
         let lastError;
-        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+        for (let attempt = 1; attempt <= this.maxCallAttempts; attempt++) {
+            const fullPrompt = lastError
+                ? `${prompt}\n\nYour previous attempt failed with this error -- fix it and try again: ${lastError}`
+                : prompt;
+            const reply = await AI.ask(fullPrompt, { maxTokens });
             try {
-                logger.write(`SceneSeedGenerator: tier ${tier} attempt ${attempt} of ${this.maxAttempts}`);
-                const candidate = await this.requestCandidate(tier, previousFixerName, lastError);
-                await this.dryRunValidate(candidate);
-                logger.write(`SceneSeedGenerator: generated a valid scene "${candidate.name}" on attempt ${attempt}`);
-                this.saveSeedToDisk(candidate, logFilePath, tier);
-                return candidate;
+                const parsed = parseJsonReply(reply);
+                logger.write(`SceneSeedGenerator: chunk "${label}" ok (attempt ${attempt})`);
+                return parsed;
             }
             catch (err) {
                 lastError = err instanceof Error ? err.message : String(err);
-                logger.write(`SceneSeedGenerator: attempt ${attempt} failed: ${lastError}`);
+                logger.write(`SceneSeedGenerator: chunk "${label}" attempt ${attempt} failed: ${lastError}`);
+                if (attempt === this.maxCallAttempts)
+                    throw err;
             }
         }
-        logger.write(`SceneSeedGenerator: giving up after ${this.maxAttempts} attempts, falling back to a static scene`);
-        return null;
+        throw new Error('unreachable');
+    }
+    /**
+     * Rooms, NPCs, and puzzles are independent given the skeleton -- they
+     * run in parallel. Items runs after puzzles: each clue item's "details"
+     * must contain its puzzle's exact passphrase.
+     */
+    static async requestAllDetails(skeleton, logger) {
+        const [rooms, npcs, puzzles] = await Promise.all([
+            this.requestChunk('rooms', buildRoomsPrompt(skeleton), this.ROOMS_TOKENS, logger),
+            this.requestChunk('npcs', buildNpcsPrompt(skeleton), this.NPCS_TOKENS, logger),
+            skeleton.puzzles.length > 0
+                ? this.requestChunk('puzzles', buildPuzzlesPrompt(skeleton), this.PUZZLES_TOKENS, logger)
+                : Promise.resolve([]),
+        ]);
+        const items = await this.requestChunk('items', buildItemsPrompt(skeleton, puzzles), this.ITEMS_TOKENS, logger);
+        return { rooms, npcs, puzzles, items };
     }
     /**
      * Saves a validated scene alongside that session's game log (same
@@ -423,29 +167,25 @@ export class SceneSeedGenerator {
      * -- AI-generated scenes previously only existed in memory for the
      * process that generated them.
      */
-    static saveSeedToDisk(candidate, logFilePath, tier) {
+    static saveSeedToDisk(candidate, logFilePath, tier, skeleton) {
         const logger = Logger.getInstance();
         const sessionDir = path.dirname(logFilePath);
         const seedPath = path.join(sessionDir, `scene-job-${tier}.json`);
         try {
             fs.mkdirSync(sessionDir, { recursive: true });
             fs.writeFileSync(seedPath, JSON.stringify(candidate, null, 2));
+            // The skeleton rides along for post-mortems: it shows what the
+            // structure pass planned, separate from what the detail passes made
+            // of it.
+            if (skeleton) {
+                fs.writeFileSync(path.join(sessionDir, `scene-job-${tier}-skeleton.json`), JSON.stringify(skeleton, null, 2));
+            }
             logger.write(`SceneSeedGenerator: saved generated scene to ${seedPath}`);
         }
         catch (err) {
             logger.error(`SceneSeedGenerator: failed to save generated scene to ${seedPath}: ${err}`);
         }
     }
-    static async requestCandidate(tier, previousFixerName, previousError) {
-        const schemaGuide = buildSchemaGuide(tier, previousFixerName);
-        const prompt = previousError
-            ? `${schemaGuide}\n\nYour previous attempt failed with this error -- fix it and try again: ${previousError}`
-            : schemaGuide;
-        let reply = await AI.ask(prompt);
-        // Models sometimes wrap their response in a markdown code fence despite instructions not to.
-        reply = reply.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
-        return JSON.parse(reply);
-    }
     /**
      * Runs the candidate through the exact same synthesis pipeline a real
      * session would use, purely to surface referential-integrity errors
@@ -453,7 +193,7 @@ export class SceneSeedGenerator {
      * resulting Scene either way -- the real session re-synthesizes fresh
      * (with AI flavor enabled) once this seed is handed off.
      */
-    static async dryRunValidate(candidate) {
+    static async dryRunValidate(candidate, player) {
         // Must run BEFORE synthesis: a room/npc/item with a missing or blank
         // "name" doesn't fail synthesis with a useful error -- it crashes deep
         // inside it with a raw JS TypeError ("Cannot read properties of
@@ -468,8 +208,11 @@ export class SceneSeedGenerator {
         // throws on those. This only checks the one semantic rule synthesis
         // can't: the item must actually be findable, not already delivered.
         await SceneSynthesizer.synthesizeFromJson(candidate, throwawayPlayer, false);
-        this.validateClueItems(candidate);
-        this.validateWinCondition(candidate);
+        this.validateClueItems(candidate, player);
+        this.validateWinCondition(candidate, player);
+        this.validateMatrixDefense(candidate);
+        this.validateStartingItems(candidate, player);
+        this.validateBypassTypes(candidate);
         this.validatePuzzleChain(candidate);
         this.validateDoorKeys(candidate);
         this.validateRewardItemPlacement(candidate);
@@ -618,28 +361,36 @@ export class SceneSeedGenerator {
         const reachable = new Set();
         if (!startRoom || !rooms.some(r => r.name === startRoom))
             return reachable;
+        // Edges are BIDIRECTIONAL: the engine mirrors every declared exit
+        // into a shared two-way Door (Room.addExit writes both sides), so a
+        // one-sided declaration -- the chunked skeleton's house style --
+        // still connects both rooms in play. The old directed-only walk
+        // falsely stranded rooms reachable via the mirrored direction.
+        const edges = [];
+        for (const room of rooms) {
+            for (const exit of room.exits ?? []) {
+                edges.push({ a: room.name, b: exit.targetRoom, keyRequired: exit.keyRequired, puzzle: exit.puzzle });
+            }
+        }
         reachable.add(startRoom);
         let grew = true;
         while (grew) {
             grew = false;
-            for (const room of rooms) {
-                if (!reachable.has(room.name))
+            for (const edge of edges) {
+                const from = reachable.has(edge.a) ? edge.a : reachable.has(edge.b) ? edge.b : undefined;
+                const to = from === edge.a ? edge.b : edge.a;
+                if (!from || reachable.has(to))
                     continue;
-                for (const exit of room.exits ?? []) {
-                    if (reachable.has(exit.targetRoom))
-                        continue;
-                    const keyLocation = exit.keyRequired ? itemLocation.get(exit.keyRequired) : undefined;
-                    // A puzzle-guarded exit (see DOORS AS PUZZLES) is always treated
-                    // as eventually passable: validateClueItems already guarantees
-                    // every puzzle's answer is discoverable somewhere, and even
-                    // without it, pick/hack/cast is a real (if risky) route through.
-                    // Only a plain "keyRequired" door needs its key traced to a
-                    // reachable location first.
-                    const passable = !!exit.puzzle || !exit.keyRequired || (keyLocation !== undefined && reachable.has(keyLocation));
-                    if (passable) {
-                        reachable.add(exit.targetRoom);
-                        grew = true;
-                    }
+                const keyLocation = edge.keyRequired ? itemLocation.get(edge.keyRequired) : undefined;
+                // A puzzle-guarded exit (see DOORS AS PUZZLES) is always treated
+                // as eventually passable: the clue/competence rules guarantee a
+                // route, and pick/hack/cast/bluff is a real (if risky) shortcut.
+                // Only a plain "keyRequired" door needs its key traced to a
+                // reachable location first.
+                const passable = !!edge.puzzle || !edge.keyRequired || (keyLocation !== undefined && reachable.has(keyLocation));
+                if (passable) {
+                    reachable.add(to);
+                    grew = true;
                 }
             }
         }
@@ -734,7 +485,7 @@ export class SceneSeedGenerator {
      * NPC's own inventory, which would make the "find and deliver it"
      * premise nonsensical.
      */
-    static validateWinCondition(candidate) {
+    static validateWinCondition(candidate, player) {
         const wc = candidate.winCondition;
         if (!wc) {
             throw new Error('Scene has no "winCondition". Every generated run needs one.');
@@ -768,7 +519,12 @@ export class SceneSeedGenerator {
             const toNpcRoom = rooms.find(r => r.name === toNpcData?.player.startLocation);
             if (toNpcRoom?.reachable === false) {
                 const reachable = this.computeReachableRooms(candidate);
-                const playerHasCommlink = (candidate.player?.startingItems ?? []).some(i => i.category === 'Commlink') ||
+                // Continuation drafts author no startingItems -- the dossier
+                // player's OWN kit (carried or equipped commlink) counts.
+                const ownsCommlink = !!player && (player.inventory.getAllItems().some(i => String(i.category).toLowerCase() === 'commlink') ||
+                    player.equipment.head?.commlink != null);
+                const playerHasCommlink = ownsCommlink ||
+                    (candidate.player?.startingItems ?? []).some(i => i.category === 'Commlink') ||
                     (candidate.items ?? []).some(i => i.category === 'Commlink' && i.room && reachable.has(i.room));
                 if (!playerHasCommlink) {
                     throw new Error(`Win condition target "${wc.toNpc}" is in a "reachable: false" room ("${toNpcRoom.name}"), so the player can only contact them via "call" -- but no Commlink-category item is available (not in "player.startingItems", and none findable in a reachable room). Give the player a way to get a commlink.`);
@@ -780,6 +536,77 @@ export class SceneSeedGenerator {
             }
         }
     }
+    /**
+     * bypassType is a closed enum the engine indexes into (puzzle.ts
+     * BYPASS_FLAVOR) -- an unvalidated value used to reach a live session
+     * and crash every "search" in that puzzle's room (the model emitted
+     * "con" for a social barrier before that type existed). The lookups are
+     * defensive now, but a bad value would still mean a barrier whose
+     * bypass route silently doesn't exist -- reject it with the exact
+     * allowed list instead.
+     */
+    static validateBypassTypes(candidate) {
+        const allowed = new Set(['lockpick', 'hack', 'spell', 'con']);
+        for (const puzzle of candidate.puzzles ?? []) {
+            if (puzzle.bypassType && !allowed.has(puzzle.bypassType)) {
+                throw new Error(`Puzzle "${puzzle.name}" has bypassType "${puzzle.bypassType}", which isn't valid -- use exactly one of "lockpick", "hack", "spell", "con" (lowercase), or omit the field for a barrier with no bypass route.`);
+            }
+        }
+    }
+    /**
+     * Mechanical teeth behind the dossier's "never duplicate their gear"
+     * rule: the prompt guidance alone was violated on its very first outing
+     * (an Adept's startingItems included "Weapon Focus Katana" verbatim, and
+     * the player watched the duplicate bounce off their occupied weapon
+     * slot). Rejects any startingItem whose name matches something the
+     * dossier player already carries or wears.
+     */
+    static validateStartingItems(candidate, player) {
+        if (!player)
+            return;
+        const owned = new Set(player.inventory.getAllItems().map(i => i.name.toLowerCase()));
+        for (const group of Object.values(player.equipment)) {
+            if (!group)
+                continue;
+            for (const item of Object.values(group)) {
+                if (item)
+                    owned.add(item.name.toLowerCase());
+            }
+        }
+        for (const starting of candidate.player?.startingItems ?? []) {
+            if (starting?.name && owned.has(starting.name.toLowerCase())) {
+                throw new Error(`"player.startingItems" includes "${starting.name}", which the runner ALREADY OWNS (see THE RUNNER dossier) -- remove it. Substitute a complementary basic they don't have (ammunition, a medkit, a tool), or simply grant fewer items.`);
+            }
+        }
+    }
+    /**
+     * A matrix-plane win-condition item must sit in a hasNode room with an
+     * ice NPC guarding it -- otherwise the whole run is a free walk: jack
+     * in, ride the grid (physical locks don't gate personas), take the
+     * file, done. Found via a real session that completed exactly that way
+     * with zero resistance. Hand-in-hand with the host-vault mechanic
+     * (matrix items stay sealed until the host is cracked -- see hack.ts /
+     * take.ts), this guarantees a datarun always has teeth.
+     */
+    static validateMatrixDefense(candidate) {
+        const wc = candidate.winCondition;
+        if (!wc)
+            return;
+        const item = (candidate.items ?? []).find(i => i.name === wc.item);
+        if (!item || item.plane !== 'matrix')
+            return;
+        if (!item.room) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" must be placed in a room (a hasNode room), not heldBy an NPC -- data lives on a host.`);
+        }
+        const room = (candidate.rooms ?? []).find(r => r.name === item.room);
+        if (!room?.hasNode) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" is in room "${item.room}", which has no "hasNode": true -- matrix files can only exist on a host. Mark that room hasNode.`);
+        }
+        const iceGuard = (candidate.npcs ?? []).some(n => n.plane === 'matrix' && n.player.startLocation === item.room);
+        if (!iceGuard) {
+            throw new Error(`Matrix-plane win condition item "${wc.item}" sits in hasNode room "${item.room}" with NO ice guarding it -- add an npc with "plane": "matrix", "startLocation": "${item.room}", and a combat block (logic 4-7). An undefended data vault makes the run a free win.`);
+        }
+    }
     /**
      * Enforces the "always some way to find the solution" guarantee: every
      * puzzle must have a discoverable clue, placed in a different room. None
@@ -794,7 +621,7 @@ export class SceneSeedGenerator {
      * documentation -- finding it and seeing its name on screen already
      * reveals the answer. A Book clue is still required for anything else.
      */
-    static validateClueItems(candidate) {
+    static validateClueItems(candidate, player) {
         const items = candidate.items ?? [];
         for (const puzzle of candidate.puzzles ?? []) {
             const requiredPhrase = (puzzle.requiredPhrase ?? '').toLowerCase();
@@ -807,8 +634,12 @@ export class SceneSeedGenerator {
             const hasNamedItemClue = requiredPhrase.length > 0 && items.some(item => item.room &&
                 item.room !== puzzle.room &&
                 item.name.toLowerCase() === requiredPhrase);
-            if (!hasBookClue && !hasNamedItemClue) {
-                throw new Error(`Puzzle "${puzzle.name}" has no discoverable clue: no Book-category item in a different room whose "details" contains the answer "${puzzle.requiredPhrase}", and no item elsewhere literally named "${puzzle.requiredPhrase}". Every puzzle needs one or the other.`);
+            // Loosened against the dossier: a barrier whose bypassType matches
+            // the runner's own trained means (a lockpick door for a master
+            // locksmith) doesn't strictly need its credential written down --
+            // the skill IS the way past. Strict rule stays without a dossier.
+            if (!hasBookClue && !hasNamedItemClue && !canBypassUnaided(player, puzzle.bypassType)) {
+                throw new Error(`Puzzle "${puzzle.name}" has no discoverable clue: no Book-category item in a different room whose "details" contains the answer "${puzzle.requiredPhrase}", no item elsewhere literally named "${puzzle.requiredPhrase}", and its bypassType (${puzzle.bypassType ?? 'none'}) is not a means this runner reliably has. Every puzzle needs one of the three.`);
             }
         }
     }