@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/claude/commands/mobile-qa.md

@@ -0,0 +1,28 @@
+---
+description: "Judge whether the Funpixel game in this folder is native to a phone (touch-native controls, the play area's share of the screen, thumb reach, chrome during play, safe areas, orientation, first touch) from real phone evidence, and get its findings ranked with a frame and a number each. Applies nothing."
+argument-hint: [--phone] [what changed since the last look, optional]
+---
+
+Look at the game in this folder (the one with `funpixel.json`) the way a phone player meets it. The
+review is a mirror: it changes nothing, and its findings are for the person to pick from.
+
+1. Say in one line what runs: free measurements here (a few minutes; every view captured at both
+   sizes, the phone screens audited, a WebKit phone shot, key parity at phone size, five windows
+   swept with `look --fit` from wide-short desktops to the phone either way), real Mobile
+   Safari when this Mac has baguette (about a minute per orientation), then one Mobile QA seat as an
+   agent on the person's own setup.
+2. On a Mac with baguette (`npx @funpixel/tools doctor` says), build and add `--phone`: it runs
+   `funtools phone` in portrait and landscape first, so the seat sees real Mobile Safari (its bars,
+   the notch, iOS taps). It boots its own simulator and shuts it down. Without it, the seat judges
+   WebKit and Chromium at phone size and says iOS was not observed.
+3. Run `npx @funpixel/tools mobile-qa` (with `--phone` when chosen). It prints the seat's prompt file.
+4. Run the `mobile-qa` agent in the foreground as a fresh agent given only that file's contents; it
+   writes its answer beside the prompt. A seat that sees this conversation or the code judges the
+   intent instead of the phone.
+5. Run `npx @funpixel/tools mobile-qa report` and hand back its findings in order, each with its
+   frame and number, and the phone-native score. What the seat judges and why: skill
+   `fp:verifying`, `references/mobile-qa.md`.
+6. Ask which to take on. When the phone is the game's primary platform, `"platform": "phone"` in
+   `funpixel.json` metadata says so, and a key no touch reaches ranks high.
+
+`/fp:playtest` runs the same seat with its other seats.

package/plugins/claude/commands/new.md

@@ -0,0 +1,94 @@
+---
+description: "Start a new Funpixel game from an idea, the way our best games were made: brief back, the first look and a nice first playable the owner steers, the whole game planned around it and locked, then built round after round against the plan's target frames until the owner plays it and says yes."
+argument-hint: [the game idea]
+---
+
+Start a new Funpixel game from the idea the person gave with this command; with nothing given, ask
+what game they want in a sentence. You are their copilot: you plan the game with them in this chat,
+then build it with them round after round. Ask little and decide well: "you choose" is always an
+answer, and you say why. The path is the brief's (each step's why
+and tools: `fp:gdd`'s `references/the-path.md`). The locked plan is the job; how you build
+it is yours.
+
+1. **Brief back, on one screen, with one question.** Turn their sentence into a short brief and
+   show it once, first thing in the reply: title, kind (genre and camera), the verb, the world, the
+   length, how failing works, the look, phone and desktop, each in a line. Under it, your calls in
+   one line each (genre, engine, title, and anything you found on the way). Then the one question:
+   is the brief right? Their yes or their edit starts the work. Everything else is yours to decide
+   and say, never a second question: what they asked for outranks a standing request it
+   contradicts (a one-minute game stays one minute); a folder already there under the game's name
+   is left as it is and the game starts beside it; a file that might be reused is kept as the
+   fallback and a new one is made. A choice only they can make (the one that changes what the game
+   is) may be the question in place of "is it right", with your pick already written in.
+2. **Start.** `npx @funpixel/tools flow start <folder> --idea "<the brief in one line>" --name
+   "<title>"` (add `--framework pixi|three-world|three` when the line doesn't make it clear) creates
+   the game (it runs `npx @funpixel/tools init `, which mints the game's id when an API key is
+   set); `npm install`. If `flow start` or the first paid step says the Funpixel tools cannot be
+   reached or the key is refused, stop there and tell them in one line what to start or sign in to
+   (`npx @funpixel/tools doctor` names it): a game drawn from boxes and spheres in place of its
+   models, sounds and music is not the first playable, and is built only on their yes. Then write
+   the plan's opening from the brief before anything is drawn:
+   the pitch, the loop, the content list at the length they asked for, the look, with no template
+   line left unfilled. `npx @funpixel/tools gdd page` writes it as a page, `design/GDD.html`
+   (every later step keeps it current): show them that page, not a file path, so they read the plan
+   and decide on it while the first pictures are made. Once the game runs, show the game itself:
+   open it beside the chat where they are: your host's own browser when it has one (Cursor's, Codex's), else `npx @funpixel/tools dev --open` (the system browser, in its own tab). Do not call `create_game` as well (it mints a second, empty draft). From then on,
+   `npx @funpixel/tools flow` each turn names the owner's notes first, then the one next step.
+3. **First look, then a first playable** (the game's opening stages; `flow` names each). Make the
+   key art (the game's look in its own light, at the play framing) and the hero's reference sheet;
+   put both in the plan (`## First look`, as their paths) so they appear on its page, show them, and
+   take their words before anything 3D is paid for. Then build a first
+   playable from them, in the game itself, with real assets: the hero (rigged where it moves), the
+   place in the key art's light, the title art, a music loop, the verb's sounds. Size it by the game:
+   a short game about 1 minute (mostly the place, its look and feel, the verb once), a mid game 2 to
+   3, a long game 3 to 5 (the core loop once, a win and a loss). Judge it against the key art
+   (`score --target`, `check --front-door`) before they see it, then show it with captures and the
+   preview link. Reveal it as a moment: a 12-second clip of real play (`reel`), the game open beside
+   the chat, "try this first: …", in the game's words, never the kit's. They play it and say whether it has potential: `npx @funpixel/tools note verdict
+   prototype accept "<their words>"`; "not this" means a new key art, or dropping the idea.
+4. **Plan the whole game around it, at its real size** (skill `fp:gdd`), in the chat and the GDD: the
+   genre's best games beside it (what they do, what we take); pillars; the story and how deep it
+   goes; levels and the environment maps; characters and the living world; fun factors and the wow
+   moments; screens and HUD for phone and desktop; the look and its locked style; a numbers contract
+   with tests named after it; and the rest of the first look: target frames for the moments that
+   matter, the screens, the HUD over play, a frame per place. Finish with the asset list: the GDD's `## Asset script`,
+   every piece the game ships (cast, environments, props, title and HUD art, sound, music), made
+   the list with `npx @funpixel/tools assets script --write` and priced with `assets gen --dry-run`.
+   The first look's pictures are its references, never the shipped art. Ask the person the choices a studio lead decides; propose
+   the rest. Size it to the length in the brief, never smaller.
+   Lines in `~/.funpixel/owner.md` are the owner's standing requests: answer the ones that apply in
+   the plan.
+   Notes the owner writes on the plan page (a host that can mark up a page sends them with the part they
+   point at) are their words on the plan: revise `design/GDD.md` there, raise its version, run
+   `npx @funpixel/tools gdd page` so the open page comes back rewritten, and say in one line what changed.
+   Show, mark, revise, apply, as many times as they want before the lock and after it. The owner can
+   also agree to the plan a section at a time; `flow` names the sections still open, and changing an
+   agreed section's words opens it again, so say so when you do.
+   Not sure which skill or command a step needs? `npx @funpixel/tools find "<what you want to do>"`.
+5. **Lock.** `npx @funpixel/tools flow ask` readies the plan and its price; show it in the chat
+   (the GDD, its target frames, the price) and wait for their yes. Record it with their words,
+   `flow agree --by owner "<their words>"`. The lock means "good, let's build, unless I say otherwise":
+   a new direction becomes a new GDD version they lock again. Where the build later has
+   to move, write it in the plan's "Where the build moved" table, with why.
+6. **Sim first**, then **build with the assets as they land**: the rules and numbers as seeded,
+   tested code with bots (`sim`, `test`); generate every planned asset from the locked style (cast,
+   environments, props, screens, HUD art, sound, music) into `public/assets/` while you build
+   (the locked plan is the go-ahead), saying the route and cost of each paid call in one line. Out
+   of credits is a pause: say so; they top up. The slice: the player moves, one verb works, a win and a loss fire, progress
+   shows, keys and touch both work, `npx @funpixel/tools check` exits 0. Keep `dev` or `verify
+   --watch` running from the first edit.
+7. **Each round, the look-dev loop**: capture at the target moments, set each beside its target
+   (`compare --target`), fix the biggest difference, then play it on phone and desktop (`play`, `playtest`). Repeat
+   until each beat is close and you are both confident the game is good; matching the targets is the job, and only the owner relaxes one. Close the
+   round: update the GDD's `## Where we are` (each capture beside its target), show the captures in
+   the chat, then `npx @funpixel/tools flow round`; after their
+   cap of rounds (default 3), hand back and they resume with `/fp:flow`. When `flow` says the
+   whole-game look is due (after the first playable, then every few rounds), run `flow look` and
+   hand its brief to a fresh agent: it routes each defect to an owner and never vetoes.
+8. **Extend** with levels and story; fold a mid-build request into the pillars first.
+9. **Hand back** with an honest verdict: what plays now (keys and touch), how it compares with its
+   targets ("below the bar: <why>" when it is), what is out on purpose, every fallback still in the
+   game, and the next two or three steps. File `report_feedback` (skill `fp:feedback`).
+
+Spend is the owner's: never shrink an agreed game to save credits. Only the owner drops a game
+(when they say so in the chat: `flow drop --by owner "<their words>"`); you may recommend it, with the numbers.

package/plugins/claude/commands/playtest.md

@@ -0,0 +1,66 @@
+---
+description: Playtest the Funpixel game in this folder between creator rounds (a long blind phone session, the calibrated critic panel, the plan-fidelity and experience seats, a head to head with the genre hit when its evidence is here, and free measurements) and get 3–4 ranked next steps with evidence. Applies nothing.
+argument-hint: [--quick] [what changed since the last playtest, optional]
+---
+
+Playtest the game in this folder (the one with `funpixel.json`). The playtest is a mirror for the
+person: it changes nothing in the game, and its steps are suggestions they pick from.
+
+1. Say in one line what will run and how long it takes: the free measurements (2 to 4 minutes),
+   then 3 critic seats (2 with `--quick`; each re-reads the phone captures), the Mobile QA seat, the fidelity seat when the GDD has target frames, one
+   blind phone round (a ten-minute session; `--quick` plays a short one) and, when the hit's evidence
+   is on this machine, 6 head-to-head calls; then 2 experience seats (1 with `--quick`). All run as
+   agents here on the person's own setup; about 30 to 45 minutes in all. `--quick` is the fast look.
+2. If `.funtools/playtest/premise.txt` is missing, write 4 to 6 neutral sentences there: what the
+   game is and what the player does, as a store page would say it. No intentions, design notes or
+   praise; a seat told why a frame looks as it does scores it kinder.
+3. Run `npx @funpixel/tools playtest` (with `--quick` when asked; add `--phone` on a Mac with
+   baguette, so the Mobile QA seat sees real Mobile Safari in both orientations). It builds, verifies, captures
+   every view at both sizes with moments as strips, audits the phone screens, measures the HUD in
+   play and how the actors stand out from the ground, and profiles, then prints one prompt file per
+   seat. Each prompt carries those numbers as facts F1, F2, … to read before the frames (Scenario's
+   numbers first, then eyes); the report says which facts each seat cited.
+4. Run every seat now, in parallel in the foreground (a background seat answered after a session
+   had already ended, in one game's third session), each as a fresh agent given only the contents of its prompt
+   file: one per `seats/<name>.md`, per `versus/<name>.md` and `fidelity/fidelity.md` when printed (and `fidelity/ui.md` from step 5), each a general-purpose
+   agent (the `critic` agent's own format would override the prompt's), and the `player` agent with
+   `player.md` at phone size. The Mobile QA seat (`mobile/mobile-qa.md`, the `mobile-qa` agent: is
+   it native to a phone, `references/mobile-qa.md` in skill `fp:verifying`) reads the blind round
+   too, so it runs in step 5. A seat that sees another seat's answer, the code or this conversation
+   drifts toward them, so each gets only its file and writes its own answer file; an answer file
+   written by anyone else is no longer a seat's verdict.
+5. Once the blind round is filed, run `npx @funpixel/tools playtest experience`: the first time, it
+   keeps the steps the blind player played as the saved route (`test/journeys/playtest-route.json`:
+   its steps, viewport and seed) and films it at the plan's timed moments, so later playtests replay
+   the same route with the same camera and compare like with like. It measures depth for free (the
+   content inventory, the pacing of real play, the come-back answer) and prints the experience seats'
+   prompts, the UI fidelity seat's when the GDD has mockups, the Mobile QA seat's with the round
+   added, the fidelity seat's again when it now has played frames, and from the second playtest on,
+   the ledger seat's (`ledger/ledger.md`: last round's blockers, judged fixed, still there or changed, and the
+   do-not-regress list, each judged held, lost or not observed). Run them the same way, each a fresh agent given only its file. What
+   they judge, and why beside the panel: skill `fp:verifying`, `references/experience.md`.
+6. Run `npx @funpixel/tools playtest report`, then read `.funtools/playtest/<n>/report.md`. After
+   the next steps it shows the do-not-regress list (up to eight things the panel named as working, kept
+   in `.funtools/keep.json`; `playtest keep` lists it), last round's blockers with this round's verdict, and the round history
+   (`.funtools/playtest/history.json`: panel axes, the experience bar, the blind player, minutes of
+   real play, fidelity per moment and the AD lines, every round), with each drop marked. When it
+   opens with "Look at the captures first", open those frames before trusting any score: a view
+   that never reached its beat is scored as the wrong game (one game scored 4.9 on views stuck at
+   the opening shot, 6.55 once they reached their beats). A thing on the list that is lost is a
+   regression: the report leads with it and exits 1, the flow makes putting it back the round's first
+   step, and only the owner takes an item off (`playtest keep --drop K<n> --by owner "<their words>"`).
+   What a great playtest looks like, and
+   the review page the person read: skill `fp:verifying`, `references/playtest.md`.
+7. Hand back the report's next steps in its order, each with its quote, frame and number, last
+   round's blockers, the round history with its drops (never leave a drop out), any staged frame
+   the played route never reached, and what ran. Ask which to take on; the playtest applies
+   nothing, so the game stays as it was until the person picks.
+8. Last, once: how did the kit do in this playtest and the rounds before it? One `report_feedback`
+   call with the kit verdict (skill `fp:feedback`, "The kit verdict"): what helped, what got
+   in the way or was wrong, what was missing, each naming its tool or skill, and one overall line.
+   About the kit, not the game; when the call fails, the same line goes in
+   `.funtools/kit-feedback.jsonl`.
+
+`npx @funpixel/tools playtest status` names any seat still owed. With a Funpixel API key,
+`npx @funpixel/tools playtest --hosted` runs the panel and the blind player as hosted jobs for
+credits instead, quoted first (`--yes` to spend a quote over 50).

package/plugins/claude/commands/publish.md

@@ -0,0 +1,23 @@
+---
+description: Publish the Funpixel game in this folder as a draft, after a fresh passing verify and filed feedback.
+argument-hint: [title, optional]
+---
+
+Publishing needs a passing `verify.json` for the current files: the server refuses a missing, stale
+or failing one. So run `npm run build && npx @funpixel/tools verify` first, and fix what it names
+(skill `fp:verifying`) until it exits 0.
+
+Then, following the `fp:publishing` skill:
+
+1. List what will ship and check it for leaks (keys, local paths, private notes): a published game
+   is public to anyone with the link, and everything outside `.harnessignore` ships.
+2. Publish as a draft: `publish_game` when the Funpixel MCP is connected, otherwise
+   `npx @funpixel/tools publish --name "<title>"` (needs `FUNPIXEL_API_KEY`). The id in
+   `funpixel.json` makes every later publish update the same draft in place; no flag needed.
+3. Load the published URL the way a player does and confirm it renders:
+   `npx @funpixel/tools verify <play url>`. When publish printed no address, its server verify is
+   that check, so a second publish to get an address repeats it (a real Claude Code session did). A publish that
+   succeeded but does not render is its own problem: the same files give the same page, so read the
+   build rather than publishing again.
+4. File `report_feedback` (skill `fp:feedback`), then tell the person the draft's link and
+   that sharing it to Community is their choice in the app.

package/plugins/claude/commands/smoke-build.md

@@ -0,0 +1,25 @@
+---
+description: The 10-minute smoke build before any full build — one locked-art picture and one generated 3D model in a bare scene, captured and judged.
+argument-hint: <plan folder with design/>
+---
+
+Before a full build, prove the kit end to end on this machine and account. In a new, empty folder next to
+the plan (never the game itself), run:
+
+`npx @funpixel/tools smoke-build ../smoke --plan <the folder holding design/plan.md and design/first-look/ref-*.png>`
+
+It runs the shortest path a real build takes: `init --bare`, the plan's locked sheets imported and
+pinned on the game's lock, one world picture and one 3D model through the hosted tools, both placed in
+the scene, then capture, `check --world`, `score --target` against the plan's target frame, and one
+progress card. It costs one picture and one model.
+
+Read the four verdicts (exit 0 pass, 1 fail, 3 error; the record is `.funtools/smoke-build.json`):
+
+1. **a generated 3D model in the world** — a failed model is retried, switched (provider, tier), or put
+   to the person (`progress ask … --kind scope`); it is never drawn in code;
+2. **the locked look** — the picture came back drawn to a locked sheet, and the target score is at the bar;
+3. **no primitives** — the world read holds by name (no boxes, box figures, gliding cut-outs);
+4. **a real card** — the card carries a frame of the build.
+
+Any FAIL means the full build would hand back what the last ones did. Fix the kit or the provider,
+run the smoke again, and only then start the game. Report the four verdicts as they stand.

package/plugins/claude/commands/verify.md

@@ -0,0 +1,20 @@
+---
+description: Build and verify the Funpixel game in this folder, fix what fails, and stop when it passes.
+argument-hint: [what changed, optional]
+---
+
+Run `npm run build`, then `npx @funpixel/tools verify` (or `npx @funpixel/tools check`: both and
+the rules suite in one call) in the game folder now (the one with `funpixel.json`). If the Funpixel MCP is connected and the local build cannot run, use `build` then
+`probe` instead.
+
+Then, following the `fp:verifying` skill:
+
+1. Read the exit code: 0 pass, 1 fail, 2 nothing measured (not a pass), 3 a tool error.
+2. For every FAIL line, fix the cause in the game, rebuild, verify again. A check weakened, or a
+   state field negated to pass it, makes verify report a game that does not exist (the harness
+   learned this on control checks passed by flipping a sign instead of fixing the camera).
+3. Exit 2: declare the missing `__FPX_*` hooks, then verify again.
+4. On exit 0, press the real start control once (the front door) and confirm the play screen:
+   verify enters play through its hooks and skips the title, so a dead Play button still passes it.
+5. Green is where this command ends. Report the verdict, what you fixed, and anything you could
+   not verify.

package/plugins/claude/hooks/brief.md

@@ -0,0 +1,135 @@
+<!-- funpixel-gdk:brief -->
+# Game development with the Funpixel toolkit
+
+Start with the creator's goal. An asset repair stays an asset repair; a new game gets the path
+below. The creator and host agent own scope, style and workflow. Recipes here and in the
+skills are defaults, not boundaries: keep locked choices, explore open ones, find another way when
+no recipe fits.
+
+Assets work in any engine; build, preview and publish target browser games (Pixi 8 or Three.js,
+Preact, the SDK).
+
+## The shelf
+
+Skills hold what great looks like, with numbers; each loads in one call (Skill tool or `SKILL.md`):
+- starting, planning or reshaping a game, the GDD: `fp:gdd`; code, the SDK, multiplayer:
+  `fp:game-spine`; rules, levels, balance, depth and replay: `fp:game-logic`
+- the look, 2D art, light and effects: `fp:art`; 3D models, the bench and levels: `fp:3d`
+- feel and payoffs: `fp:game-feel`; a place with a story: `fp:world-and-story`; sound
+  and music: `fp:audio`; phone HUD, touch: `fp:mobile-ui`
+- proving it plays, the panel and blind player: `fp:verifying`; dev log: `fp:feedback`;
+  publish, trailer, store shots, playable ads: `fp:publishing`; a store: `fp:store`;
+  Unity: `fp:unity-game`
+
+The session start names the few this game needs. Local hooks advise (`funpixel.json` `gdk.gate`:
+`"block"` or `"off"`; `FUNPIXEL_GDK_GATE`); no setting changes publishing's own checks.
+
+## The path
+
+For a complete game, the path our best games took: you are the person's copilot, not an autopilot.
+A plan made with them is a contract, target frames show what done looks like, and every round
+closes the gap between the two. The locked plan
+is the job; how you build it is yours. Why, tool and signal per step:
+`gdd/references/the-path.md`.
+
+Start each session from `npx @funpixel/tools flow`: the owner's notes first (they outrank an
+agent's claim), then the one next step. After every step, a short status in the chat with a
+capture of the build: the owner watches and steers.
+
+1. **Brief back, one screen, one question.** A short brief (title, kind, verb, world, length,
+   failing, look, platforms), your calls in a line each, then one question: is it right? Decide
+   the rest and say it: their ask outranks a standing request.
+2. **First look, then a first playable.** The key art and the hero's reference sheet, shown in
+   the chat for the owner to steer. Then a playable built from them with real assets (the hero,
+   the place in the key art's light, title, music, the verb's sounds), sized by the game (short:
+   about 1 minute; long: 3 to 5), judged against the key art. They play: potential, or not.
+3. **Plan the whole game around it** (skill `fp:gdd`): the genre's best, pillars, story,
+   levels and maps, fun and wow moments, screens and HUD, a numbers contract with named tests,
+   the rest of the first look (target frames), the asset list with its price.
+4. **Lock** (`flow ask`): the owner's "looks good, let's build" (price shown; not a cap). It
+   stands until they say otherwise; a new direction is a new GDD version locked again; a
+   departure goes in "Where the build moved", with why.
+5. **Sim first** (`sim`, `test`), then **build with the assets as they land** in `public/assets/`,
+   each judged under the game's light. The slice: one verb, a win and a loss, progress, keys and
+   touch, `check` exits 0.
+6. **Each round, the look-dev loop**: capture at the target moments, set each beside its target
+   (`compare --target`), fix the biggest difference, then play it (`play`, `playtest`). Repeat
+   until each beat is close. Matching the targets is the job, never a style choice: only the owner
+   relaxes a target.
+7. **Extend** chapter by chapter (each to its targets, then the owner's yes); fold a new
+   request into the pillars first.
+8. **Finish when the person plays it and says yes.** Green means stop. When verify passes and the
+   goal is met, stop editing. No renames, restyles or polish nobody asked for; they break what
+   worked and hide which change did what.
+Hand back what plays now (keys and touch), what is out on purpose, the next two or three steps,
+and every stand-in. File the dev log with `report_feedback` before you finish.
+
+## A funtools scaffold
+
+A folder `funtools init` made is a finished frame around a demo round (`init --bare`: none). Replace
+the demo with your game (`rules.ts`, `session.ts`, `game.ts`, `feel.ts`, `hud.tsx`, `screens.tsx`,
+`look.json`, a check per mechanic in `funpixel.json`); keep the frame, host integration and checks.
+
+## Silent failures
+
+- dt is in seconds and clamped: `dt = Math.min(dt, 0.1)`. A background tab hands you one huge
+  frame and everything tunnels. Pixi: `ticker.deltaMS / 1000`, never `deltaTime`.
+- Resize with `setupGameResize((w, h) => …)` from `@funpixel/sdk`, never a `resize` listener or
+  `resizeTo: window`: those miss iframe resizes. It fires once at the call, so create the renderer
+  first.
+- Audio: one `new AudioEngine({ iosPatch: false })` from `@funpixel/sdk/audio`; connect every
+  source to `audio.master` and call `audio.unlock()` from the first click, pointerup or keydown.
+  `iosPatch: false` lets the iPhone ringer switch mute the game; pass `true`
+  only when sound is the game (rhythm, music). Keep an existing game's choice.
+- Pointer handlers use `addEventListener`. Assigning `onpointerdown = …` twice kills the first
+  control without an error.
+- Three: GLBs need `DRACOLoader`, `KTX2Loader` and the meshopt decoder with same-origin decoder
+  paths, an environment map (they render flat grey without one), and `mixer.update(dt)` every frame.
+- Pixi: every display object gets a `.label`; `window.__PIXI_APP__ = app` after `app.init()`.
+- Room codes, share codes and seeds carry `data-funpixel-selectable` (else they cannot be copied).
+- `@funpixel/sdk` is pinned exactly (`"0.7.0"`). Import the root only for `setupGameResize`;
+  everything else from a subpath. Multiplayer is `Room.autoJoin(getGameKey(), …)`, never a raw
+  WebSocket (skill `fp:game-spine`).
+- A performance fix changes how a frame is made (pooling, atlases, instancing), never what it shows.
+- Assets arrive as expiring URLs: `npx @funpixel/tools job <id> --wait --out public/assets/<file>`;
+  never base64 in code.
+- Hosts may refuse chains, loops, `sed -i`, heredocs and outside paths: use the edit tool, one
+  command per call (`doctor --host`); keep captures in `design/shots/`.
+
+## Red flags: thoughts before broken games
+
+- "It compiles, so it works." Verify it; a runtime crash builds green.
+- "I'll cast it to make the error go away." Look the name up (skill `fp:game-spine`); `as any` and
+  `?.` compile code that does nothing.
+- "The class exists, so the feature exists." Trace it from boot, the loop or an input handler, and
+  give it a check.
+- "The shapes will do for now." They won't: make the planned asset. A shape is only a fallback
+  until it lands; name every one still in the game at hand-back.
+- "The Play button surely works." Press it (skill `fp:verifying`, front door).
+
+## Spending
+
+Scope, time and spend are the creator's: never shrink an agreed game to save them. The locked plan
+is the go-ahead for its assets: make them (pass `confirm_cost`); before each paid call say the
+route and its cost in one line. No budget unless the owner sets a cap. Out of credits is a pause: say so;
+they top up and you go on. Long jobs return an id: collect
+with `get_job`. Never end a session (headless `-p` too) while a background job, subagent
+or recording runs: a session that ends does not come back. Do the work in the session.
+
+## Hosted and local
+
+The Funpixel MCP does the paid and hosted work; `funtools` runs locally and free. When the MCP is
+not connected, use the local column and say which steps you could not do.
+
+| Job | MCP tool | Local (`npx @funpixel/tools …`) |
+|---|---|---|
+| New game | `create_game`, only with no local files (`init` mints the id) | `init` |
+| Build and preview | `build`, `preview` | `npm run build`, `dev` |
+| Check it plays | `probe`, `screenshot` (`click` presses Play) | `verify`, `verify --watch`, `verify --front-door` |
+| Look at a state | `capture_view`, `audit_screens`, `inspect_scene` | `capture` (`--all`: every view), `audit-screens`, `scene` |
+| Critic panel, blind player | `review`, `play` | `playtest`: `critic`, `player` agent seats |
+| Images, sprites, sheets | `generate_image`, `generate_sprite`, `edit_image`, `generate_spritesheet` | `gen image\|sprite\|edit\|sheet`, `assets gen` |
+| Sound and music | `generate_sound`, `generate_music` | `gen sound`, `gen music` |
+| 3D models | `generate_3d_model`, then the bench tools (skill `fp:3d`) | `gen model3d`, `model …` (`--local` on your Blender) |
+| Publish | `publish_game` | `publish` (needs `funtools login`) |
+| Dev log and feedback | `report_feedback` | lines in `.funtools/devlog.jsonl` |

package/plugins/claude/hooks/critic-receipts.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const hash = (s) => createHash('sha256').update(s).digest('hex');
+const AXES = ['lookAndFeel', 'readability', 'intuitiveness', 'juice', 'fun', 'mobile', 'hud', 'overall'];
+const BAR = ['art_direction', 'consistency', 'motion', 'juice', 'screens'];
+const PERSONAS = { veteran: 'veteran player', ux: 'UX designer', skeptic: 'skeptic' };
+const directory = (root) => join(root, '.funtools', 'critic');
+export function captureDigest(root) {
+    try {
+        return hash(readFileSync(join(root, '.funtools', 'capture', 'index.json')));
+    }
+    catch {
+        return null;
+    }
+}
+export function panelScore(surfaces) {
+    if (!Array.isArray(surfaces) || surfaces.length < 2 || surfaces.length > 32)
+        return null;
+    const persona = Object.keys(PERSONAS).find((p) => surfaces[0]?.persona === p || surfaces[0]?.persona === PERSONAS[p]);
+    if (!persona || !surfaces.every((s) => s && (s.persona === persona || s.persona === PERSONAS[persona]) &&
+        typeof s.surface === 'string' && AXES.every((a) => Number.isFinite(s.scores?.[a]) && s.scores[a] >= 1 && s.scores[a] <= 10) &&
+        Array.isArray(s.findings) && s.findings.every((f) => f && ['high', 'medium', 'low'].includes(f.severity)) &&
+        BAR.every((k) => ['met', 'missing', 'unseen'].includes(s.bar?.[k]))))
+        return null;
+    if (!['phone', 'desktop'].every((vp) => surfaces.some((s) => s.surface.toLowerCase().startsWith(`${vp} `))))
+        return null;
+    const mean = (axis) => surfaces.reduce((n, s) => n + s.scores[axis], 0) / surfaces.length;
+    const entries = new Map();
+    for (const s of surfaces) {
+        for (const [k, v] of Object.entries(s.bar))
+            if (v === 'missing')
+                entries.set(`${s.surface}: ${k} missing`, k);
+        for (const f of s.findings.filter((x) => x.severity === 'high')) {
+            entries.set(`${s.surface}: ${f.id ?? 'high finding'} ${f.issue ?? ''}`.trim(), String(f.id ?? f.issue ?? 'high finding'));
+        }
+    }
+    const unseen = [...new Set(surfaces.flatMap((s) => Object.entries(s.bar).filter(([, v]) => v === 'unseen').map(([k]) => k)))];
+    return { persona, overall: mean('overall'), look: mean('lookAndFeel'), open: [...entries.keys()], openKeys: [...entries.values()], unseen };
+}
+export function recordCritic(root, input, fingerprint, now = Date.now()) {
+    if (input.hook_event_name !== 'SubagentStop' || typeof input.agent_id !== 'string' || !input.agent_id ||
+        input.agent_id.length > 200 || typeof input.last_assistant_message !== 'string' || input.last_assistant_message.length > 65536)
+        return false;
+    let value;
+    try {
+        value = JSON.parse(input.last_assistant_message);
+    }
+    catch {
+        return false;
+    }
+    const digest = captureDigest(root);
+    if (value?.kind !== 'funpixel-critic' || !digest || value.fingerprint !== fingerprint || value.capture_digest !== digest || !panelScore(value.surfaces))
+        return false;
+    const dir = directory(root);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${hash(input.agent_id)}.json`);
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify({ ...value, agent_id: input.agent_id, at: now }));
+    renameSync(temp, file);
+    return true;
+}
+export function codexPanel(root, fingerprint) {
+    const digest = captureDigest(root);
+    if (!digest)
+        return [];
+    let files;
+    try {
+        files = readdirSync(directory(root));
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const file of files.filter((f) => /^[a-f0-9]{64}\.json$/.test(f))) {
+        try {
+            const value = JSON.parse(readFileSync(join(directory(root), file), 'utf8'));
+            const score = panelScore(value?.surfaces);
+            if (score && value.kind === 'funpixel-critic' && value.fingerprint === fingerprint && value.capture_digest === digest &&
+                typeof value.agent_id === 'string' && file === `${hash(value.agent_id)}.json` && Number.isFinite(value.at))
+                records.push({ ...score, at: value.at });
+        }
+        catch { }
+    }
+    return records.sort((a, b) => a.at - b.at);
+}

package/plugins/claude/hooks/durable.mjs

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { readState, writeState } from './lib.mjs';
+const git = (root, ...args) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 5000 });
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} };
+export function inTemp(root) {
+    const r = real(root);
+    return [real(tmpdir()), '/tmp', '/private/tmp', '/var/folders', '/private/var/folders'].some((t) => r === t || r.startsWith(`${t}/`));
+}
+export function gitState(root) {
+    const inside = git(root, 'rev-parse', '--is-inside-work-tree');
+    if (inside.error)
+        return { repo: null };
+    if (inside.status !== 0 || inside.stdout.trim() !== 'true')
+        return { repo: false };
+    const status = git(root, 'status', '--porcelain', '--untracked-files=all', '--', '.');
+    const files = status.status === 0 ? status.stdout.split('\n').filter((l) => l.trim()).map((l) => l.slice(3)) : [];
+    const remote = git(root, 'remote').stdout.trim().length > 0;
+    const ahead = git(root, 'rev-list', '--count', '@{u}..HEAD');
+    return { repo: true, files, remote, unpushed: ahead.status === 0 ? Number(ahead.stdout.trim()) || 0 : null };
+}
+export function durableLine(root, st = gitState(root)) {
+    const parts = [];
+    if (inTemp(root))
+        parts.push(`the game lives in a temp folder (${root}), which the system wipes — move it to a folder of its own`);
+    if (st.repo === false)
+        parts.push('the game is not in git — `git init`, commit, and push to a remote so it cannot be lost');
+    else if (st.repo) {
+        const n = st.files.length;
+        if (n)
+            parts.push(`${n} file${n === 1 ? '' : 's'} not committed — commit and push (\`git add -A\`, \`git commit\`, \`git push\`)`);
+        if (!st.remote)
+            parts.push('no remote — push the game somewhere it survives this machine (`git remote add origin …`, then `git push -u origin HEAD`)');
+        else if (!n && st.unpushed)
+            parts.push(`${st.unpushed} commit${st.unpushed === 1 ? '' : 's'} not pushed — \`git push\``);
+    }
+    return parts.length ? `Funpixel: keep the game — ${parts.join('; ')}.` : null;
+}
+export function durableNote(input, root) {
+    if (process.env.FUNPIXEL_GDK_DURABLE === 'off')
+        return null;
+    const state = readState(input);
+    if (state.durableNoted)
+        return null;
+    const line = durableLine(root);
+    if (!line)
+        return null;
+    writeState(input, { ...readState(input), durableNoted: Date.now() });
+    return line;
+}

package/plugins/claude/hooks/fence.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { forHost, isMain, readInput, readState, startDir, writeState } from './lib.mjs';
+import { fence } from './vendor/lanes/fence.mjs';
+export function fenceAnswer(input) {
+    let a = null;
+    try {
+        a = fence({ cwd: startDir(input), agentType: input.agent_type, tool: String(input.tool_name ?? ''), input: input.tool_input ?? {} });
+    }
+    catch {
+        return null;
+    }
+    if (!a)
+        return null;
+    if ('deny' in a)
+        return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: a.deny } };
+    const state = readState(input);
+    const noted = Array.isArray(state.fenceNoted) ? state.fenceNoted : [];
+    if (noted.includes(a.lane))
+        return null;
+    writeState(input, { ...state, fenceNoted: [...noted, a.lane] });
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: a.note } };
+}
+async function main() {
+    const out = fenceAnswer(await readInput());
+    if (out)
+        process.stdout.write(forHost(JSON.stringify(out)));
+}
+if (isMain(import.meta.url)) {
+    main().catch((e) => process.stderr.write(`funpixel fence: ${e instanceof Error ? e.message : e}\n`));
+}