picopilot 0.0.0 → 0.1.1

package/src/skills/game-design-reference/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: game-design-reference
+description: Reference body of universal game-design principles (fairness, human reaction budget, readability, visibility, originality method). A shared reference other skills point at (game-jam, and any make-a-game skill); not fired on its own.
+disable-model-invocation: true
+---
+
+# game design reference
+
+Universal principles of a GOOD game, true of any game regardless of engine, clock, or theme. This is a shared REFERENCE body: another skill (e.g. `game-jam`) points you here and you apply every principle below. It is engine-agnostic; where a check needs a concrete PICO-8 procedure (drive a cart, count frames), that lives in the loop skill `picopilot-debug` (playtest), which you follow the pointer into.
+
+The one failure mode that unites the traps below: **an agent playtests as a frame-perfect machine and never models a human player.** You can hit any button on the exact right frame and see every pixel, so a game that is fair-and-playable TO YOU can be unfair or impossible for a human. Every check here is you deliberately putting on the human's eyes and hands.
+
+## Fairness: never a dead state
+
+A game is UNFAIR when it can reach a state the player did nothing wrong to reach, from which EVERY available action leads to a loss. A death the player could not have avoided reads as the GAME cheating, not the player failing, and it damages fairness far more than a hard-but-fair challenge does. Fairness is "the player can always still win, even after a setback": from every state, at least one legal move is non-losing.
+
+This is distinct from DIFFICULTY. Hard is fine; a dead state punishes the player for the game's own design gap.
+
+**The self-check (the one that gets skipped).** When a game has HAZARDS plus LIMITED control (a few discrete actions), verify BOTH properties, not just the first:
+
+1. **Goal reachability** — from spawn/rest states, some sequence of actions reaches the objective. (Agents check this one.)
+2. **Hazard avoidability** — from EVERY state the player can settle/rest into, at least ONE available action is non-fatal. (Agents SKIP this one.) If a resting position exists where all actions force a loss, that is a DEAD STATE: a fairness defect. Fix the geometry (widen an exit, move the hazard, add a safe lane) so no such pocket exists.
+
+For a discrete-control game this is enumerable: drive the player into every corner/pocket it can settle in, then try EACH action and assert not-all-fatal. Do this with the playtest loop (`picopilot-debug`) deliberately, it will not happen by accident.
+
+## Reaction budget: a human is not frame-perfect
+
+Simple human reaction time is ~200-300ms (see a thing, press a button) and that is DETECTION only, before deciding what to do. At PICO-8's 30fps that is roughly **6-9 frames** just to react. So:
+
+- **Any required-input WINDOW narrower than ~6-9 frames is effectively frame-perfect** and unplayable by a human as a reaction (only as a memorised pattern).
+- **Do not tune difficulty against your own `--input` scripts.** If the ONLY way you can clear a level is a hand-timed frame sequence you authored, a human cannot clear it. That is the trap: you tuned against a frame-perfect player (yourself).
+- **Telegraph, then require.** Fast games stay fair by relying on PREDICTION: give a readable wind-up so the player acts on anticipation, not on a sub-reaction-time window. Difficulty should come from planning/prediction pressure, not from beating the reaction-time floor.
+
+**The self-check.** Before calling a level done, ask: could a HUMAN with ~250ms reaction clear this, relying on telegraphed anticipation rather than frame-perfect timing? If clearing it needs your exact scripted frames, widen the window or add telegraphing.
+
+## Visibility: the player must see the player
+
+If you `spr(n)` an entity, sprite n must actually be DRAWN (a non-empty sprite), or the entity is invisible and the game is unplayable however correct the logic. Prefer primitives (`circfill`, `rectfill`, `line`) for the player and key entities unless you have authored real sprites, primitives can never be an empty slot. The player, and every entity the player must track, must be visible and distinguishable on screen.
+
+## Readability and feedback
+
+The player must be able to READ the game state at a glance and get FEEDBACK for every action: what am I, what is a hazard, what is a goal, did my input register, did I score or get hit. Motion trails, colour contrast, a HUD, particles/shake/sfx on events, these are not polish for its own sake, they are how the player perceives the state they must act on.
+
+## Difficulty curve and progression
+
+A good game GOES SOMEWHERE: it escalates. Ramp difficulty by introducing or combining MECHANICS (a new hazard type, a new interaction) over the playthrough, not merely by piling more of the same obstacle. More-of-the-same reads as samey and does not deepen; a new wrinkle does. Aim for a difficulty ARC with a satisfying peak, not a flat loop. Keep the first contact with each new mechanic gentle enough to learn it before it is tested under pressure.
+
+Progression can take MANY FORMS, a ladder from cheapest to richest:
+
+1. **A difficulty ramp within one loop** (speed / spawn rate / hazard density rises as you play) — the smallest way to "go somewhere".
+2. **Escalating waves / rounds** (new hazard TYPES arrive in later waves, not just more) — deepens one screen without new scenes.
+3. **Discrete levels / stages** (hand-built rooms, each teaching or combining a mechanic) — a real authored arc.
+4. **Worlds / acts** (sustained progression across many levels, new mechanics unlocking) — the top of the ladder.
+
+Each rung "goes somewhere" more than the one below; each also costs more to build and finish. WHICH rung a given game should reach is not universal, it depends on how much you can build and FINISH (a rough over-reach loses to a finished smaller arc). Pick the highest rung you can complete well.
+
+## Originality: a method, not a menu
+
+Novelty is a real design quality and it is the axis judges cap hardest. But it cannot be handed to you as a list of mechanics, if it were, every game would converge on the same listed idea and it would be the list-writer's creativity, not yours. So this section teaches a METHOD to GENERATE and then TEST your own idea. It deliberately lists NO example mechanics. (If you are editing this skill: do not add concrete example mechanics here. A listed lever becomes the answer every agent copies, run after run, the exact trap this framing exists to avoid.)
+
+**Interrogate your idea (questions to ask about YOUR idea, not answers to copy):**
+
+- What is the OBVIOUS version of this theme, the first thing anyone would build? (Name it, so you can avoid it.)
+- Could you SUBVERT the expectation the theme sets, rather than meet it?
+- Could you INVERT the role, act on the world instead of the avatar, or control the thing usually controlled against you?
+- Could the CONSTRAINT itself become the mechanic, rather than a limit you work around?
+- Could two unrelated ideas COMBINE into something neither is alone?
+- Could you RECONTEXTUALISE a familiar mechanic into a setting that changes its meaning?
+
+**The self-check (load-bearing).** Before you commit to an idea: name the obvious version of this theme; is your idea just that with a reskin? If a judge (or player) has almost certainly seen this exact game before, go again. Commit only to an idea that passes this check, then build it well, a fresh idea executed roughly beats a stale idea executed perfectly.

package/src/skills/game-jam/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: game-jam
+description: Build a complete, original, playable PICO-8 game against a deadline and a theme. Use for a game jam, a timed game-build, or a jam benchmark run. Carries the clock discipline; applies the universal design principles via game-design-reference.
+---
+
+# game jam
+
+A jam is building a GOOD game (the universal part) UNDER A CLOCK and to a THEME (the jam part). This skill carries only the jam-specific part; the design principles live in `game-design-reference`.
+
+**FIRST STEP, before anything else: use the `read` tool to LOAD AND FOLLOW `game-design-reference` (`../game-design-reference/SKILL.md`, resolved against THIS skill's directory).** It is the shared body of universal design principles (fairness / no dead state, human reaction budget, visibility, readability, difficulty curve, and the originality method) that you apply throughout the jam. This skill does not repeat them; it tells you the calls they force when you are racing a clock, so you need the reference open to make those calls. Do not skip this read: the fairness and reaction-budget self-checks live there, and they are exactly what a jam entry gets wrong. Then use the picopilot loop skills as you go: `picopilot-overview` (the `#include` layout + verify loop), `picopilot-code` (the token budget), `picopilot-art` / `picopilot-audio` (assets), and `picopilot-debug` (run + playtest, your eyes on the running game).
+
+## Interpret the theme yourself
+
+The theme is a seed, not a brief. YOU interpret it into a game. Run `game-design-reference`'s originality method and self-check on the bare theme and commit to your OWN idea, do not wait to be told what to build, and do not settle for the obvious version. This is where the jam is won or lost: a fresh, well-chosen idea sets your ceiling.
+
+## The clock: slice, deepen, triage
+
+Three phases you map onto whatever time budget you are given, not a rigid schedule:
+
+- **SLICE (first third).** Get to a PLAYABLE slice fast. A playable slice = it boots, responds to input (the button actually changes what happens), and has a goal with a win/lose, and `verify` is green. Scope tiny: one screen, one mechanic, one goal. A rough playable game scores; a broken ambitious one scores zero.
+- **DEEPEN (middle).** Once the slice works, spend the BULK of your remaining time making the game DEEPER (go somewhere), not just more finished. Reach UP the progression ladder (`game-design-reference`: difficulty ramp -> escalating waves -> levels/stages -> worlds) as far as your budget can FINISH. Polish (juice, audio, extra feedback) is worth some time but is NOT the main use of a long budget: a short game buffed to a shine still under-uses the clock. Deepening and polishing both stay gated behind a green `verify`, playable at every checkpoint.
+- **TRIAGE (last stretch).** Stop adding features. Confirm it boots and is playable, finalise the writeup. But "stop adding features" is NOT "stop improving": if you have found a real design DEFECT (below), fixing it beats holding, and beats gold-plating. Do not idle a proven build if it still has a fairness or playability flaw.
+
+## Scale your ambition to the clock
+
+The RIGHT size of game depends on the time you are given, and you know your budget from the brief. Match your ambition to it:
+
+- **Short clock** (minutes): one screen, one mechanic; deepen via a difficulty ramp or a few escalating waves. Levels would over-reach and ship broken. Getting a tight, finished, fair slice IS the win.
+- **Long clock** (an hour-plus, a day, more): a playable slice in the first third is just the beginning. Then reach real progression, hand-built levels, unlocking mechanics, an authored difficulty arc, a bigger, deeper game. Idling a proven short game or only polishing it WASTES the budget; more time should buy more GAME.
+
+Never over-reach past what you can FINISH: a rough, unfinished big game loses to a finished smaller arc. Pick the highest rung of the ladder you can complete well, and let the clock, not a fixed template, decide which rung that is. YOU choose the form (ramp / waves / levels / worlds) that fits your idea and your time.
+
+## The design calls the clock forces
+
+When you find one of these under time pressure, this is the jam-time decision (the principle is in `game-design-reference`):
+
+- **A dead state (unfair forced-loss).** You found a spot where the player has no non-losing move. FIX IT even late: a dead state tanks the playability/fairness a judge and a player feel far more than a missing feature costs. This outranks polish.
+- **A superhuman level (frame-perfect tuning).** You tuned a level against your own frame-perfect `--input` scripts and only YOU can clear it. Budget a reaction margin (widen the window, add telegraphing) before you call it done. If a human with ~250ms reaction cannot clear it, it is not done, it is broken.
+- **An invisible entity.** You `spr()` something that is an empty slot, or the player cannot tell player from hazard from goal. Fix visibility/readability before anything else; an unreadable game is unplayable.
+
+Do not declare "done, holding" while any of these is unfixed. The plateau trap is stopping because you cannot SEE what to improve, run the `game-design-reference` self-checks (fairness: test hazard-avoidability from every rest state, not just reachability; reaction: could a human clear this) precisely to find the work that remains.
+
+## Finish
+
+At the deadline you ship: a playable `main.p8` (boots, responds, has win/lose, `verify` green) and a short `JAM.md` (theme interpretation, the mechanic, controls, and the honest calls you made under the clock). A rough playable game with a fresh idea beats a broken ambitious one, every time.

package/src/skills/picopilot-art/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: picopilot-art
+description: Edit and JUDGE PICO-8 sprites with picopilot. The char-grid edit surface, the rendered-PNG judge surface, the render to look, set to fix, render again loop, and the non-multimodal fallback for models that cannot read images. Also the gfx/map overlap smart-refuse. Use when editing __gfx__ sprites.
+---
+
+# picopilot art
+
+Sprites live in the cart as hex blobs you cannot read. picopilot gives you two
+distinct surfaces so you can both EDIT precisely and JUDGE honestly. (See
+`picopilot-overview` for the `#include` discipline; never hand-edit `__gfx__`.)
+
+## Two surfaces: the char grid (edit) and the PNG (judge)
+
+- **Char grid** (`picopilot gfx show <sprite>` / `gfx set <sprite>`): a per-pixel
+  hex grid, `.` = transparent, `0-F` = the 16 fixed PICO-8 colours. This maps 1:1
+  to `__gfx__` and is your EXACT, round-trippable EDIT surface. It is the
+  SVG-for-pixels source you change.
+- **Rendered PNG** (`picopilot gfx render <sprite|sheet>`): an upscaled,
+  true-16-colour PNG written to a known path. This is the JUDGE surface: it is
+  how you tell whether the sprite READS as intended.
+
+You need both, because coding models generate structured visual source (a grid,
+like SVG) well but read it back poorly for gestalt and colour. Edit on the grid;
+judge on the PNG.
+
+## The art loop: render → look → set → render
+
+1. `picopilot gfx render <sprite>`: produce the PNG (and get the grid).
+2. LOOK at it, then
+3. `picopilot gfx set <sprite>`: fix pixels on the char grid.
+4. `picopilot gfx render <sprite>`: re-render and look again.
+
+These steps are wired as CTAs, so follow the suggested next command.
+
+## The non-multimodal fallback (load-bearing)
+
+The tool ALWAYS emits both the PNG path AND the char grid, because whether you
+can read an image is YOUR capability, not something picopilot can detect.
+
+- If you CAN read images: open the `gfx render` PNG and judge the pixels there.
+- If you CANNOT read images: do NOT pretend to. Fall back to reasoning over the
+  `gfx show` grid, read the hex nibbles row by row, reconstruct the shape and
+  colours in your head, and judge from that. The eyes-loop degrades honestly to
+  the grid rather than to guessing.
+
+## gfx/map overlap: the smart-refuse
+
+Sprites 128..255 (`0x1000`-`0x1fff`) ALIAS `__map__` rows 32..63, the SAME
+memory. Writing such a sprite can clobber real map tiles you cannot see.
+
+`picopilot gfx set` inspects the overlapping map region:
+
+- overlap empty/all-zero, or overlap authorised: the write succeeds (the result
+  notes the aliasing).
+- real map tiles at risk AND nothing authorised the loss: it REFUSES with a
+  structured `map-overlap` result and a nonzero exit, and leaves `__map__`
+  UNCHANGED. This is not a warning you may ignore; it is a stop.
+
+To authorise overlap deliberately, pass `--allow-map-overlap` on the command or
+set `allowMapOverlap: true` in `picopilot.json`. Or just use sprites 0..127,
+which are gfx-only. The one guaranteed invariant: picopilot never SILENTLY
+overwrites existing map tiles.

package/src/skills/picopilot-audio/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: picopilot-audio
+description: Compose PICO-8 sound as text with picopilot. The #1 reframe (no tempo, compose in TRACKER ROWS at one speed), the picopilot-MML grammar (waveform/volume/effect per note + the 5 SFX filters for designed sounds like explosion/engine/pad), structural music assembly from SFX references, the loud refusals, and the compose to hear ears loop. Use when authoring __sfx__ / __music__.
+---
+
+# picopilot audio
+
+SFX and music live in the cart as hex blobs you cannot read. picopilot lets you
+compose sound as TEXT you can reason about, then transpiles it into `__sfx__` /
+`__music__`. (See `picopilot-overview` for the `#include` discipline; never
+hand-write the audio hex.) The exact byte layout + the full grammar/mapping
+tables are the canonical reference in
+`work/notes/findings/pico8-audio-sfx-music-layout-and-mml-subset.md` (Part A =
+layout, Part B = the picopilot-MML grammar + mapping). This skill carries what a
+model gets WRONG, not the whole finding.
+
+## Read this first: no tempo, compose in TRACKER ROWS (ADR-0008)
+
+The one thing a model gets wrong: it reaches for sheet music. PICO-8 has NO
+per-note duration and NO tempo/BPM. An SFX is a column of up to 32 tracker ROWS,
+and ALL rows share ONE SFX `speed` (ticks/row, set with `s<N>`). So a
+picopilot-MML length is a ROW COUNT, not a musical note value: `c4` = the note C
+held for 4 ROWS (emitted as the note plus 3 tie rows), NOT a quarter note. There
+is no tempo token; a tempo-style input is refused with a clear message, not
+guessed at. Consequences you must design around:
+
+- **No true sustain across rows.** A held note is RE-STRUCK each following row
+  (PICO-8 has no cross-row sustain bit). For a smooth hold use effect `e1`
+  (slide) or a low `s<N>` speed, not a long length. Do not expect a legato tie.
+- **Dotted notes round to whole rows.** `c4.` = 6 rows; a fractional result
+  rounds to the nearest whole row and the result WARNS. Rows are integers.
+- **32-row hard cap.** A melody past 32 rows is refused (see below). Splitting it
+  into several SFX arranged by a music pattern is a STRUCTURAL choice YOU make,
+  not something the transpiler does silently.
+
+## The ears loop: `sfx from-mml` -> `music from-patterns` -> `audio render`
+
+This is the audio analogue of the `picopilot-art` render/look/set eyes loop:
+
+1. `picopilot sfx from-mml <slot> "<mml>"`: compose one sound as text.
+2. `picopilot music from-patterns "<json>"`: arrange SFX into a song.
+3. `picopilot audio render`: RECORD a WAV and HEAR it, then iterate.
+
+These steps are wired as CTAs (a merged SFX or song points you at `verify` then
+`audio render`), so follow the suggested next command.
+
+## `audio render` / `audio record`: get a WAV by RECORDING (ADR-0009)
+
+PICO-8 has NO working offline WAV export (it SIGFPEs upstream), so picopilot gets
+audio-to-WAV the only way that works: by RECORDING a running session
+(`extcmd("audio_rec")`/`audio_end`). Two commands, both PICO-8-gated and both
+REAL-TIME recordings that need a real audio+video session (a developer machine,
+NOT headless CI), NOT deterministic offline exports:
+
+- **`picopilot audio render`** injects a THROWAWAY play-harness for a chosen
+  target and records it, so you write NO playback code. Pick the target with
+  `--sfx <n>` (one SFX slot), `--pattern <p>` (one music pattern), or NEITHER
+  (the whole song, `music 0`). The record window is derived from an `--sfx`
+  target's speed+rows; override any target with `--seconds <n>`. An empty slot or
+  out-of-range target is REFUSED loudly (nothing to render), never a silent
+  recording of silence.
+- **`picopilot audio record <cart>`** records the cart's OWN playback (it keeps
+  the cart's code and appends a cooperative recorder); use it to capture a whole
+  run's audio. `picopilot run --record-audio` does the same alongside a normal
+  `run` (a WAV next to the screenshots).
+
+The WAV goes to an isolated dir (`--wav-dir`, default a temp dir), never
+`~/Desktop` or the carts root (the `audio_end(1)`-saves-to-the-current-folder
+trap; picopilot steers it with PICO-8's `root_path`). PICO-8 absent -> a
+structured `pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`), never a
+crash. On a headless machine the recording succeeds but captures NO audio
+(`captured:false` + a nudge to run on a machine with a display + audio device):
+that is honest, not a failure of the recipe.
+
+## `sfx from-mml`: one MML string -> one SFX slot
+
+`picopilot sfx from-mml <slot> "<mml>"` transpiles picopilot-MML into one
+`__sfx__` slot (`0-63`) and merges it (only that slot changes; every other
+section stays byte-identical). Cart is `--cart` (default `main.p8`); pass a
+longer source with `--file` (give EITHER the argument OR `--file`).
+
+Write notes AND their waveform/volume/effect in MML: that is exactly the
+information PICO-8 needs and hand-written hex hides. This is why picopilot-MML,
+not ABC: ABC is score-level and cannot name a per-note waveform, volume, or
+effect, so an ABC-authored SFX is timbre-less ("blind audio in a nicer font").
+
+### The picopilot-MML grammar in brief
+
+Modal state (sticky until changed): `@<0-7>` waveform (`@8`-`@f` = SFX 0-7 as a
+custom instrument), `v<0-7>` volume, `e<0-7>` effect (0 none, 1 slide, 2 vibrato,
+3 drop, 4 fade in, 5 fade out, 6 arpeggio fast, 7 arpeggio slow), `o<0-5>` octave
+(default `o2`), `l<N>` default length in rows, `>`/`<` octave shift. A bare note
+(`c d e f g a b`, `+`/`#` sharp, `-` flat) emits one row in the current state.
+`r<N>` = N silent rows; `^<N>` extends the previous note; `s<N>` = SFX speed
+(default `s16`); `{`/`}` = loop markers (a LONE `{` marks the pattern LEN, the
+finding's LEN special case). SFX-level FILTERS (per-SFX, order-free): `!dampen`/
+`!dampen2`, `!reverb`, `!noiz`, `!buzz`, `!detune1`/`!detune2` (see the filters
+section below). Whitespace + `|` bars are cosmetic. See finding Part B / A.7 for
+the full tables.
+
+Note `e` is BOTH a note letter AND the effect prefix: `e0`-`e7` is the EFFECT; a
+bare `e` is note E (hold it with `l4 e`, not `e4`). Effects have NO letter
+mnemonics (the finding's `sl`/`vb`/... sugar did NOT ship: each collides with a
+real note-plus-length sequence); use the numeric `e0`-`e7`.
+
+Example: `picopilot sfx from-mml 0 "s8 @3 v6 e2 c e g > c"` is a square-wave
+(`@3`) vibrato (`e2`) arpeggio at speed 8.
+
+### SFX FILTERS: how to reach DESIGNED sounds (explosion, engine, pad)
+
+Pitch + waveform + volume + effect get you notes; the 5 per-SFX FILTERS are what
+make a sound DESIGNED. They are `!`-prefixed SFX-level directives (per-SFX like
+`s<N>`, place them anywhere in the string, order-free): they set the SFX's first
+header byte and change nothing per-note. Use them when a boom reads as a
+machine-gun rattle, or an engine as a buzz: no amount of pitch/volume MML can
+synthesize the low BODY or resonant TAIL, only these filters can.
+
+- **`!dampen` / `!dampen2`** — a low-pass at 2 levels. This is the BODY/weight:
+  turns raw `@6` noise from a hiss/rattle into a "boom". `!dampen2` is heavier.
+  The single biggest lever for an explosion.
+- **`!reverb`** — an echo/tail. The resonant TAIL that makes a boom ring out (and
+  a pad bloom). On/off (a single switch, see the caveat below).
+- **`!noiz`** — pure white-noise texture; applies ONLY to instrument 6 (`@6`), a
+  no-op on any other waveform. The noise character under an explosion.
+- **`!buzz`** — a buzzier alteration (all waveforms). With `@6` + `!buzz` and NOIZ
+  off you get brown noise.
+- **`!detune1`** (flange, second detuned voice) / **`!detune2`** (a voice tuned up
+  ~an octave) — thickness for a lead or pad. `!detune` needs an explicit 1 or 2.
+
+The canonical DESIGNED explosion: `!dampen2 !reverb @6` over a descending pitch
+sweep + volume decay, e.g.
+`picopilot sfx from-mml 3 "s6 !dampen2 !reverb @6 o3 v7 g o1 c o0 g v6 e v5 c v4 g v3 c v2 g v1 c"`.
+Strip the two filters and the SAME notes read as a descending zap / rattle: the
+filters are the tool gap the audio dogfood surfaced (they set header byte `e0`).
+
+CAVEAT (finding A.7): the filter byte layout was decoded byte-for-byte on PICO-8
+v0.2.7, but the byte has no non-colliding room for a REVERB level 2 under the
+verified layout, so picopilot exposes `!reverb` as a single on/off switch (DAMPEN
+keeps its 2 levels). A bad level (`!dampen3`, `!noiz2`, `!reverb2`, `!detune`
+without 1/2) is a loud `audio-mml-filter-level-out-of-range` refusal, not a clamp.
+
+## `music from-patterns`: structural, NOT a notation
+
+`__music__` holds NO melody: melody lives entirely in the referenced SFX. A song
+is an ORDERED LIST of up-to-4 SFX-channel references per pattern.
+`picopilot music from-patterns "<json>"` writes `__music__` (only `__music__`
+changes; `__sfx__` and every other section stay byte-identical). So author each
+voice as an SFX with `sfx from-mml`, THEN arrange the references here; you never
+write music in a melodic notation. Cart is `--cart` (default `main.p8`); longer
+songs via `--file`.
+
+### The pattern-list JSON
+
+An array of patterns, each
+`{"channels":[c0,c1,c2,c3], "loopStart"?, "loopBack"?, "stop"?}`. Pattern order =
+song order. A channel is an SFX index `0-63`, OR `null` = OFF (silent this
+pattern). **`null` is NOT `sfx 0`**: `null` sets the channel's off bit; `0` is a
+real, playing SFX. Keep them distinct. The 3 flow flags (optional, default
+false): `loopStart`, `loopBack` (jump back to the loop-start pattern at this
+pattern's end), `stop` (music stops after this pattern); they combine. A
+`loopBack` with NO `loopStart` anywhere is allowed but WARNS (PICO-8 falls back
+to pattern 0).
+
+Example: `[{"channels":[0,1,null,3],"loopStart":true},{"channels":[0,1,null,3],"loopBack":true}]`
+is a 2-pattern loop whose channel 2 is silent.
+
+**Pattern length is INHERITED from the SFX, not stored here.** PICO-8 ends a
+pattern when its LEFT-MOST non-looping channel's SFX finishes, so pattern timing
+comes from the referenced SFX (its `speed` + LEN). To change how long a pattern
+plays, change the referenced SFX, not the music.
+
+## The two refusals: loud, never clamped
+
+Both stop you with a structured error + nonzero exit (no bytes change on a
+refusal) so a refusal is ACTIONABLE, not a dead end:
+
+- **`audio-mml-pitch-out-of-range`** (`sfx from-mml`): a note fell below C0 or
+  above D#5 (`0-63`). PICO-8 has no notes outside that range. Fix: TRANSPOSE, pick
+  an octave (`o0`-`o5`) that keeps every note in range, rather than transposing
+  off the keyboard.
+- **`audio-mml-sfx-overflow`** (`sfx from-mml`): more than 32 rows. Fix: SPLIT the
+  melody across multiple SFX slots yourself, then arrange them with
+  `music from-patterns`.
+- **`audio-mml-filter-level-out-of-range`** (`sfx from-mml`): a filter level PICO-8
+  does not have (`!dampen3`, `!reverb2`, `!noiz2`, or `!detune` without a mode).
+  Fix: `!dampen` has levels 1-2 (`!dampen`/`!dampen2`); `!reverb`/`!noiz`/`!buzz`
+  are on/off; `!detune` needs `!detune1` (flange) or `!detune2` (octave).
+
+Related: `music from-patterns` refuses an out-of-range SFX index with
+`audio-music-sfx-out-of-range` (to silence a channel use `null`, not an
+out-of-range number); a malformed JSON payload is `audio-music-parse-error`. And
+`audio render`/`audio record` require PICO-8, so they return a structured
+`pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`) when absent, never
+a crash. The text authoring + transpile steps need neither PICO-8 nor shrinko.

package/src/skills/picopilot-code/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: picopilot-code
+description: Write low-token PICO-8 Lua and stay under the 8,192-token budget. How to read picopilot tokens output, the PICO-8 shorthands that reclaim budget, and how minify (safe-only) and verify fit the loop. Use when writing or shrinking cart Lua.
+---
+
+# picopilot code
+
+The #1 way an agent fails at PICO-8 is token bloat: verbose Lua silently blows
+past the 8,192-token budget and the cart will not load. picopilot's job here is
+to make the budget visible and cheap to fix. (See `picopilot-overview` for the
+`#include` discipline: you edit `main.lua`, never the `.p8` binary sections.)
+
+## Read the token breakdown every iteration
+
+Run `picopilot tokens` after each change. It reports:
+
+- `tokens` and `pct`: the count and its percentage of the 8,192 budget.
+- `overBudget`: true when you are over 8,192 (the cart will not load).
+- `chars` and `compressed`: size, not the load-bearing limit; tokens are.
+
+When you are over budget, the result CTAs you to `picopilot minify`. Treat the
+token count as the number to drive down, not something to check once.
+
+If shrinko is not installed, `tokens` returns a structured `shrinko-not-found`
+result (nonzero exit) with the exact remedy `uv pip install shrinko`. That is not
+a crash; install shrinko and re-run.
+
+## Token discipline (write cheap Lua the first time)
+
+Models blow the budget by writing verbose Lua. Prefer PICO-8 shorthands:
+
+- `?` for `print`.
+- inline if: `if(c) x=1` instead of `if c then x=1 end`.
+- compound assignment: `+=`, `-=`, `*=`, `/=`.
+- `\` for integer divide.
+- reuse locals; avoid needless globals; fold repeated expressions into one local.
+
+## Reclaim budget with minify (safe-only)
+
+`picopilot minify` runs SAFE minification by default and reports the before/after
+token delta. Safe-only never changes behaviour, so it is the first move when over
+budget. Aggressive minification is never silent; if it is ever offered it is an
+explicit opt-in.
+
+## Gate it
+
+`picopilot verify` is the single static acceptance gate: tokens + integrity, no
+run. A green verify is well-formed, not proven-to-run, so it points you at
+`picopilot run`. With shrinko absent, verify is `gate-incapable` (never green),
+because it cannot check token bloat, the failure this loop exists to catch.
+
+## PICO-8 gotchas that break carts silently
+
+These are NOT token issues; they are behaviours that differ from mainstream Lua
+/ math and make a cart compile-and-run-but-behave-wrong. The ones models get
+wrong most:
+
+- `sin(t)`/`cos(t)` take TURNS (0..1), not radians, and `sin` is INVERTED for
+  screen space (+y is down). A full circle is `t: 0->1`. Do not multiply by
+  `2*pi`; do not re-negate `sin`.
+- `/` does NOT truncate (`5/2` is `2.5`). Integer divide is `\` (`5\2` is `2`),
+  which floors toward negative infinity (`-5\2` is `-3`).
+- `rnd(x)` returns a FLOAT in `[0,x)`. Wrap with `flr` for an integer
+  (`flr(rnd(6))` is 0..5). `rnd(table)` returns a random element.
+- Tables are 1-BASED. `del(t,val)` removes by VALUE; `deli(t,i)` removes by
+  INDEX. Deleting the current item inside `foreach` is safe; deleting inside an
+  ascending `for i=1,#t` loop ERRORS once the list shrinks (iterate descending).
+- Draw state PERSISTS across frames: `camera`, `pal`, `palt`, `clip`, `color`,
+  `fillp` stay set until you reset them (no-arg form: `camera()`, `pal()`).
+  Reset before drawing the HUD or offsets/palette swaps leak.
+- Variables are GLOBAL unless declared `local`. The `x = cond and a or b` ternary
+  returns `b` when `a` is falsy; use an explicit `if` when `a` can be `false`/`nil`.
+
+## Data-as-split-strings (a top token-saver)
+
+`split"a,b,c"` turns a comma string into a 1-based array in one cheap token.
+Declare frames, hitboxes, direction lookups, and whole level rows this way
+instead of table literals. `unpack(split"...")` spreads it as a vararg (e.g.
+`poke(addr, unpack(split"..."))` writes a byte blob in one call). Prefer it for
+any homogeneous list.
+
+## Genre code references (load the one you need)
+
+The right STRUCTURE differs by game type: a platformer's gravity + per-axis
+collision is nothing like a grid puzzle's transactional tile-step or a shooter's
+entity swarm. When you start building a specific genre, load the matching file
+from this skill's `reference/` folder (see `reference/README.md` for the index):
+
+- `reference/platformer.md`: gravity/jump, per-axis tile collision, camera follow.
+- `reference/puzzle-grid.md`: grid state, discrete tile-step moves, rule passes.
+- `reference/twin-stick-arcade.md`: many entities, spawn/despawn at scale, juice.
+- `reference/top-down-adventure.md`: tiled world, 4-dir movement, tile interaction.
+- `reference/mode7-racing.md`: pseudo-3D `tline` floor projection, driving.
+- `reference/rpg-menus-dialog.md`: UI state stack, cursor menus, timed text reveal.
+
+Each carries a minimal idiomatic implementation and a genre-pitfalls checklist.
+Adapt them to your game.

package/src/skills/picopilot-code/reference/README.md

@@ -0,0 +1,42 @@
+# PICO-8 game-type code references
+
+Per-genre reference implementations for PICO-8 carts. The right structure for a
+platformer is not the right structure for a puzzle game, so pick the file that
+matches what you are building and load it on demand. These are minimal
+implementations written in idiomatic, token-cheap PICO-8 Lua (see the
+`picopilot-code` SKILL for the token discipline they follow). They teach the
+STRUCTURE and the genre-specific pitfalls; adapt them to your game.
+
+Load the ONE that matches your game:
+
+- `platformer.md`: side-view gravity/jump, per-axis tile collision, camera
+  follow.
+- `puzzle-grid.md`: a grid of cells, discrete tile-by-tile movement, rule
+  evaluation, no physics.
+- `twin-stick-arcade.md`: many entities at once (bullets, enemies, particles),
+  spawn/despawn at scale, screen juice.
+- `top-down-adventure.md`: walk a tiled world, room/map streaming, 4-direction
+  movement and facing, interact with tiles.
+- `mode7-racing.md`: pseudo-3D projected floor via `tline`, per-scanline
+  perspective, heading-based driving.
+- `rpg-menus-dialog.md`: UI state STACK, cursor menus, timed text reveal,
+  turn-based battle menus.
+
+Cross-cutting truths that apply to ALL genres live in the always-loaded
+`AGENTS.md` (palette, memory map, the loop) and in this skill's other sections
+(token budget). The genre files assume you already know those.
+
+## Idioms every genre file relies on (quick recap)
+
+- `add(list,obj)` / `del(list,obj)` / `deli(list,i)` for entity lists. Deleting
+  the CURRENT item inside `foreach` is safe; deleting inside an ASCENDING numeric
+  `for i=1,#list` loop is NOT (it errors once the list shrinks). Iterate a
+  descending loop or `foreach` when you delete while iterating.
+- `split"a,b,c"` turns a comma string into a 1-based array in one cheap token;
+  it is the cheap way to declare data tables (frames, hitboxes, level rows).
+- `sin(t)`/`cos(t)` take TURNS (0..1), not radians, and `sin` is INVERTED for
+  screen space (+y is down). A full circle is `t: 0->1`.
+- `mid(lo,x,hi)` is the idiomatic clamp.
+- Draw state (`camera`, `pal`, `palt`, `clip`, `color`, `fillp`) PERSISTS across
+  frames and calls. Reset with the no-arg form (`camera()`, `pal()`) before
+  drawing the HUD, or it leaks.

package/src/skills/picopilot-code/reference/mode7-racing.md

@@ -0,0 +1,95 @@
+# Mode-7 / pseudo-3D racing reference (tline floor projection)
+
+Structure for a pseudo-3D game with a projected ground plane (arcade racer,
+first-person floor). PICO-8 has no real 3D; you FAKE it by drawing the map as a
+perspective-warped floor with `tline` (textured line), one horizontal scanline at
+a time, each sampling the map further away as it climbs toward the horizon. This
+is structurally unlike every other genre here: there are no entity-vs-tile
+collisions in world pixels, the "world" is a texture you sample.
+
+## The load-bearing rules
+
+1. Draw the floor BOTTOM-UP: for each screen row `py` from the horizon down to the
+   bottom, compute how far into the world that row is, and `tline` one row of the
+   map at that depth. Rows near the bottom are close (map moves fast); rows near
+   the horizon are far (map moves slowly).
+2. `tline(x0,y0,x1,y1, u,v, du,dv)` draws screen pixels `x0,y0..x1,y1` sampling the
+   MAP starting at map-coord `(u,v)` and stepping `(du,dv)` per pixel. The scale
+   (how much world per screen pixel) is what creates perspective: bigger step near
+   the bottom, smaller near the horizon.
+3. Rotation uses `sin`/`cos` in TURNS (0..1). The camera angle rotates the `(du,dv)`
+   sampling basis; do NOT feed radians.
+4. This is CPU-heavy. Keep it to the floor; draw sprites (player, opponents) on top
+   with normal `spr`, scaled by their distance.
+
+## Minimal floor projection
+
+```lua
+-- camera: world pos (cx,cy), heading angle (ang, in TURNS), height above floor
+cam={x=0,y=0,ang=0,h=16}
+horizon=48   -- screen row where the floor starts (sky above)
+
+function draw_floor()
+ local ca,sa=cos(cam.ang),sin(cam.ang)
+ for py=horizon,127 do
+  -- depth: how far this scanline is into the world. Rows just below the horizon
+  -- are very far (large scale); rows at the bottom are near. This 1/(py-horizon)
+  -- shape is the perspective.
+  local d=cam.h/(py-horizon+1)          -- world distance for this row
+  local scale=d/64                       -- world units per screen pixel
+  -- the world point at the CENTER of this scanline, then the left/right ends
+  local wx=cam.x + d*ca
+  local wy=cam.y + d*sa
+  -- sampling basis perpendicular to heading, scaled by depth
+  local du= sa*scale
+  local dv=-ca*scale
+  -- start at the left screen edge: back off 64 pixels along the basis
+  local u=wx - du*64
+  local v=wy - dv*64
+  tline(0,py,127,py, u,v, du,dv)         -- one textured scanline of the map
+ end
+end
+```
+
+Tune `horizon`, `cam.h`, and the `d`/`scale` constants to taste; the exact numbers
+depend on your track's map scale. The SHAPE (1/row depth, perpendicular basis from
+`sin`/`cos`, `tline` per row) is what matters.
+
+## Driving (heading + speed, no tile collision in the usual sense)
+
+```lua
+speed=0
+function update_car()
+ if btn(2) then speed=min(speed+0.1,4) end   -- accelerate
+ if btn(3) then speed=max(speed-0.1,0) end   -- brake
+ if btn(0) then cam.ang-=0.005*speed end     -- steer (turn amount scales w/ speed)
+ if btn(1) then cam.ang+=0.005*speed end
+ -- move along heading (TURNS: cos/sin)
+ cam.x+=cos(cam.ang)*speed
+ cam.y+=sin(cam.ang)*speed
+end
+```
+
+Off-track detection reads the map tile under the car (`mget(cam.x\8, cam.y\8)`) and
+slows the car, rather than blocking movement like a platformer wall.
+
+## Draw order
+
+```lua
+function _draw()
+ cls(12)          -- sky
+ draw_floor()     -- projected map
+ draw_opponents() -- spr, scaled by distance, sorted far-to-near
+ draw_hud()       -- speed, lap; camera is not offset here (floor is drawn directly)
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Floor drawn per-scanline with `tline`, horizon down to row 127.
+- [ ] Depth uses a 1/(row) shape so far rows compress toward the horizon.
+- [ ] Rotation via `sin`/`cos` in TURNS; sampling basis is perpendicular to heading.
+- [ ] It is CPU-heavy: profile with `picopilot run`, keep the floor loop tight,
+      consider `_update60`->`_update` (30fps) if it cannot keep up.
+- [ ] Sprites drawn on top, scaled and sorted by distance, NOT via the floor.
+- [ ] Off-track is a tile lookup that slows you, not a solid-wall collision.