Kingpin's Room v1: build plan

Status: 2026-10-14, Claude for Sarah. Built the same day and not yet committed: the engine (19 tests), the import, the views and two full-run UI tests all pass. Replaces Kingpin Showdown. The art comes from the finished pack at Image-Assets/Kingpins-Room/ (78 files), governed by kingpin-art-spec.md. Calico's concede and win frames are stand-ins until Sarah's corrections land.

Rules

Decided by Sarah, 2026-10-14

• Boss pools. Each boss plays their whole con family:
  • Contrarian: text (97 questions)
  • Professor: dodge (89)
  • Mistranslator: math (90)
  • Absolutist: overplay (39)
  • Splicer: sentence (49)
• The player knows the family. Sitting across from a boss announces the family. The skill being trained is finding that family's trap in a real question. Calico's hands announce nothing, so the run moves from named traps to unnamed ones.
• The Squint is out of play. The figure family has no questions, so R1 shows its tucked empty chair.
• Rotation. The bosses play in turn around the table in seat order (L1, R1, L2, R2, L3, R3), skipping the Squint and anyone eliminated.
• Elimination. A boss leaves after the player has beaten them twice. The wins add up across the run and don't have to come in a row. A miss doesn't reset the count.
• The pot. One pot for the whole run. It starts at 1000. Each boss miss takes 100 off it and leaves a chip on the table. Wins don't add to it. It never drops below 200, so the player always has something at stake at Calico's table.
• Calico. Once every boss has left, she plays three questions. Each one carries traps from at least two families and is weighted toward this run's chips. Any miss is instant death: she takes the whole pot, and the run banks 0. Clear all three and the run banks what is left of the pot.
• The score. A run scores the pot it banks, from 0 to 1000.
• The old game goes. Kingpin's Room takes the kingpin game key, the Underworld plate and the route. KingpinShowdownView is removed.

Decided earlier (memory, art spec)

• Every hand is one real bank question. The boss's family trap is a live wrong answer.
• Calico's weighting uses this run's chips only. After a clean sweep, it falls back to the family the player has missed most often, from the shared miss source.
• Chips stay on the table after their boss leaves.
• Steering copy comes from the room or the Docket, never from Falconer.

Defaults Claude chose (Sarah can overrule any of them)

1. Boss hands have no clock. Only Calico's hands drain the pot over time.
2. Calico's clock. During each of her hands the pot holds for ReadingBudget.readOnlySeconds, so the clock never cuts into reading. It then drains in a straight line, losing up to 150 points by the end of ReadingBudget.seconds, and holds there. The floor of 200 still applies. A slow clean sweep of her three hands costs at most 450.
3. Where a chip goes. A wrong pick puts the chip in front of the boss whose family owns the trap the player took, even if that boss has already left. The boss whose hand it was stays in the rotation either way. Untagged wrong choices, and traps from a family with no boss in play, put the chip with the hand's boss. This keeps the chips an honest record of which families cost the player, which is what Calico's weighting reads.
4. Questions don't repeat within a run. If a family runs out, its boss draws again from questions already played this run, least recent first. Overplay has the smallest pool, at 39.
5. A run is not saved. Leaving mid-run abandons it, as in The Tail. A run is about 16–18 hands: ten boss wins, the misses, and Calico's three.
6. Content modes. Kingpin now deals from the Wager bank, so it gets all three modes: Fresh, Endless and My Misses. Under My Misses, each boss deals the player's open misses from their family first, then fills from the family pool. It leaves the makeable path that The Make still uses.
7. Result rows. Each hand writes a VigilanceResult. Its points are the hand's change to the pot: −100 for a boss miss, 0 for a boss win, the clock's drain on a Calico win, and minus the whole pot on a Calico miss. The run's NightTake carries the banked pot.

Architecture

Core: PeregrineCore/Sources/PeregrineCore/Vigilance/KingpinRun.swift

A pure value type with no UI. It holds:

• Seats: L1 … R3, each with a boss id, a state (seated, rising, departed, vacant) and a chip count.
• The deal: nextHand() returns the boss and the question, from the family pool built out of VigilanceBank.withGenerated().wagerQuestions filtered by Con.Family. For My Misses, the pool comes through MissSource.deal.
• Answers: answer(pick:) returns the outcome, the points, which seat takes the chip, and whether the boss leaves.
• Calico: calicoQuestions(lifetimeMisses:) picks three from the items whose traps span at least two families (102 in the current bank), weighted by this run's chips, with the clean-sweep fallback. calicoDrain(elapsed:read:budget:) gives the clock's drain within a hand.
• Tests go in KingpinRunTests:
  • the pool sizes per family
  • no repeats until a pool runs out
  • chip attribution, including a trap from a departed boss's family
  • Calico weighting, and the clean-sweep fallback
  • rotation order, skipping the Squint and eliminated bosses
  • elimination after two wins, with a miss in between
  • the pot: −100 per boss miss, never below 200
  • Calico's clock: holds while reading, drains at most 150 per hand, respects the floor
  • instant death: a Calico miss banks 0
  • a seeded run through ten wins and three Calico hands

Art import: tools/kingpin_import.py

• Checks every file against the SHA-256 in the pack's manifest.json, the same way tail_import.py does.
• Writes Peregrine/Assets.xcassets/Kingpin/kingpin_<name>.imageset. The opaque plates become JPEG q86 4:4:4. Layers and sprites stay PNG.
• Crops each full-canvas room layer to its alpha bounds and records the offset in a generated Peregrine/Views/Kingpin/KingpinCatalog.swift. Stacking about twenty uncropped 1536×2304 RGBA layers would need roughly 280 MB of decoded image memory.
• Writes the seat anchors and per-seat chip and card scales from anchors.json into the catalog.
• Chip scale override. At true size the chip is about 3.6 pt on a phone. The catalog sets a readable minimum for the near seats and keeps the size ratio between near and far seats.
• Regenerates the game_kingpin plate from the final room.
• Stand-ins. The import takes Calico's concede and win frames as they are. When Sarah's corrected files arrive, their manifest hashes must be updated with them, or the import will refuse them.

App: Peregrine/Views/Kingpin/

• KingpinRoomView runs the run as a series of phases:
  1. the room
  2. a cut to the hand's close view
  3. the verdict
  4. back to the room, where the boss rises and their chair goes pushed, or a chip lands
  5. next hand
  6. after the last boss, the cut to Calico and her pot
  7. her concede or win frame
  8. the report, through NightDebrief with this run's points
• KingpinStage draws the room layers in the spec's order: plate, chair shadows, chairs, character shadows, characters, name cards, chips, then UI. It draws seats from far to near, so a nearer figure overlaps a farther one.
• KingpinHand shows the close plate, the boss or Calico, kingpin_paper as a nine-slice using the manifest's cap insets, and the question, choices and pot.
• Results. One VigilanceResult per hand, in the same shape as The Tail's:
  • game "kingpin", itemID, section, points, correct, playerPick
  • conID on a wrong pick
  • then GameFamiliarity.recordRound

Remove and rename

• Delete KingpinShowdownView.swift, including WindowRing and LiveWindowRing, which nothing else uses.
• Point PeregrineRootView (.kingpin and -routeKingpin) at the new view.
• GamesView: retitle the plate "Kingpin's Room", change its badge to the bank count, and take Kingpin out of the makeable / "The Make and Kingpin deal …" copy.
• Update the title strings in NightTake.swift:80, SkillMap.swift:56, YouView.swift:778 and NightDebrief.swift:60, and the string in TrainingGroundHubUITests.swift:105.
• Update the ContentSourceTests and LedgerTests lines that name Kingpin as a Make-path game.
• Run xcodegen generate after adding files.

Order of work

0. Tell the My Misses session (peregrine-22) that the build is starting, as agreed. Kingpin deals Wager-bank ids, so it needs no new lookup for its misses. Confirm that with them before writing any results.
1. Write KingpinRun and its tests.
2. Write kingpin_import.py, then import and generate the catalog.
3. Build KingpinStage and check the six seat states against the pack's review assemblies.
4. Build KingpinHand and the full run loop, writing results.
5. Calico's three hands, her clock and instant death.
6. Remove and rename everything above, regenerate the project, build, then run the unit and UI tests.
7. Simulator pass: a full run on an iPhone 16-class simulator, with screenshots of each phase for Sarah. Check what a phone shows on screen, and make no claim about how the game feels on a real device.

Known art issues carried in

• Rising layers (withdrawn 2026-10-14). The Wave 2 review reported that four rising layers erase the farther seats. A visual check of each overlap shows the boss's own clothing there: each riser stands in front of the farther chair, so covering it is correct depth. The pixel count behind the report had matched dark cloth against dark wood. No fix is needed.
• Calico's concede and win frames: Sarah's halo-free recuts landed in 0cf1e51.

Final review

Pros

• Reuses the bank, the miss source, the result shape and the debrief that The Tail and the Darkroom already use. Kingpin's results feed My Misses and the Trap Atlas with no changes there.
• The engine is pure and tested apart from the art, so rule changes stay cheap.
• The layered stage draws every seat state from the pack's own layers, so no art is re-composited by hand.

Cons and risks

• The import crops each layer and moves it by an offset. A wrong offset shows as a seam or jump between seat states. Step 3 compares each state against the painter's assemblies to catch it.
• The overplay pool has 39 questions, so a player who keeps losing to the Absolutist will see repeats sooner than with any other boss.
• Instant death is harsh by design. A player who gets 70% of Calico's mixed questions right clears her about a third of the time. Her clean-sweep and clear rates in playtesting will show whether three hands is right.
• The chip-scale override departs from true scale. It is a judgement call about readability that needs Sarah's eye on the simulator screenshots.
• Calico's 102 multi-family items are mostly generated questions, which carry no per-choice analysis. Her post-hand review will show less explanation than a boss hand on an authored question.

Edge cases

• The Squint enabled later with only a few figure questions. Gate the seat on a minimum pool size of 30, not on "any".
• My Misses with no open misses in a family. The backfill covers it.
• Fewer than three unplayed multi-family items. Calico then draws from the full multi-family set, least recent first.
• The app goes to the background during Calico's hand. The pot clock pauses, as the other timed games do.

Confidence: 80/100 that this is the right shape. The engine, results and import pattern are proven in The Tail and the Darkroom. The remaining uncertainty is in Calico's clock (default 2), chip attribution (default 3) and the chip scale, which only playing the game will settle.