recordstoreguy/PLAN.md

# RECORD STORE GUY — master execution plan
*(title FINAL — John's executive call, 2026-07-19)*

Dragon's Lair / Space Ace-style FMV QTE game: a guy in a record store surviving
escalating, ridiculous, surreal hazards — the floor floods into a shark ocean,
turns to lava, the roof rips off into space, the store goes full Tron. Uncharted-
level setpiece adrenaline + Dragon's Lair wrong-move-you're-dead urgency + comedy.
AI-generated 4–5s clips (Google Flow / Veo, John's 9000 paid credits) strung
together by a web player demanding precisely-timed inputs. Creative design of the
worlds/setpieces: **WORLDS.md** (read it after this file).

**Division of labor (hard rule):**
- **Google Flow (9000 credits)** = ONLY the final in-game video clips. John paid for
  these and wants them used — but never wasted on tests that FLUX can do.
- **MODELBEAST FLUX (`flux_local`, free, ~9s/image)** = all concept art, character
  bible references, style frames, marketing art, and the stills we upload to Flow
  as "ingredients" for character consistency.
- **MODELBEAST local video ops** = optional pre-viz/animatics only, never final clips.

## Environment facts (verified 2026-07-19 on m3ultra)
- MODELBEAST queue **UP**: `http://100.89.131.57:8777` (34 operators). This machine
  (m3ultra) IS the primary.
- CLI: `~/Documents/MODELBEAST/mb` (stdlib-only python). Needs `MB_TOKEN` env var.
  **Token was NOT found on m3ultra** — it lives in `~/Documents/backnforth/.env` on
  **ultra** (per fleet skill), or create/read one via MODELBEAST web UI ⚙ Settings →
  Users → token, or `scripts/users.py`. Read from disk; never print/commit it.
  Example: `MB_TOKEN=$(ssh ultra@100.91.239.7 'grep MB_TOKEN ~/Documents/backnforth/.env | cut -d= -f2')` — or ask John which token to use. Guest tokens cap at 4 active jobs.
- ffmpeg: `/opt/homebrew/bin/ffmpeg` ✅
- Project dir created: `~/Documents/recordstoreguy/` with `bible/concept/`, `engine/clips/`, `tools/`.

## Phases

### Phase 1 — Engine shell with placeholder clips (zero credits)
Build the full player before any real video exists. Placeholders prove the QTE feel.
Spec: `ENGINE.md`. Placeholder generator: `tools/make_placeholders.sh` (ffmpeg
test-pattern clips with big text + a visual "beep" flash at the QTE window so timing
is testable by eye). Definition of done: playable in browser start→3 scenes→death→
retry→win, lives counter, attract loop, debug overlay showing windows.

### Phase 2 — Bible + FLUX concept art (zero credits)
`bible/BIBLE.md` holds the verbatim STYLE/CHARACTER/SET blocks (drafted — see file).
Generate concept art on MODELBEAST; iterate until John approves each. Commands:

```sh
cd ~/Documents/MODELBEAST
export MB_TOKEN=...   # from disk, see above
./mb run flux_local -p prompt="<PROMPT>" -p seed=<N> --wait --download ~/Documents/recordstoreguy/bible/concept/
```

Concept shot list (full prompts in BIBLE.md §Concept-art prompts):
1. `hero_sheet` — Dez full-body turnaround, neutral pose, front+side
2. `hero_face` — close-up head, 3/4 view (this becomes the Flow ingredient)
3. `villain` — the antagonist (direction TBD with John — see Open Decisions)
4. `store_wide` — the record store master set, wide establishing
5. `store_backroom` — second set (stockroom / listening booth)
6. `style_frame` — one full "this is what the game looks like" money shot
7. `death_concept` — one comedic death (shelf of crates toppling)
8. `title_card` — RECORD STORE GUY logo/marquee concept
Run 3–4 seeds each, keep best. Free, so iterate hard BEFORE touching Flow.

### Phase 3 — Flow consistency test (~100 credits MAX, gated on John's approval)
In Google Flow (browser; John logs in himself — never handle his credentials):
1. Upload approved `hero_face` + `hero_sheet` FLUX stills as **ingredients**.
2. Generate 5 test clips, Veo Fast (~20 cr each): same character, same set block,
   5 different one-sentence actions (walk-in, duck, grab record, get scared, run).
3. Judge: does the face/outfit/style hold across clips? Log verdicts in
   `production/SHOTLOG.csv`. If it holds → green-light full production. If not →
   revise ingredients/style block with more FLUX iterations and retest (another ~100).

### Phase 4 — Story + scene graph (with John — mise en scène discussion)
Creative direction now drafted in `WORLDS.md` (premise, 7 worlds, setpieces, deaths,
clip budget). Remaining work this phase: John iterates WORLDS.md, then:
- `scenes.json` fully authored (schema in ENGINE.md) with per-scene prompt sheets in
  `production/prompts/` — each sheet is the verbatim template with only the action
  sentence and camera line filled in.

### Phase 5 — Batch production in Flow (the 9000 credits)
Budget: 9000 cr ≈ 450 Veo Fast gens. Keep-rate assumption 1-in-2.5 → ~180 usable
clips. Target game: ~35 scenes × (1 action clip + 1 death clip) + intro + attract +
game-over + win ≈ **80 final clips** → ~200–280 gens spent, leaving reserve for
hero-moment quality gens (100 cr each, use sparingly: intro, final scene, best deaths).
Discipline:
- Work scene-by-scene from prompt sheets; NEVER freestyle a prompt in Flow.
- Frame-chain within a scene (last frame → start frame / Flow extend) for continuity;
  hard cuts between scenes hide the rest.
- Log every gen in `production/SHOTLOG.csv`: `scene_id,take,credits,verdict,notes`.
  Running credit total in the log; stop and re-plan if burn rate exceeds 2× budget line.
- Download keepers to `production/raw/`, then `tools/postprocess.sh` (ffmpeg: trim,
  normalize to 24fps 1280×720 h264 + aac silent/or SFX bed, name `<scene_id>_<kind>.mp4`)
  into `engine/clips/`.

### Phase 6 — Sound + deploy
- SFX/music: needle-drop crackle bed + stingers. (m1max is the audio machine but
  disk-critical — keep audio work local or ask John.)
- Deploy: static site → botchat games VPS (`humanjing@100.71.119.27`, docker) next to
  the other partly.party games, per deploy-map skill. Verify live with cache-busted curl.
- Run ship-check skill before exposing publicly.

## Decisions status
1. **Title**: ✅ RECORD STORE GUY (final, John 2026-07-19).
2. **Premise/worlds/tone**: ✅ surreal escalating setpiece worlds, Uncharted chaos +
   comedy deaths — designed in WORLDS.md (John reviews/iterates the specifics).
3. **Art style**: OPEN — plan assumes 80s hand-drawn cel (Bluth-adjacent); alt is
   live-action FMV cheese. Style block in BIBLE.md is written for cel — decide before Phase 3.
4. **Hero design**: OPEN — "Dez" is a placeholder design; John approves/redirects at
   concept-art review.
5. **Villain**: recommended **The Dead Wax** (fits WORLDS.md arc) — confirm with John.

## File map
```
recordstoreguy/
  PLAN.md            ← this file (master; Opus starts here)
  WORLDS.md          ← creative design: premise, 7 worlds, setpieces, QTEs, deaths, clip budget
  ENGINE.md          ← full engine spec (schema, player loop, QTE rules, placeholder script spec)
  bible/BIBLE.md     ← style/character/set blocks, prompt grammar, concept-art prompts, Flow workflow
  bible/concept/     ← FLUX outputs land here
  engine/            ← index.html, player.js, styles.css, scenes.json, clips/
  tools/             ← make_placeholders.sh, postprocess.sh
  production/        ← (Phase 4+) prompts/, raw/, SHOTLOG.csv
```
Git: repo lives at `~/Documents/recordstoreguy`, remote already configured:
`origin ssh://git@100.71.119.27:222/monster/recordstoreguy.git` (Gitea). Never commit
tokens; engine/clips + production/raw are gitignored (video bulk stays out of git).