toastsim/MASTERPLAN.md

# TOASTSIM → THE RAD KITCHEN — Master Plan

*2026-07-17. This sits above the build briefs. Each phase below gets cut into an
OPUS-BUILD-BRIEF-N.md when its turn comes; parallel Opus agents build inside a
phase in separate file lanes; Fable reviews every stage against the exit bar
with harness numbers before merge. "It's been done"? Sure. Ours is better, and
it will keep getting better.*

## 0. The one-sentence pitch

A kitchen where every station is the same game — fields, points, doses, and
nerve — and a judge who notices everything, played from toast to a full pass.

## 1. The design law (unchanged, non-negotiable)

One game, not minigames in a trench coat. Every new mechanic must ride the
proven bones or improve them for everyone:

| Bone | Proven by | Generalizes to |
|---|---|---|
| **Field** (2D scalar grid + stats) | browning, spread, damage, mess | pan sear, egg set, sauce coverage, plate composition heat |
| **Point statistics** (Clark–Evans) | crust rind, toppings | plating layout, garnish scatter, seed mess |
| **Cutting sim** (bite/saw/slip/wobble) | bread, tomato, mushrooms | steak (grain axis), potato lid (depth), everything |
| **Dose/mass tracking** | spreads, juice | salt, capers, wasabi, sauces, butter-in-pan |
| **Temperature clock** | butter softness, fridge/bench | rest clock, pan heat, egg water, sog |
| **Swirl/gesture detection** | jar remix, reamer twist | whisking, poach vortex, sauce swoosh |
| **Dwell commits + judge bands + lines** | everything | everything |
| **Dev harness** (real input, deterministic dt) | every milestone | every milestone — no unverified feel, ever |
| **MODELBEAST pipeline** | the current cast | unlimited free assets; trial-and-error is cheap, bad eggs allowed |

## 2. The foundation doctrine: SALT & BUTTER

John's law: *butter and salt are the foundation, really.* So they are
**cross-cutting systems**, not ingredients — every phase from P2 on hooks them.

**Salt is two objects and a timing question.**
- **Fine table/cooking salt**: dissolves, penetrates, seasons DURING cooking.
  Cheap, correct, invisible when right.
- **Flaky finishing salt** (the good stuff): texture + sparkle, plating ONLY.
  The cardinal sin — cooking off the good salt: flakes into a hot pan dissolve
  into ordinary salinity and the judge KNOWS: *"You cooked with the
  finishing salt. I can hear it weeping."* Inverse sin: table salt at the
  pass reads flat — *"sad little grains."*
- Mechanics: one shared **dose curve** (under = unnoticed, right = bonus,
  over = ruined) — the same curve class capers and wasabi use (Brief 2 §7.5),
  built once. Plus a **timing check**: salt-type × when-applied matrix.

**Butter is a state machine, everywhere.**
- Spread (done, M2+), softness clock (done).
- P2 adds **butter as cooking medium**: cold → foaming (the moment) → browned
  (beurre noisette, flavour bonus) → burnt (bitter, mess). Heat × time on the
  existing temperature clock. Basting = a gesture that paints the sear Field.
- P3 closes the loop beautifully: over-whip cream long enough and you MAKE
  butter. The game teaches where butter comes from by punishing you with it.

## 3. The map — six phases

### P0 — TOAST (done: M0–M11 core)
Toaster, spreads, jars, bakery, prep bench core. The bones exist and are
measured. Remaining: M11 finish line (route days through the bench) — first
lane of Stage 1.

### P1 — THE PREP BENCH (Brief 2: M12–M15, specced, next to build)
Oranges + ribbed pyramid juicer, grater, onions, bruschetta capstone.
Plus the pantry backlog already in the cast: mushrooms ×3, bell pepper.
**Feel that must be right:** the reamer twist, the onion stop-line.

### P2 — FIRE (the pan) — *the steak phase*
The one new primitive: **the pan** = a heat source under a Field, like the
toaster but continuous, visible, and yours to modulate.
- **Rib eye, in full:**
  1. **Salt it** — when? Properly early (penetrates) or at the pass (crust);
     mid-cook sprinkle = amateur hour. Salt type matters (§2).
  2. **Cook it** — sear Field per side; flip timing; butter + baste;
     doneness = interior ramp (new 1D depth profile per Field cell — reuses
     the browning math pointed inward). Mushrooms & peppers cook here too.
  3. **REST it** — the nerve test. Rest clock: cut at 0s and juice mass
     (moisture 0.95→0.6 decay) floods the board — the mess field's finest
     hour. The ticket tempts you; the judge times you.
  4. **Cut it** — new `grain` axis on Ingredient; score cut-angle vs grain;
     wobble TEARS. Across the grain or it's chewing gum.
  5. **Pair it** — right mustard from the family (Brief 2 §7.5).
- Judge groups: The Season / The Cook / The Rest / The Cut / The Pairing.
- **Feel that must be right:** the sizzle-to-rest silence, and juice flooding
  when you cut too early. Player must FEEL the urge to cut early and learn.

### P3 — EGGS & AIR
Two new gestures on old bones, then the near-game:
- **Whisking/whipping**: sustained swirl detection + shear accumulation →
  cream: liquid → soft peaks → stiff peaks → grainy → **butter** (see §2).
  Field stores air fraction; judge pokes the peak on camera.
- **The poached egg** — almost a whole game, treated with respect:
  water temp band (clock), the **vortex** (reamer-twist gesture at pot
  scale), the drop (timing + height), white-set vs yolk-liquid as a
  **two-layer Field** (set outer, liquid inner — the toast browning math with
  a phase boundary), the lift, the drain, the **wobble test** — judge presses
  it: *"It should tremble. Like you, right now."*
- **Feel that must be right:** the vortex drop, and the wobble.

### P4 — THE PASS (plating)
Composition becomes the scored surface. The plate is a Field + point set:
- **Placement** = Clark–Evans + mass balance bands (M15 topping math, plate-
  sized). Height/stacking as a bonus axis.
- **Sauce gestures**: dots (dose curve), the smear/swoosh (a spread stroke
  scored on confidence — ONE motion, hesitation reads in the Field),
  drizzle (path statistics).
- **Garnish = the dosing danger class**: capers, flake salt, herbs. Tiny
  masses, brutal curves (§2). Wrong-salt-at-the-pass judged here.
- **Feel that must be right:** the swoosh. One confident stroke.

> **P6–P12 live in KITCHEN-ATLAS.md** — water & oil, the spice rack (the
> irreversibility doctrine), the knife roll + drills, directed heat (the
> torch, the crack), cold & time (cures across days), and the banquet
> (carving, the symphony). Read it after P2 ships; suggested weave in its §8.

### P5 — SERVICE (the restaurant)
The kitchen becomes one organism: multi-course orders, the planning clock
generalized (M15's fridge/bench timing at menu scale), stations in parallel,
the pass as the bottleneck. **Baked stuffed potato** lands here as the
multi-station capstone (bake → lid cut → scoop → mix → restuff → rebake —
Brief 2 §7.5). Career arc: the menu grows day by day; the judge brings
FRIENDS. S-rank a full service = the diploma.

## 4. The build model (stages, agents, review)

- **Stage = one phase slice with 2–3 parallel Opus agents**, each in its own
  git worktree, each owning a disjoint file lane (one owns `src/sim/X.ts` +
  its harness helpers; another owns scene/UI; a third fires asset batches and
  does judge lines). Lanes declared in the stage brief; game.ts merge
  conflicts resolved at review, not shared live.
- **Agents verify with typecheck + build; Fable holds the browser** — harness
  numbers and screenshots are the REVIEW gate, run by the reviewer, so no two
  agents fight over the preview pane. No milestone merges without numbers.
- **Exit bar per stage** (same as ever): played-through with numbers in the
  commit message, screenshots, feel-check on the phase's named feel. Feel
  wrong = fix feel before advancing, always.
- **Bad eggs policy**: assets are free and code is cheap — trial fearlessly,
  kill quickly. A mechanic that isn't fun after its harness works gets ONE
  retune pass, then it's cut and logged in the brief. No sunk-cost stations.
- Commit discipline unchanged: one commit per milestone, message = what you
  measured, push to Gitea.

## 5. Asset batches (MODELBEAST, seeds reserved per phase)

- **P1**: in flight (prep cast rendering now) + mushrooms ×3, bell pepper.
- **P2**: cast-iron pan, raw rib eye (marbling!), cooked steak rested + cut
  showing pink interior, salt cellar (fine) + salt dish (flakes), butter
  block in pan, tongs. Seeds 170–199.
- **P3**: whisk, copper bowl, egg carton, single egg, poach pot, slotted
  spoon, cream carton. Seeds 200–229 (2D: soft/stiff peak reference cards).
- **P4**: big white plates ×3 shapes, squeeze bottle, microgreens, sauce
  spoon. Seeds 240–269.
- **P5**: the pass window, docket rail, second toaster (!). Seeds 270+.
- Anything the player identifies by shape or that carries physics stays
  procedural — silhouettes are gameplay (unchanged law).

## 6. Order of battle

1. **Stage 1 (now)**: M11 finish line + M12 juicer, parallel lanes.
2. Stage 2: M13 grater + M14 onions.
3. Stage 3: M15 bruschetta (single lane — it's integrative by nature).
4. Stage 4: cut Brief 3 from P2 (salt system + pan + steak). The big one.
5. Stage 5+: P3 eggs, P4 plating, P5 service — brief per phase, re-planned
   against what the previous phase taught us.

The bet, restated for the whole kitchen: the bones are good, so every station
is the bones wearing a new apron — and the game stays ONE game, from a slice
of toast to a full Saturday service.