picopilot 0.1.4 → 0.2.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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), understand the structured pico8-not-found / shrinko-not-found boundaries, and export with a screenshot as the label splash. Use when a cart misbehaves, you need to confirm it boots, or you are exporting it.
 ---
 
 # picopilot debug
@@ -181,6 +181,23 @@ 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.
 
+## Ship it: `picopilot export` and the label splash
+
+`picopilot export <cart> [dest]` writes a playable `index.html` + `index.js` bundle (requires PICO-8). PICO-8 needs a `__label__` (the loading splash) to export well; a labelless cart gives a blank splash or no bundle at all. Give it one from the game itself, with no image tool. The simplest way captures a frame for you:
+
+```sh
+picopilot export main.p8 out --label-frame 0    # run the cart with no input, use frame 0 (the title screen)
+```
+
+`--label-frame <n>` runs any cart headlessly through the playtest harness with NO input and bakes frame `n` in (0-based: 0 is the first drawn frame); the cart does not need to screenshot itself. Use 0 for the title screen, or a later frame if the title fades in or animates. Check the result: the output's `labelSource` is `frame`, and a cart that never reaches frame `n` fails as `label-frame-not-captured`. To look at a frame BEFORE baking it, a session reproduces it exactly: `playtest start main.p8`, `playtest step <id> --frames <n+1>`, `playtest shot <id>` (not `playtest run`, which presses buttons). With no input it cannot get past the title, so for a GAMEPLAY splash, drive the cart and pass the screenshot you want:
+
+```sh
+picopilot playtest run main.p8 --input "..."     # or: picopilot run main.p8 --shot-dir shots
+picopilot export main.p8 out --label shots/<name>.png   # <name>: a path listed under `screenshots`
+```
+
+Pass the screenshot unchanged. `run` and `playtest` write PICO-8's pixel-exact upscale (384x384 at the default 3x `screenshot_scale`), and `--label` accepts any square multiple of 128 (128x128, 256x256, 384x384, ...) and samples it back down to 128x128. Any 128x128 PNG works too, including palette-indexed and greyscale ones. Do NOT resize or convert it with ImageMagick first: that is never needed, and a resize that is not an exact multiple is rejected (`label-wrong-size`). An existing `__label__` in the cart always wins; `--label` only fills a missing one. `--label` and `--label-frame` never write into your cart (they export a labeled copy), so pass one on every export; passing both is an error. `picopilot serve` (play the build in a browser) takes the same two flags for the same reason, e.g. `picopilot serve main.p8 --label-frame 0`.
+
 ## The two structured boundaries
 
 Both dependency boundaries are soft and well-signposted, so read the result, do

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

@@ -1,6 +1,6 @@
 ---
 name: picopilot-overview
-description: Start here for any PICO-8 cart built with picopilot. The #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
+description: Start here for any PICO-8 cart built with picopilot. Call picopilot doctor first to learn what this machine can do (everything works headless), then the #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
 ---
 
 # picopilot overview
@@ -13,6 +13,14 @@ acceptance gate, so you can build a PICO-8 game and self-correct.
 Load this skill first. Then load the group skill for whatever you are doing:
 `picopilot-code`, `picopilot-art`, `picopilot-audio`, or `picopilot-debug`.
 
+## First on a new machine: `picopilot doctor`
+
+Run `picopilot doctor` before anything else on a machine you have not used yet. It reports what THIS machine can do: whether PICO-8 is found and actually runs (with its version), whether shrinko8 is found, how a PICO-8 audio session would get a display, and the resulting `available` / `unavailable` command lists (each unavailable command says what it is missing). Plan from that list instead of discovering limits by failing.
+
+Every picopilot command works on a machine with no display and no sound card (a server, CI, an agent sandbox). Screenshots, `playtest` and `export` run PICO-8 headless. Audio recording (`audio render`, `audio record`, `run --record-audio`) needs a real PICO-8 session with a window, and picopilot provides one by itself: with the default display mode `auto`, when there is no display it starts a private virtual display for that recording and removes it afterwards. You do not need to set anything up. Only if `doctor` lists the audio commands as unavailable with `missing: display` (or a recording fails with `display-unavailable`) does the machine lack Xvfb; the error names the install command to suggest to the human.
+
+The display mode can be forced with `--display xvfb` (always virtual) or `--display native` (use the current display as-is), also settable as `PICOPILOT_DISPLAY` or `"display"` in `picopilot.json` (when picopilot runs as an MCP server, only `PICOPILOT_DISPLAY` in the server's environment applies). Leave it at `auto` unless a human asks otherwise.
+
 ## The #include discipline (how every picopilot cart is laid out)
 
 - `main.p8` is the cart. Its `__lua__` section is a single line: `#include main.lua`.