picopilot 0.0.0 → 0.1.0

package/src/skills/picopilot-code/reference/puzzle-grid.md

@@ -0,0 +1,106 @@
+# Puzzle / grid reference (discrete cells, tile-step movement, rules)
+
+Structure for a grid puzzle (block-pushing, rule-based, or match games). The
+world is a 2D array of CELLS, the player moves ONE cell per input (not by
+velocity), and a
+turn is: read intent, test the move against rules, commit if legal. There is no
+gravity and no sub-pixel motion here; do NOT reach for the platformer shape.
+
+## The load-bearing rules
+
+1. State is a GRID, not a pixel position. Store `col,row` (integers), render by
+   multiplying by 8 (`x=col*8`). Movement changes `col,row` by exactly +/-1.
+2. Input is DISCRETE: use `btnp` (fires once per press), never `btn` (fires every
+   frame = the player rockets across the board).
+3. A move is a TRANSACTION: compute the target cell, check every rule (in bounds?
+   wall? pushable block that itself can move?), and only then mutate the grid.
+   Never move first and undo, it corrupts multi-object pushes.
+4. Grids are 1-based in Lua. Guard bounds explicitly (`c>=1 and c<=cols`).
+
+## Grid setup (rows as split strings = cheap + readable levels)
+
+```lua
+cols,rows=16,16
+-- a level as one string per row: .=floor #=wall @=player $=box
+level=split("################, #@.....#......#, #..$..........#, ...(more rows)...", ",")
+
+grid={}          -- grid[r][c] = tile char
+player={c=2,r=2}
+
+function load_level()
+ grid={}
+ for r=1,rows do
+  grid[r]={}
+  local row=level[r]
+  for c=1,cols do
+   local ch=sub(row,c,c)
+   grid[r][c]=ch
+   if ch=="@" then player.c,player.r=c,r grid[r][c]="." end
+  end
+ end
+end
+```
+
+## Discrete move as a transaction (with box-push)
+
+```lua
+-- dir -> delta. split pairs are the idiomatic lookup.
+dc=split"0,0,-1,1"   -- up,down,left,right dx (matches btnp 2,3,0,1 order below)
+dr=split"-1,1,0,0"
+
+function cell(c,r) -- safe read; out of bounds reads as wall
+ if c<1 or c>cols or r<1 or r>rows then return "#" end
+ return grid[r][c]
+end
+
+function try_move(dx,dy)
+ local nc,nr=player.c+dx,player.r+dy
+ local t=cell(nc,nr)
+ if t=="#" then return end          -- wall: no move
+ if t=="$" then                     -- box: can it be pushed one further?
+  local bc,br=nc+dx,nr+dy
+  if cell(bc,br)~="." then return end  -- blocked behind: whole move illegal
+  grid[br][bc]="$" grid[nr][nc]="."    -- commit the push
+ end
+ player.c,player.r=nc,nr            -- commit the player move
+end
+
+function _update()
+ -- btnp order: 0 left,1 right,2 up,3 down
+ if btnp(0) then try_move(-1,0) end
+ if btnp(1) then try_move(1,0) end
+ if btnp(2) then try_move(0,-1) end
+ if btnp(3) then try_move(0,1) end
+end
+```
+
+## Render (grid -> screen, cell*8)
+
+```lua
+function _draw()
+ cls(1)
+ for r=1,rows do for c=1,cols do
+  local t=grid[r][c]
+  if t=="#" then rectfill((c-1)*8,(r-1)*8,(c-1)*8+7,(r-1)*8+7,5)
+  elseif t=="$" then spr(2,(c-1)*8,(r-1)*8) end
+ end end
+ spr(1,(player.c-1)*8,(player.r-1)*8)   -- player
+end
+```
+
+## Win / rule evaluation
+
+Evaluate win AFTER a committed move, by scanning the grid (e.g. every box on a
+target). For a game where the RULES are themselves objects on the grid, the rule
+set is DATA you re-parse each turn (scan the grid for rule triples, rebuild a
+properties table), then movement/legality queries that table. Keep the rule pass
+separate from the move pass; do not interleave them.
+
+## Genre pitfalls checklist
+
+- [ ] Position is integer `col,row`, rendered as `*8`, not a pixel velocity.
+- [ ] Input uses `btnp`, not `btn`.
+- [ ] Moves are validated fully BEFORE any grid mutation (transaction).
+- [ ] Multi-object pushes check the space behind the pushed object.
+- [ ] Bounds guarded (1-based); out-of-bounds reads treated as wall.
+- [ ] Win/rule evaluation is a separate pass after the move commits.

package/src/skills/picopilot-code/reference/rpg-menus-dialog.md

@@ -0,0 +1,122 @@
+# RPG menus + dialog reference (UI state machines, text reveal)
+
+Structure for the menu/dialog side of an RPG or any UI-driven game (title menus,
+inventory, shop, dialog boxes, turn-based battle menus). The defining problem is
+NOT movement, it is a STACK of UI STATES, a cursor over a list of options, and
+text that reveals over time. Get the state stack and the cursor-wrap right; the
+"game feel" here is menu responsiveness and readable text pacing.
+
+## The load-bearing rules
+
+1. UI is a STACK of modes (`{"map"}` -> push `"menu"` -> push `"item"`). Input and
+   draw dispatch on the TOP of the stack. Opening a submenu PUSHES; canceling
+   (btnp 5 / X) POPS. This is cleaner than a flat `mode` string once menus nest.
+2. Menu input is DISCRETE: `btnp` only. A cursor is an index into an options list;
+   moving wraps with `%`. Confirm = btnp(4), cancel = btnp(5).
+3. Dialog text REVEALS over time (one char every few frames), not all at once.
+   Track a reveal counter; a confirm press either fast-forwards to full text or,
+   if already full, advances to the next line.
+4. Draw menus in SCREEN space. If the field behind is camera-offset, `camera()`
+   (reset) before drawing the box, or it slides with the world.
+
+## Mode stack + dispatch
+
+```lua
+stack={"field"}
+function top() return stack[#stack] end
+function push(m) add(stack,m) end
+function pop() if #stack>1 then deli(stack) end end   -- never pop the base mode
+
+function _update()
+ local m=top()
+ if m=="field" then
+  update_field()
+  if btnp(4) then push("menu") menu_cur=1 end
+ elseif m=="menu" then
+  update_menu()
+ elseif m=="dialog" then
+  update_dialog()
+ end
+end
+```
+
+## Cursor over a list, with wrap
+
+```lua
+menu_items=split"items,magic,status,save"   -- data as a split string
+menu_cur=1
+
+function update_menu()
+ -- up/down move the cursor, wrapping (1-based, so the %+1 dance)
+ if btnp(2) then menu_cur=(menu_cur-2)%#menu_items+1 end
+ if btnp(3) then menu_cur=menu_cur%#menu_items+1 end
+ if btnp(4) then choose(menu_items[menu_cur]) end   -- confirm
+ if btnp(5) then pop() end                          -- cancel closes the menu
+end
+
+function draw_menu()
+ camera()                       -- SCREEN space
+ rectfill(80,8,120,40,0) rect(80,8,120,40,7)
+ for i,it in ipairs(menu_items) do
+  local y=12+(i-1)*7
+  print(it,88,y, i==menu_cur and 7 or 5)
+  if i==menu_cur then print(">",83,y,7) end
+ end
+end
+```
+
+## Dialog with timed text reveal
+
+```lua
+dlg={text="",shown=0}
+function say(s) dlg.text=s dlg.shown=0 push("dialog") end
+
+function update_dialog()
+ if dlg.shown < #dlg.text then
+  dlg.shown+=0.5                       -- ~2 chars/frame; tune for pacing
+  if btnp(4) then dlg.shown=#dlg.text end  -- confirm fast-forwards to full
+ else
+  if btnp(4) then pop() end            -- fully shown: confirm closes/advances
+ end
+end
+
+function draw_dialog()
+ camera()
+ rectfill(4,100,123,123,1) rect(4,100,123,123,7)
+ print(sub(dlg.text,1,flr(dlg.shown)), 8,104, 7)  -- sub reveals up to `shown`
+end
+```
+
+(For multi-line/word-wrapped dialog, pre-split the text into lines that fit the box
+width and reveal line by line. `print` glyphs are ~4px wide, so ~28 chars per line
+in a full-width box.)
+
+## Turn-based battle menu (same primitives)
+
+A battle is the SAME machinery: a mode on the stack (`"battle"`), a cursor over
+actions (`Fight/Item/Run`), pushing a target-select submenu, then running the
+action and popping back. Keep the battle STATE (hp, turn order) separate from the
+MENU state (which option is highlighted); do not entangle them.
+
+## Coroutine for scripted sequences (optional)
+
+For a scripted intro / cutscene (text, then move a sprite, then more text), a
+coroutine reads far cleaner than a hand-rolled step counter:
+
+```lua
+function intro()
+ say("long ago...") yield_until_closed()
+ -- move the king sprite, wait, etc.
+ say("...a hero was needed.") yield_until_closed()
+end
+-- drive it: seq=cocreate(intro); each frame if costatus(seq)~="dead" then coresume(seq) end
+```
+
+## Genre pitfalls checklist
+
+- [ ] UI is a STACK (push submenu / pop on cancel), dispatched on the top mode.
+- [ ] Menu input is `btnp` only; cursor index WRAPS with `%` (mind 1-based).
+- [ ] Dialog text reveals over time; confirm fast-forwards, then advances.
+- [ ] Menus/boxes drawn in SCREEN space (`camera()` reset first).
+- [ ] Battle/menu STATE kept separate from which option is highlighted.
+- [ ] Word-wrap pre-computed to the box width (~28 chars full-width).

package/src/skills/picopilot-code/reference/top-down-adventure.md

@@ -0,0 +1,117 @@
+# Top-down adventure reference (tiled world, 4-dir movement, interaction)
+
+Structure for a top-down explorer (action-adventure, RPG overworld). The player walks a
+tiled world in 4 (or 8) directions, collides with solid tiles, the camera follows
+across a map larger than the screen, and the player interacts with specific tiles
+(doors, chests, NPCs). Unlike the platformer there is no gravity; unlike the
+puzzle grid, movement is smooth pixel motion, not cell-stepping.
+
+## The load-bearing rules
+
+1. The player has a pixel position and a FACING direction. Movement is smooth
+   (pixels/frame), but collision is still tested against map tiles via
+   `mget`/`fget`.
+2. Resolve X and Y separately (same axis-by-axis idea as the platformer) so the
+   player slides along walls instead of sticking on corners.
+3. Facing is state you keep for animation AND for "what am I interacting with"
+   (the tile in front of the player).
+4. The map is bigger than 128x128: `camera` follows the player and CLAMPs to the
+   map's pixel bounds. `map()` draws the whole tilemap in world space.
+
+## Movement + per-axis wall collision
+
+```lua
+speed=1.5
+player={x=64,y=64,face=3}   -- face: 0 left,1 right,2 up,3 down (btn order)
+
+function solid(x,y) return fget(mget(x\8,y\8),0) end   -- flag 0 = solid
+function blocked(x,y)  -- 8x8 body, four corners
+ return solid(x,y) or solid(x+7,y) or solid(x,y+7) or solid(x+7,y+7)
+end
+
+function update_player(p)
+ local dx,dy=0,0
+ if btn(0) then dx=-speed p.face=0 end
+ if btn(1) then dx=speed  p.face=1 end
+ if btn(2) then dy=-speed p.face=2 end
+ if btn(3) then dy=speed  p.face=3 end
+
+ -- resolve X then Y separately (slide along walls)
+ if not blocked(p.x+dx,p.y) then p.x+=dx end
+ if not blocked(p.x,p.y+dy) then p.y+=dy end
+end
+```
+
+## The tile in front (interaction target)
+
+```lua
+fdx=split"-1,1,0,0"   -- indexed by face+1: left,right,up,down
+fdy=split"0,0,-1,1"
+
+function front_tile(p)
+ -- the map cell one step ahead in the facing direction
+ local fx=p.x+4 + fdx[p.face+1]*8   -- +4 = center of the 8px body
+ local fy=p.y+4 + fdy[p.face+1]*8
+ return fx\8, fy\8
+end
+
+function _update()
+ update_player(player)
+ if btnp(4) then           -- action button: interact with the tile ahead
+  local tx,ty=front_tile(player)
+  local s=mget(tx,ty)
+  if s==CHEST then mset(tx,ty,CHEST_OPEN) got_item() end
+  -- doors, signs, NPCs: branch on the sprite id at (tx,ty)
+ end
+end
+```
+
+## Camera follow with map-edge clamp
+
+```lua
+-- map_w,map_h = map size in PIXELS (tiles*8).
+function update_camera(p)
+ local cx=mid(0, p.x-64, map_w-128)
+ local cy=mid(0, p.y-64, map_h-128)
+ camera(cx,cy)
+end
+
+function _draw()
+ cls()
+ update_camera(player)
+ map()                       -- whole tilemap, world space
+ spr(walk_frame(player), flr(player.x), flr(player.y), 1,1, player.face==0)
+ camera()                    -- RESET before the HUD
+ draw_hud()
+end
+```
+
+## Rooms / streaming (optional, for large worlds)
+
+Two common approaches:
+- One big shared map, camera just moves over it (simplest; limited by the 128x32
+  map size, extendable with the shared bank).
+- Room-based: each screen is a fixed 16x16 tile region; when the player crosses
+  an edge, snap the camera to the next room and reposition the player. Store room
+  coords, draw `map(room_c*16, room_r*16, 0,0, 16,16)`.
+
+## Animation (frame per facing + walk cycle)
+
+```lua
+-- 2-frame walk per direction; base sprite per facing in a split lookup.
+face_base=split"16,16,32,48"   -- left/right share sprites, flipped
+function walk_frame(p)
+ local moving = btn(0) or btn(1) or btn(2) or btn(3)
+ local step = moving and flr(t()*4%2) or 0
+ return face_base[p.face+1]+step
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Movement is smooth pixel motion, but collision still tests map tiles.
+- [ ] X and Y resolved separately (wall-slide, no corner-stick).
+- [ ] Facing is kept as state and drives BOTH animation and interaction target.
+- [ ] Interaction reads the tile ONE step ahead in the facing direction.
+- [ ] Camera follows and clamps to the map's PIXEL bounds; reset before HUD.
+- [ ] `btnp` for the discrete action button; `btn` for continuous walking.

package/src/skills/picopilot-code/reference/twin-stick-arcade.md

@@ -0,0 +1,128 @@
+# Twin-stick / arcade reference (many entities, spawn/despawn, juice)
+
+Structure for an action arcade cart (shooter, bullet-hell, wave survival). The
+defining problem is MANY short-lived entities at once (bullets, enemies,
+particles) that spawn and despawn every frame. Get the entity-list lifecycle and
+the despawn-while-iterating right, then layer on the "juice" that makes arcade
+carts feel good. Shipped arcade carts are `rnd`-heavy for exactly that juice.
+
+## The load-bearing rules
+
+1. One flat list per KIND (`bullets`, `enemies`, `particles`), each entity a
+   table. `add` to spawn, `del`/`deli` to despawn.
+2. Despawn safely. Deleting the CURRENT item inside `foreach` is safe. Deleting
+   inside an ASCENDING `for i=1,#list` is NOT (it errors once the list shrinks).
+   Use `foreach`, or iterate DESCENDING when you delete by index.
+3. Off-screen or dead entities must be removed, or the list grows unbounded and
+   the cart slows/crashes. Cull every frame.
+4. Movement is velocity-based and free (no grid, no gravity unless you want it).
+   `sin`/`cos` take TURNS (0..1) for aiming/spread.
+
+## Entity lists + safe cull
+
+```lua
+bullets={}
+enemies={}
+parts={}
+
+function fire(x,y,ang,spd)
+ -- ang in TURNS (0..1). sin is screen-inverted, so this aims correctly on screen.
+ add(bullets,{x=x,y=y,dx=cos(ang)*spd,dy=sin(ang)*spd,life=90})
+end
+
+function update_bullets()
+ foreach(bullets,function(b)
+  b.x+=b.dx b.y+=b.dy b.life-=1
+  -- cull off-screen OR expired; del of the CURRENT item under foreach is safe
+  if b.life<=0 or b.x<-4 or b.x>131 or b.y<-4 or b.y>131 then
+   del(bullets,b)
+  end
+ end)
+end
+```
+
+## Spawning waves + aiming at the player
+
+```lua
+function spawn_enemy()
+ -- rnd picks a random screen edge; flr for an integer choice
+ add(enemies,{x=flr(rnd(128)),y=-8,hp=3})
+end
+
+function enemy_shoot(e)
+ -- atan2 gives the turn-angle from e to the player; feed it straight to fire()
+ fire(e.x,e.y, atan2(player.x-e.x, player.y-e.y), 1.5)
+end
+```
+
+## Particles / juice (why arcade carts call rnd a lot)
+
+```lua
+function burst(x,y,col,n)
+ for i=1,n do
+  local a=rnd()               -- random turn 0..1
+  local s=0.5+rnd(1.5)        -- random speed
+  add(parts,{x=x,y=y,dx=cos(a)*s,dy=sin(a)*s,life=10+rnd(10),col=col})
+ end
+end
+
+function update_parts()
+ foreach(parts,function(p)
+  p.x+=p.dx p.y+=p.dy p.dx*=0.9 p.dy*=0.9 p.life-=1
+  if p.life<=0 then del(parts,p) end
+ end)
+end
+
+function draw_parts()
+ foreach(parts,function(p) pset(p.x,p.y,p.col) end)
+end
+```
+
+Screen shake is a cheap, high-impact juice: offset the camera by a decaying
+random amount, then RESET it.
+
+```lua
+shake=0
+function add_shake(n) shake=max(shake,n) end
+function apply_shake()
+ if shake>0 then
+  camera(rnd(shake)-shake/2, rnd(shake)-shake/2)  -- random offset
+  shake*=0.8
+  if shake<0.5 then shake=0 end
+ else
+  camera()   -- no shake: ensure camera is reset (draw state persists!)
+ end
+end
+```
+
+## Collision (cheap circle test for round-ish sprites)
+
+```lua
+-- squared-distance test avoids sqrt. r = sum of radii.
+function hit(a,b,r)
+ local dx,dy=a.x-b.x,a.y-b.y
+ return dx*dx+dy*dy < r*r
+end
+```
+
+## Draw + reset discipline
+
+```lua
+function _draw()
+ cls()
+ apply_shake()
+ map() ; foreach(enemies,draw_enemy) ; foreach(bullets,draw_bullet) ; draw_parts()
+ camera()          -- RESET before HUD (shake/camera persist otherwise)
+ print("score "..score,2,2,7)
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Each entity KIND is its own list; entities are tables.
+- [ ] Despawn uses `foreach`+`del` (safe) or a descending index loop, never an
+      ascending `for i=1,#list` with in-loop `del`.
+- [ ] Off-screen/dead entities are culled EVERY frame (no unbounded growth).
+- [ ] Angles are TURNS (0..1); `atan2`/`sin`/`cos` used consistently.
+- [ ] `rnd(x)` wrapped with `flr` when an integer is needed.
+- [ ] `camera()` reset after any shake, before the HUD.

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

@@ -0,0 +1,195 @@
+---
+name: picopilot-debug
+description: Close the run-test loop for a PICO-8 cart with picopilot. Run the cart headless and read printh output, use the static verify gate honestly (well-formed is not proven-to-run), and understand the structured pico8-not-found / shrinko-not-found boundaries. Use when a cart misbehaves or you need to confirm it boots.
+---
+
+# picopilot debug
+
+Static checks tell you a cart is well-formed; only running it tells you it works.
+picopilot gives you both a static gate and a headless run so you can drive a
+closed loop. (See `picopilot-overview` for the `#include` discipline and
+`picopilot-code` for the token loop.)
+
+## Static first: `picopilot verify`
+
+`picopilot verify` runs tokens + integrity and returns ONE structured pass/fail
+envelope. It is STATIC and NEVER runs the cart, so:
+
+- A green verify means "well-formed", NOT "it runs". The passing result points
+  you at `picopilot run` to confirm the cart boots. Do not stop at green.
+- A fail lists WHICH check flunked (over budget, or a malformed cart), so you fix
+  the named thing.
+- With shrinko absent, verify is `gate-incapable` (a distinct nonzero outcome,
+  NEVER green): it cannot check token bloat, so it refuses to report pass.
+
+## Then run it: `picopilot run`
+
+`picopilot run <cart>` launches PICO-8 headless (`pico8 -x`), streams stdout,
+ENDS the run the moment the cart prints a done-sentinel, and collects one
+structured result: the screenshot PNG paths, the captured `printh` stdout, and
+the exit reason (`sentinel` / `timeout` / `exit`). Read the screenshots to SEE
+the running game; read printh for text traces. On a backstop `timeout` it CTAs
+you to `verify`/`tokens` to catch a code fault.
+
+`run` requires PICO-8 (a licensed, paid binary with no pip/npm path). If PICO-8
+is absent, `run` returns a structured `pico8-not-found` result with a remedy
+(`set PICO8_PATH or install PICO-8`) and a nonzero exit, not a crash or a hang.
+Use the static `verify` loop while PICO-8 is unavailable; it never needs it.
+
+### NEVER run `pico8 --help` / `--version` / bare `pico8` (they BLOCK your tool call)
+
+PICO-8 is a GUI app with NO headless diagnostic mode. `pico8 --help`,
+`pico8 --version`, and bare `pico8` do NOT print text and exit like a normal
+CLI, they LAUNCH THE INTERACTIVE APP and hang forever (verified: `timeout 5
+pico8 --help` exits 124 with zero output). Running one from an agent/automation
+context STALLS your own tool call indefinitely (it has already bitten this
+project's agents more than once, hanging a whole build). Do NOT invoke `pico8`
+to "see its flags" or check it works. The only safe, non-blocking calls are the
+automation ones, ALWAYS with `</dev/null` + a `timeout` backstop:
+`pico8 -x <cart>`, `pico8 -run <cart>`, `pico8 <cart> -export foo.p8.png`. And
+prefer to let picopilot (`run`, `audio render`, etc.) shell out for you rather
+than calling `pico8` by hand. To learn a CLI flag, read the PICO-8 manual, never
+ask the binary.
+
+### The cart must COOPERATE (the recipe `run` orchestrates)
+
+There is no "screenshot an arbitrary running cart" hook and a cart CANNOT quit
+the PICO-8 app itself (`extcmd("shutdown")` works only in EXPORTED binaries).
+So the cart takes its own screenshots and signals when it is done, and `run`
+does the watch + kill + collect. Add these debug lines to the cart, run, then
+remove them:
+
+```lua
+-- screenshot on a frame timer (the verb is "screen", NOT "screenshot")
+if t==20 then extcmd("set_filename","frame_0") extcmd("screen") end
+if t==40 then extcmd("set_filename","frame_1") extcmd("screen") end
+-- signal done so run kills PICO-8 promptly (it can't self-quit)
+if t==45 then printh("__PICOPILOT_DONE__") end
+```
+
+Load-bearing details (each an easy wrong guess, all tested):
+
+- The screenshot verb is **`extcmd("screen")`**. `extcmd("screenshot")` ERRORS
+  ("unknown extcmd"). `extcmd("set_filename","frame_0")` before it names the next
+  shot deterministically (so you can read `frame_0.png`, `frame_1.png`, ... in
+  order and PERCEIVE MOTION by comparing frames).
+- The done-sentinel is the default `__PICOPILOT_DONE__` on its OWN line via
+  `printh`. `run` kills PICO-8 the instant it matches, so the run lasts exactly
+  as long as the cart's logic needs, no blind wait. `--sentinel` changes it.
+- A cart that never prints the sentinel is killed by the backstop
+  (`--backstop-ms`, default 15000) and reported as `exitReason: timeout`.
+- `-x` IS genuinely headless (runs with no display); the external kill is needed
+  only because a cart cannot self-quit, NOT because of a window.
+- Screenshots go to a run-controlled dir (`--shot-dir`, default an isolated temp
+  dir), never `~/Desktop`.
+
+To SEE the game actually being PLAYED (drive input + capture gameplay), use
+`picopilot playtest`, next. (`run` boots the cart and captures what it does on
+its own; `playtest` drives it.) There is also a legacy `run --input` that passes
+a one-shot `-p`/`stat(6)` string, but it only works if the cart hand-decodes
+`stat(6)`; for driving an arbitrary game, `playtest` is the tool, not `run
+--input`.
+
+## Actually PLAY it: `picopilot playtest`
+
+`picopilot playtest` drives ANY normally-written cart (one that reads real
+`btn`/`btnp`) with NO change to it: on a THROWAWAY copy it redefines `btn`/`btnp`
+to read a harness-piped held-buttons byte (reconstructing `btnp` edges) and OWNS the frame
+loop, so it advances an exact number of frames, PAUSES (freezing all state,
+including logic in `_draw`) for a clean screenshot, and captures gameplay (not
+the title). Your `main.p8` is never mutated. `playtest` requires PICO-8 and
+returns the same structured `pico8-not-found` boundary as `run` when it is
+absent. (Mechanism: ADR-0011.)
+
+There are three ways to drive a cart; pick by how much continuity you need.
+
+### One-shot: `picopilot playtest run <cart>`
+
+The whole scripted input is known up front, so the cart replays it to completion
+and exits, returning ONE envelope (screenshot paths + captured printh + the
+steps run). Great for a scripted playtest or benchmark judging.
+
+```
+picopilot playtest run main.p8                          # generic driver (press-to-start + gentle presses)
+picopilot playtest run game.p8 --input "z"              # just press O (a bare button = a press at frame 0)
+picopilot playtest run game.p8 --input "3:o, 18-22:o, 20:right"  # a timeline: press/hold at specific frames
+picopilot playtest run game.p8 --seed 1 --input "o"     # opt-in srand for deterministic replay
+```
+
+`--input` accepts EITHER a bare list of buttons (`"z"`, `"o right"`, pressed at
+frame 0, the same "just press these" form as the session `input` verb) OR a
+timeline of `frame:button` (a single press, one clean `btnp` edge) /
+`from-to:button` (a hold). A button is a NAME (`o x left right up down`, aliases
+`l r u d`, PICO-8 keys `z`/`x`) or a bit `0..5`. Omit `--input` for the generic
+one-button/runner/flappy driver. `--seed n` injects `srand(n)` at cart start
+(never silent) so a random cart replays identically. Screenshots go to
+`--shot-dir` (default an isolated temp dir, NEVER `~/Desktop`).
+
+### (A) Resumable LIVE session: `start` -> `step`/`input`/`shot` -> `stop`
+
+When you want to PLAY across turns (look at the last frame, decide, inject input,
+step, look again), keep the game ALIVE and PAUSED between your turns. `start`
+launches a persistent driven PICO-8 and returns a SESSION ID; every other verb
+addresses that id in a SEPARATE invocation, and the game stays alive + paused in
+between. Stepping is deterministic via a stdout ACK handshake (the host waits for
+the cart's ack before returning), so you always act on a settled, known frame, no
+wall-clock guessing.
+
+```
+ID=$(picopilot playtest start main.p8 --format json | jq -r .id)   # launch, get the id
+picopilot playtest input  $ID "right o"    # hold buttons for the next steps (names: left/right/up/down/o/x)
+picopilot playtest step   $ID --frames 30  # advance EXACTLY 30 frames, then pause
+picopilot playtest shot   $ID              # screenshot the current frozen frame -> a PNG path
+picopilot playtest status $ID              # is it alive? how many frames in?
+picopilot playtest stop   $ID              # tear it down (quit PICO-8, reap the dir)
+```
+
+Lifecycle notes (each verified/handled, not a hope):
+
+- Each verb WRITES a fixed-size command block and WAITS for the cart's ACK, so a
+  `step N` advances exactly N frames and a `shot` between steps captures the
+  frozen intended frame. Between verbs the game is frozen (stable framebuffer).
+- ONE session per id; MULTIPLE concurrent sessions are allowed (distinct ids get
+  distinct daemons/dirs). Omit `--id` for a fresh random id; pass `--id name` for
+  a stable one.
+- ORPHAN reaping: a session you never `stop` self-reaps after an idle window
+  (`--idle-timeout-ms`, default 10 min), so a walked-away session cannot leak a
+  live PICO-8 forever. `stop` is idempotent (safe on an already-dead session).
+- PICO-8 dying mid-session surfaces as a STRUCTURED error on the next verb
+  (`playtest-session-process-dead`), never a hang; a command with no ACK by the
+  deadline is `playtest-session-ack-timeout`. `start` with PICO-8 absent is
+  `pico8-not-found`, same as `run`.
+- Screenshots + the throwaway driven cart live under a controlled temp session
+  dir, never `~/Desktop` or your carts root.
+
+### (C) Stateless REPLAY (the free fallback, no daemon)
+
+You do NOT always need a live session. Because the one-shot is deterministic
+under `--seed`, you can "resume" by RE-INVOKING `playtest run` with an
+ACCUMULATING script each turn: re-run from frame 0 with the same seed plus the
+new presses appended. It is cheap, reproducible, and daemon-free.
+
+```
+picopilot playtest run game.p8 --seed 1 --input "3:4"                 # turn 1
+picopilot playtest run game.p8 --seed 1 --input "3:4, 40:1"          # turn 2 (replays turn 1, then the new press)
+picopilot playtest run game.p8 --seed 1 --input "3:4, 40:1, 55:5"    # turn 3 ...
+```
+
+Prefer (C) for short, replay-safe games (it needs no live process). Use the live
+session (A) for true continuity: long games, or games that reseed from a
+NON-deterministic source (wall-clock/entropy) mid-run and so cannot be replayed
+from frame 0. Both drive the SAME cart-side transform; only the host lifecycle
+differs.
+
+## The two structured boundaries
+
+Both dependency boundaries are soft and well-signposted, so read the result, do
+not guess:
+
+- `shrinko-not-found` (remedy `uv pip install shrinko`): gates the token/lint
+  commands and therefore `verify`.
+- `pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`): gates `run`,
+  `playtest`, `audio render`, and binary/PNG exports.
+
+Each is a structured `{ ok: false, reason, remedy }` envelope with a nonzero
+exit, telling you exactly which capability is gated and how to enable it.