@maka/maka-cli 5.4.0 → 5.5.0

package/bundle/typescript/src/commands/game/sideQuest/game.js

@@ -33,6 +33,7 @@ import { EdgeCommand } from './commands/edge.js';
 import { SheetCommand } from './commands/sheet.js';
 import { CallCommand } from './commands/call.js';
 import { EndCallCommand } from './commands/end-call.js';
+import { fuzzyPickName, levenshteinDistance } from './utilities/fuzzy-match.js';
 import { PickCommand } from './commands/pick.js';
 import { HackCommand } from './commands/hack.js';
 import { CastCommand } from './commands/cast.js';
@@ -44,6 +45,14 @@ import { AssenseCommand } from './commands/assense.js';
 import { DroneCommand } from './commands/drone.js';
 import { PanCommand } from './commands/pan.js';
 import { RebootCommand } from './commands/reboot.js';
+import { BrandishCommand, HolsterCommand } from './commands/brandish.js';
+import { AdvanceCommand } from './commands/advance.js';
+import { equipIntoEmptySlots } from './archetypes.js';
+import { NPC } from './models/npc.js';
+import { HaggleCommand } from './commands/haggle.js';
+import { SneakCommand } from './commands/sneak.js';
+import { PersuadeCommand } from './commands/persuade.js';
+import { BluffCommand } from './commands/bluff.js';
 import { AutoFight } from './utilities/auto-fight.js';
 import { CommandFactory } from './factories/command-factory.js';
 import { SceneSynthesizer } from './factories/scene-factory.js';
@@ -78,6 +87,91 @@ export default class Game {
     // player-location state out from under whatever the player was already
     // doing in it.
     _draftInProgress = false;
+    // The HUB scene, when this session started in one (a seed with
+    // "hub": true -- the persistent home base, e.g. Tacoma Purple Haze).
+    // Kept as the live Scene INSTANCE, same pattern as _homeRoom, so
+    // everything in it -- NPC state, shop stock, dropped loot -- persists
+    // untouched while runs play out, and returnToHub() just re-points the
+    // world at it. undefined for classic sessions (test scene, launch-
+    // generated runs), which keep the old continue->draft loop.
+    _hubScene;
+    _hubName = 'home';
+    get hasHub() {
+        return this._hubScene !== undefined;
+    }
+    /** The persistent hideout room -- go.ts's walk-home trigger checks it. */
+    get homeRoom() {
+        return this._homeRoom;
+    }
+    // A drafted run waiting for the player to take it (hub sessions only):
+    // generation finishing sends a MESSAGE instead of teleporting anyone --
+    // "call Mr. Johnson" hears the offer, "travel" goes.
+    _pendingRunSeed;
+    _pendingRunTier;
+    get pendingRun() {
+        return this._pendingRunSeed;
+    }
+    get pendingRunTier() {
+        return this._pendingRunTier;
+    }
+    /**
+     * The cab that answers "call taxi" varies per job (player request: not
+     * always a van) -- picked once when the pending run lands, so the
+     * arrival and the ride read as ONE vehicle.
+     */
+    static RIDE_POOL = [
+        {
+            arrive: `A matte-black step-van splashes to the curb in front of you, side door already sliding open.`,
+            board: `The door rattles shut and the Haze smears past the grimy windows.`,
+        },
+        {
+            arrive: `A pearl-gray Westwind glides up out of the rain, gullwing lifting -- somebody's billing this to the client.`,
+            board: `The gullwing sighs closed and the launch pins you into leather that costs more than your rent.`,
+        },
+        {
+            arrive: `A patchwork gypsy cab rattles around the corner and stops dead in front of you, meter torn out, driver watching the mirrors.`,
+            board: `The cabbie pulls off before the door's even latched, humming something older than the district.`,
+        },
+        {
+            arrive: `A rust-eaten GMC Bulldog bulls through traffic and mounts the curb beside you, panel doors ajar.`,
+            board: `The Bulldog coughs, catches, and shoves into traffic like it's owed something.`,
+        },
+        {
+            arrive: `An unmarked ambulance rolls up silent, lights dead, back doors swinging open -- nobody looks twice at it.`,
+            board: `You ride out flat on the gurney, ceiling lights strobing past the little windows.`,
+        },
+        {
+            arrive: `A growling Harley with a reinforced sidecar pulls a U-turn and stops at your boots, rider jerking a thumb at the car.`,
+            board: `You drop into the sidecar; the pipes drown the whole district out.`,
+        },
+    ];
+    _pendingRide;
+    /** The pending job's cab flavor -- "call taxi" narrates with it (see call.ts). */
+    get pendingRide() {
+        return this._pendingRide;
+    }
+    /**
+     * Generates NPC first-impression appearances ("look at <npc>") in the
+     * background, one at a time -- the only AI dressing still worth doing
+     * now that every scene arrives with real prose. Fire-and-forget: until
+     * an appearance lands, look-at just shows a bit less flavor.
+     */
+    warmNpcAppearancesInBackground() {
+        if (!this._useAi)
+            return;
+        const npcs = this.scene.allActors.filter((a) => a instanceof NPC);
+        const context = `${this.sceneSeed?.name ?? ''} -- ${this.scene.story}`;
+        void (async () => {
+            for (const npc of npcs) {
+                try {
+                    await npc.ensureAIAppearance(context);
+                }
+                catch {
+                    // Non-fatal: the next look-at simply has less flavor.
+                }
+            }
+        })();
+    }
     // A single fixed room, created once and never torn down across job
     // transitions -- the player's own place, unlike every job's generated
     // rooms which get discarded wholesale when the next job replaces them.
@@ -138,6 +232,22 @@ export default class Game {
         CommandFactory.registerCommand('drone', DroneCommand);
         CommandFactory.registerCommand('pan', PanCommand);
         CommandFactory.registerCommand('reboot', RebootCommand);
+        CommandFactory.registerCommand('brandish', BrandishCommand);
+        CommandFactory.registerCommand('draw', BrandishCommand);
+        CommandFactory.registerCommand('holster', HolsterCommand);
+        CommandFactory.registerCommand('stow', HolsterCommand);
+        // "end" and "hangup" both bounced in real sessions when players
+        // wanted to end a call -- the intent is unambiguous mid-call.
+        CommandFactory.registerCommand('end', EndCallCommand);
+        CommandFactory.registerCommand('hangup', EndCallCommand);
+        CommandFactory.registerCommand('advance', AdvanceCommand);
+        CommandFactory.registerCommand('train', AdvanceCommand);
+        CommandFactory.registerCommand('haggle', HaggleCommand);
+        CommandFactory.registerCommand('negotiate', HaggleCommand);
+        CommandFactory.registerCommand('sneak', SneakCommand);
+        CommandFactory.registerCommand('persuade', PersuadeCommand);
+        CommandFactory.registerCommand('convince', PersuadeCommand);
+        CommandFactory.registerCommand('bluff', BluffCommand);
     }
     determineStartRoom() {
         return this.scene.determineStartRoom();
@@ -180,32 +290,19 @@ export default class Game {
         this.initInputBox(screen);
         this.initLogBox(screen);
         this.initStatusBox(screen);
-        // Create a loading box
-        const loadingBox = blessed.box({
-            parent: screen,
-            top: 'center',
-            left: 'center',
-            width: '50%',
-            height: 'shrink',
-            content: 'Generating Scene... Please wait.',
-            border: { type: 'line' },
-            style: {
-                fg: 'white',
-                bg: 'black',
-                border: { fg: 'cyan' },
-            }
-        });
-        screen.append(loadingBox);
-        screen.render();
+        // No "Generating Scene... Please wait." box anymore: every path now
+        // arrives with REAL prose (hand-authored static seeds, chunk-authored
+        // generated scenes), so the old blocking AI-redressing pass -- 30-60
+        // seconds rewriting text that was already good -- is skipped and the
+        // game opens instantly. The one thing still worth generating (NPC
+        // first-impression appearances for "look at") warms in the background
+        // below.
         try {
-            this.scene = await SceneSynthesizer.synthesizeFromJson(this.sceneSeed, this.player, options.useAi);
+            this.scene = await SceneSynthesizer.synthesizeFromJson(this.sceneSeed, this.player, false);
         }
         catch (err) {
             throw new Error(`Scene generation failed: ${err.message}`);
         }
-        // Remove loading box
-        screen.remove(loadingBox);
-        screen.render();
         this.scene.initialize(this);
         this.player.currentLocation = this.determineStartRoom();
         this.registerCommands();
@@ -217,6 +314,24 @@ export default class Game {
         });
         this.scene.addRoom(this._homeRoom);
         this.connectHomeRoom(this.player.currentLocation);
+        // Every session starts AT HOME -- the hideout, one door from the job's
+        // start room (player request, left as an in-game note: "I'd like to
+        // always start in my hideout"). The scene's isStartRoom still anchors
+        // where the hideout's door leads; the runner just wakes up on their
+        // own cot instead of already standing in the job.
+        this.player.currentLocation = this._homeRoom;
+        // Starting in a hub makes this a hub SESSION: runs are commissioned
+        // by calling the fixer from here, and completing one returns here.
+        if (this.scene.isHub) {
+            this._hubScene = this.scene;
+            this._hubName = this.sceneSeed?.name ?? 'home';
+        }
+        // Gear up automatically: wearables (and the commlink) slot into any
+        // EMPTY slots at load -- no "equip all" ritual to start a session
+        // (player request). Occupied slots (archetype signature gear) are
+        // never swapped out.
+        equipIntoEmptySlots(this.player);
+        this.warmNpcAppearancesInBackground();
         this.initialized = true;
         // Nudge the player toward "call" up front -- the fixer convention means
         // the story deliberately doesn't narrate a completed briefing, so
@@ -235,9 +350,14 @@ export default class Game {
      */
     canDraftNextScene() {
         if (this._draftInProgress) {
-            return { allowed: false, message: `Already drafting the next job -- give it a moment, he'll call back.` };
+            return { allowed: false, message: `Still lining it up -- I'll ping you.` };
         }
-        if (!this.scene.isCompleted()) {
+        if (this._pendingRunSeed) {
+            return { allowed: false, message: `You've got my message already. Call a taxi when you're ready to roll.` };
+        }
+        // A hub is ALWAYS ready to commission the next run -- it has no win
+        // condition to complete; that's the whole point of home.
+        if (!this.scene.isHub && !this.scene.isCompleted()) {
             return { allowed: false, message: `This job isn't finished yet.` };
         }
         if (!this._useAi) {
@@ -274,6 +394,13 @@ export default class Game {
      * instant feedback, but this stays safe to call directly too).
      */
     async continueToNextScene() {
+        // Hub sessions: a finished RUN doesn't chain into the next draft --
+        // "continue" takes you home instead, and the next run is commissioned
+        // from there (call the fixer). Classic sessions skip this and keep
+        // the old continue->draft loop.
+        if (this._hubScene && this.scene !== this._hubScene && this.scene.isCompleted()) {
+            return this.returnToHub();
+        }
         const gate = this.canDraftNextScene();
         if (!gate.allowed) {
             return gate.message ?? `This job isn't finished yet.`;
@@ -286,6 +413,44 @@ export default class Game {
             this._draftInProgress = false;
         }
     }
+    /**
+     * Re-points the world at the preserved hub scene after a run: the hub's
+     * whole state (NPCs, shop stock, anything dropped there) survived
+     * untouched because the INSTANCE survived. The player walks back in
+     * through their own hideout, firmly in the meat -- any lingering run
+     * state (a persona still jacked in, an astral projection, a sneak,
+     * open combat bookkeeping) is settled on the way home.
+     */
+    returnToHub() {
+        const hub = this._hubScene;
+        if (!hub)
+            return `There's no home to go back to.`;
+        // Settle cross-plane and combat state that must not leak into the hub
+        // (the run's rooms -- including a bodyRoom the player left behind --
+        // are about to be orphaned wholesale).
+        this.player.plane = 'meat';
+        this.player.bodyRoom = undefined;
+        this.player.simMode = undefined;
+        this.player.astralTicks = 0;
+        this.player.activeDeck = undefined;
+        this.player.astralPerceiving = false;
+        this.player.sneaking = false;
+        this.player.inExchange = false;
+        this.player.combatOpponent = undefined;
+        this.player.activeCallPartner = undefined;
+        this.autoFight.cancelPending();
+        this.scene = hub;
+        this.scene.addRoom(this._homeRoom);
+        this.connectHomeRoom(hub.determineStartRoom());
+        this.player.currentLocation = this._homeRoom;
+        this.player.cameFrom = undefined;
+        this.updateEquipment(this.player.equipment);
+        this.updateInventory(this.player.inventory, capitalCase(this.scene.getCurrencyType()));
+        this.updateExits(this.player.currentLocation);
+        this.updateStatus();
+        Logger.getInstance().write(`Returned to hub "${this._hubName}".`);
+        return `\n=== ${this._hubName.toUpperCase()} ===\nThe run's wrapped and the street swallows you back up. You're home -- your hideout, one door off ${hub.determineStartRoom().name}. Call ${FIXER_NAME} when you're hungry for the next job.`;
+    }
     /**
      * The actual drafting work, split out from continueToNextScene() purely
      * so that method can wrap it in the try/finally that clears
@@ -309,40 +474,99 @@ export default class Game {
         // seconds for a tiered scene with AI flavor enabled. Framed as the
         // fixer's own line when he's actually in this scene, rather than a
         // bare system message -- he's the one drumming up the next gig.
-        const waitingLine = fixerStillInScene
-            ? `\n${CALL_ICON} ${FIXER_NAME}: "I'll call you back when I've got something lined up." (drafting the next job...)`
-            : '\nDrafting the next job... please wait.';
-        this.logBox.pushLine(waitingLine);
-        this.logBox.scrollTo(this.logBox.getScrollHeight());
-        this._screen.render();
-        const nextSeed = await SceneSeedGenerator.generate(this._logFilePath, nextTier, previousFixerName);
+        // No system "drafting..." line -- the fixer's own one-ring commission
+        // (call.ts) already told the player he'll call back; anything more
+        // reads as machinery (real playtest note). The wait resolves as HIS
+        // callback either way, success or failure.
+        //
+        // The player object rides along so the job is drafted FOR this runner
+        // -- their archetype, stats, and toolkit (see buildPlayerDossier).
+        const nextSeed = await SceneSeedGenerator.generate(this._logFilePath, nextTier, previousFixerName, this.player);
         if (!nextSeed) {
-            return `Couldn't draft a new job this time. Type "continue" to try again, or "quit" to stop here.`;
+            return `Incoming call -- ${FIXER_NAME}: "Job fell through, chummer. Client got cold feet before the ink dried. Give me another call in a bit -- I'll shake something loose."`;
         }
-        this._tier = nextTier;
-        this.sceneSeed = nextSeed;
+        // HUB sessions: the draft lands as a MESSAGE, never a teleport (real
+        // playtest note: being yanked into the run the instant generation
+        // finished was jarring). The player invokes it on their own time:
+        // "call Mr. Johnson" delivers the offer (haggle window included --
+        // see call.ts), and "travel" actually goes (launchPendingRun).
+        if (this.hasHub) {
+            this._pendingRunSeed = nextSeed;
+            this._pendingRunTier = nextTier;
+            this._pendingRide = Game.RIDE_POOL[Math.floor(Math.random() * Game.RIDE_POOL.length)];
+            return `Your link pings -- 1 new message: ${FIXER_NAME}. ("call ${FIXER_NAME}" to hear the job.)`;
+        }
+        // Classic sessions transition immediately, hideout-first, as always.
+        return await this.activateRunScene(nextSeed, nextTier, { startInHideout: true });
+    }
+    /**
+     * Installs a drafted run as the live scene. Shared by the classic
+     * immediate path (hideout start) and the hub's "travel" (start-room
+     * start -- you rode there, you arrive AT the job).
+     */
+    async activateRunScene(seed, tier, opts) {
+        this._tier = tier;
+        this.sceneSeed = seed;
         // A call partner from the old scene wouldn't exist in the new one --
         // hang up before moving on, rather than leave a dangling reference.
         if (this.player.activeCallPartner) {
+            this.player.activeCallPartner.activeCallPartner = undefined;
             this.player.activeCallPartner = undefined;
         }
-        // false: this is a continuation, not a fresh game -- the player already
-        // has gear from prior jobs, so don't dump another starter kit on top.
-        this.scene = await SceneSynthesizer.synthesizeFromJson(nextSeed, this.player, this._useAi, false);
+        // false, false: no starter kit (the player carries their own gear
+        // forward), and no blocking AI-redressing pass either -- the chunked
+        // rooms pass already wrote this scene's prose.
+        this.scene = await SceneSynthesizer.synthesizeFromJson(seed, this.player, false, false);
         this.scene.initialize(this);
         this.player.currentLocation = this.determineStartRoom();
         // New job, fresh luck (see commands/edge.ts).
         this.player.refreshEdge();
         // The home base is owned by Game, not any one Scene -- re-inject it and
-        // rewire its one exit to point at this job's start room instead of the
-        // just-abandoned one.
+        // rewire its one exit to point at this job's start room.
         this.scene.addRoom(this._homeRoom);
         this.connectHomeRoom(this.player.currentLocation);
+        if (opts.startInHideout) {
+            this.player.currentLocation = this._homeRoom;
+        }
         this.updateEquipment(this.player.equipment);
         this.updateInventory(this.player.inventory, capitalCase(this.scene.getCurrencyType()));
         this.updateExits(this.player.currentLocation);
         this.updateStatus();
-        return `\n=== JOB #${this._tier}: ${nextSeed.name} ===\n${this.scene.story}`;
+        // Fresh streets, no trail yet (see Player.cameFrom / the HUD crumb).
+        this.player.cameFrom = undefined;
+        this.warmNpcAppearancesInBackground();
+        return `\n=== JOB #${this._tier}: ${seed.name} ===\n${this.scene.story}`;
+    }
+    /**
+     * "travel": takes the arranged transport to the pending job (see
+     * commands/travel.ts). The player arrives AT the run's start room --
+     * "You travel to <location>" -- not teleported onto their own cot.
+     * A haggle struck during the offer call already mutated the pending
+     * seed's payout, and stays spent across the transition (refreshEdge
+     * would otherwise re-arm it).
+     */
+    async launchPendingRun() {
+        const seed = this._pendingRunSeed;
+        const tier = this._pendingRunTier;
+        if (!seed || tier === undefined) {
+            return `There's no job waiting. "call ${FIXER_NAME}" to drum one up.`;
+        }
+        const haggledAtOffer = this.player.haggledThisJob;
+        try {
+            const banner = await this.activateRunScene(seed, tier, { startInHideout: false });
+            this._pendingRunSeed = undefined;
+            this._pendingRunTier = undefined;
+            this._pendingRide = undefined;
+            this.player.haggledThisJob = haggledAtOffer;
+            return `You travel to ${this.player.currentLocation.name}.\n${banner}`;
+        }
+        catch (err) {
+            this._pendingRunSeed = undefined;
+            this._pendingRunTier = undefined;
+            this._pendingRide = undefined;
+            Logger.getInstance().error(`launchPendingRun failed: ${err}`);
+            return `The ride never shows and the job address goes dead. ${FIXER_NAME} will not enjoy hearing this -- call him for another.`;
+        }
     }
     async close() {
         this._inputBox.removeAllListeners(); // removes all event listeners
@@ -471,8 +695,13 @@ export default class Game {
         // is illegible enough that the stance looked absent entirely.
         const stanceColor = player.autoStance === 'aggressive' ? 'red' : player.autoStance === 'guarded' ? 'yellow' : 'white';
         const stance = `{${stanceColor}-fg}⚔ ${player.autoStance.toUpperCase()}{/${stanceColor}-fg}`;
+        // The breadcrumb, reading chronologically into the current location:
+        // "Neon Strip (west) > Night Market" -- origin first, the direction
+        // BACK to it in parens. An 18-room hub made "which way did I come in"
+        // a real question.
+        const crumb = player.cameFrom ? `${player.cameFrom.room} (${player.cameFrom.back}) > ` : '';
         if (player.currentLocation) {
-            lines.push(`{bold}📍 ${player.currentLocation.name}{/bold}  |  ${stance}`);
+            lines.push(`${crumb}{bold}📍 ${player.currentLocation.name}{/bold}  |  ${stance}`);
         }
         else {
             lines.push(stance);
@@ -493,15 +722,22 @@ export default class Game {
         // actually live (equipped), the recurring "why can't I call anyone"
         // friction surfaced at a glance.
         const weapon = player.getWeaponProfile();
-        const weaponItem = player.equipment.rightHand?.weapon ?? player.equipment.leftHand?.weapon;
+        const weaponItem = player.getCarriedWeapon();
         const ammoNote = weaponItem?.isFirearm()
             ? (weaponItem.jammed
                 ? ` {red-fg}[JAMMED -- reboot]{/red-fg}`
                 : weaponItem.ammo === 0 ? ` {red-fg}[DRY]{/red-fg}` : ` [${weaponItem.ammo} rds]`)
             : '';
-        const armed = weapon.name === 'bare fists'
-            ? `{gray-fg}Unarmed{/gray-fg}`
-            : `Armed: ${weapon.name} (DV ${weapon.damage}${weapon.poolBonus > 0 ? `, +${weapon.poolBonus} dice` : ''})${ammoNote}`;
+        // Three armed states on the meat plane: drawn, holstered (weapon
+        // carried but riding leather -- "brandish" puts it in hand; combat
+        // auto-draws so this is posture, not readiness), or nothing at all.
+        // Off-plane the profile is attack programs / astral will and reads as
+        // Armed. White, not gray, for the same legibility reason as the stance.
+        const armed = player.plane === 'meat' && weaponItem && !player.weaponDrawn
+            ? `{white-fg}Holstered: ${weaponItem.name}${ammoNote} -- "brandish"{/white-fg}`
+            : weapon.name === 'bare fists'
+                ? `{gray-fg}Unarmed{/gray-fg}`
+                : `Armed: ${weapon.name} (DV ${weapon.damage}${weapon.poolBonus > 0 ? `, +${weapon.poolBonus} dice` : ''})${ammoNote}`;
         const armorNote = `Armor +${player.getArmorValue()}`;
         const hasLink = player.equipment.head?.commlink != null;
         const link = !hasLink
@@ -517,6 +753,12 @@ export default class Game {
         if (player.sustainedArmor > 0) {
             lines.push(`{magenta-fg}Sustained: armor +${player.sustainedArmor} soak (-2 dice to everything else){/magenta-fg}`);
         }
+        if (player.astralPerceiving) {
+            lines.push(`{magenta-fg}✧ ASTRAL SENSES OPEN (-2 dice sustained) -- "assense" to close{/magenta-fg}`);
+        }
+        if (player.sneaking) {
+            lines.push(`{white-fg}🐾 SNEAKING -- entries are opposed vs their perception; loud acts break it{/white-fg}`);
+        }
         if (player.activeCallPartner) {
             lines.push(`{${CALL_COLOR}-fg}${CALL_ICON} On a call with ${player.activeCallPartner.name}{/${CALL_COLOR}-fg}`);
         }
@@ -562,7 +804,10 @@ export default class Game {
         return Game.instance;
     }
     async handleInput(input) {
-        const parts = input.trim().split(' ');
+        // "jack-in"/"jack-out" read naturally but parse as unknown verbs (a
+        // real session typed "jack-in" and bounced) -- normalize the hyphen.
+        const normalized = input.replace(/^\s*jack-(in|out)\b/i, 'jack $1');
+        const parts = normalized.trim().split(' ');
         const verb = parts[0].toLowerCase();
         const args = parts.slice(1);
         if (verb === 'quit' || verb === 'exit') {
@@ -572,19 +817,13 @@ export default class Game {
             return 'You are still in the game, type "quit" to exit';
         }
         if (verb === 'continue') {
-            // Instant feedback for "not ready yet" (job not done, no AI
-            // configured); otherwise kicks off drafting in the background rather
-            // than freezing this command (and everything after it) behind a
-            // 20-40+ second generation call -- same as calling the fixer does.
-            const gate = this.canDraftNextScene();
-            if (!gate.allowed) {
-                return gate.message ?? `This job isn't finished yet.`;
-            }
-            this.draftNextSceneInBackground();
-            return `Understood -- drafting the next job now. Feel free to keep exploring in the meantime.`;
+            // RETIRED verb, kept only as a redirect: jobs flow through the
+            // fixer ("call Mr. Johnson"), and a finished run ends by walking
+            // home to your hideout -- no system command in the loop.
+            return `That's not how the street works anymore, chummer: "call ${FIXER_NAME}" when you want work. When a run's wrapped, head home to your hideout -- the door knows the way.`;
         }
         if (verb === 'help') {
-            return this.getHelpMessage();
+            return this.getHelpMessage(args);
         }
         if (verb === 'clear') {
             return '';
@@ -601,21 +840,103 @@ export default class Game {
             const result = await command.execute(args);
             return result;
         }
+        // Typo tolerance: two straight sessions bounced on slips like "searh"
+        // and "maop". Reuse the same fuzzy matcher item/NPC names go through
+        // (ambiguous guesses deliberately miss). A unique match auto-runs with
+        // a note -- EXCEPT anything that ends the session, which only ever
+        // gets a suggestion: a typo must never quit the game.
+        const knownVerbs = [...Object.keys(CommandFactory.getAllRegisteredCommands()), 'help', 'clear', 'quit', 'exit'];
+        let guess = fuzzyPickName(verb, knownVerbs);
+        // The shared matcher refuses typo tolerance on words <= 3 chars (too
+        // risky for item/NPC names) -- but the verb list is small and
+        // distinct, so a unique edit-distance-1 hit is safe ("maop" -> "map").
+        if (!guess && verb.length >= 3) {
+            const close = knownVerbs.filter(v => levenshteinDistance(verb, v) <= 1);
+            if (close.length === 1)
+                guess = close[0];
+        }
+        if (guess && guess !== verb) {
+            if (guess === 'quit' || guess === 'exit') {
+                return `I don't understand "${verb}" -- did you mean "${guess}"?`;
+            }
+            const corrected = await this.handleInput([guess, ...args].join(' '));
+            return corrected === null ? null : `(read "${verb}" as "${guess}")\n${corrected ?? ''}`;
+        }
         return `I don't understand the command "${verb}".`;
     }
-    getHelpMessage() {
-        const commands = CommandFactory.getAllRegisteredCommands();
-        let helpText = "Available Commands:\n";
-        for (const verb in commands) {
-            if (Object.hasOwn(commands, verb)) {
-                const CommandClass = commands[verb];
-                helpText += `- ${verb}: ${CommandClass.getDescription()}\n`;
+    /**
+     * The help taxonomy: every entry is [primary, ...aliases], grouped the
+     * way a player thinks, not the order commands were registered. The
+     * overview shows only verbs per category (the flat all-descriptions
+     * dump had grown past 45 lines); "help <category>" and "help <command>"
+     * drill into the real descriptions. Verbs registered but missing from
+     * this table surface in an "other" bucket rather than vanishing -- a
+     * future command can't silently fall out of help.
+     */
+    static HELP_CATEGORIES = [
+        { title: 'moving', entries: [['look'], ['go'], ['map', 'exits'], ['search'], ['sneak']] },
+        { title: 'gear', entries: [['inv', 'inventory'], ['equipment', 'eq'], ['take'], ['drop'], ['give'], ['store'], ['equip'], ['unequip'], ['brandish', 'draw'], ['holster', 'stow'], ['reload'], ['use'], ['read']] },
+        { title: 'combat', entries: [['attack', 'kill'], ['subdue'], ['stance'], ['surrender'], ['edge'], ['rest']] },
+        { title: 'magic', entries: [['spells'], ['cast'], ['project'], ['return'], ['assense']] },
+        { title: 'matrix', entries: [['jack'], ['hack'], ['pan'], ['silent'], ['reboot'], ['drone']] },
+        { title: 'social', entries: [['say'], ['talk-to'], ['call'], ['end-call', 'end', 'hangup'], ['haggle', 'negotiate'], ['persuade', 'convince']] },
+        { title: 'barriers', entries: [['solve'], ['pick'], ['bluff'], ['unlock'], ['lock']] },
+        { title: 'character', entries: [['sheet', 'stats'], ['advance', 'train']] },
+        { title: 'session', entries: [['help'], ['clear'], ['quit', 'exit']] },
+    ];
+    /** Descriptions for the verbs handled inline in handleInput() rather than registered. */
+    static BUILTIN_DESCRIPTIONS = {
+        help: 'This overview. "help <category>" for one group with full descriptions; "help <command>" for one command.',
+        clear: 'Clear the screen.',
+        quit: 'Exit the game.',
+    };
+    describeVerb(verb) {
+        const builtin = Game.BUILTIN_DESCRIPTIONS[verb];
+        if (builtin)
+            return builtin;
+        const CommandClass = CommandFactory.getAllRegisteredCommands()[verb];
+        return CommandClass?.getDescription() ?? 'No description available.';
+    }
+    getHelpMessage(args = []) {
+        const registered = Object.keys(CommandFactory.getAllRegisteredCommands());
+        const covered = new Set(Game.HELP_CATEGORIES.flatMap(c => c.entries.flat()));
+        const uncategorized = registered.filter(v => !covered.has(v));
+        const query = args.join(' ').trim().toLowerCase();
+        // "help <category>": that group, with full descriptions.
+        if (query) {
+            const categoryNames = Game.HELP_CATEGORIES.map(c => c.title);
+            const pickedCategory = fuzzyPickName(query, categoryNames);
+            if (pickedCategory) {
+                const category = Game.HELP_CATEGORIES.find(c => c.title === pickedCategory);
+                const lines = [`=== ${category.title.toUpperCase()} ===`];
+                for (const [primary, ...aliases] of category.entries) {
+                    lines.push(`- ${primary}${aliases.length > 0 ? ` (${aliases.join(', ')})` : ''}: ${this.describeVerb(primary)}`);
+                }
+                return lines.join('\n');
             }
+            // "help <command>": one description, aliases resolved to their primary.
+            const allVerbs = [...covered, ...uncategorized];
+            const pickedVerb = fuzzyPickName(query, allVerbs);
+            if (pickedVerb) {
+                const entry = Game.HELP_CATEGORIES.flatMap(c => c.entries).find(e => e.includes(pickedVerb));
+                const primary = entry?.[0] ?? pickedVerb;
+                const aliases = entry?.slice(1) ?? [];
+                return `${primary}${aliases.length > 0 ? ` (${aliases.join(', ')})` : ''}: ${this.describeVerb(primary)}`;
+            }
+            return `No command or category called "${query}". Try plain "help".`;
+        }
+        // The overview: compact category lines, primaries only.
+        const lines = ['=== COMMANDS ==='];
+        const pad = Math.max(...Game.HELP_CATEGORIES.map(c => c.title.length));
+        for (const category of Game.HELP_CATEGORIES) {
+            lines.push(`${category.title.padEnd(pad)}  ${category.entries.map(e => e[0]).join(', ')}`);
+        }
+        if (uncategorized.length > 0) {
+            lines.push(`${'other'.padEnd(pad)}  ${uncategorized.join(', ')}`);
         }
-        helpText += `- clear: Clear the screen.\n`;
-        helpText += `- continue: Take on a new, tougher job once you've completed the current one.\n`;
-        helpText += `- quit: Exit the game.\n`;
-        return helpText;
+        lines.push('');
+        lines.push(`"help <category>" for a group with descriptions ("help combat"); "help <command>" for one ("help haggle").`);
+        return lines.join('\n');
     }
 }
 //# sourceMappingURL=game.js.map