@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-game-spine/references/room-api.md

@@ -0,0 +1,63 @@
+# Room API (`@funpixel/sdk/multiplayer`, SDK 0.7.0)
+
+```ts
+import { Room, getGameKey, RoomError } from '@funpixel/sdk/multiplayer';
+
+// Joining. All static, all return promises.
+Room.autoJoin(getGameKey(), { game, maxPlayers })  // create-or-join this game's room; the first player hosts
+Room.auto({ game, maxPlayers })                    // joins only when the URL has ?room=CODE, else resolves null
+Room.join(code, { username? })                     // an existing room of THIS game, by its 8-character code
+// Room.connect is refused for games (the relay answers FORBIDDEN). Never call it.
+
+// World state for late joiners and reconnects (the host answers)
+room.provideState(() => state)        // host: the snapshot source (the SDK re-asks it on each join)
+room.onState((state) => {})           // everyone: apply a full snapshot
+
+// Continuous own state: sampled 20 Hz, sent on change, never echoed
+room.sync(key, () => ({ x, y }))
+room.onSync(key, (peerId, value) => {})
+
+// Events: delivered to everyone in the room, the sender included
+room.send(name, data)                 // discrete events, a few per second; data is a plain object
+room.sendBuffered(name, item)         // high-frequency lane, batched; receivers get one callback per item
+room.on(name, (peerId, data) => {})   // peerId === room.playerId on your own echo
+
+// Presence and lifecycle
+room.onPlayerJoin((player) => {})     // player: { id, username, isHost }
+room.onPlayerLeave(({ id }) => {})
+room.onHostChange((newHostId, youAreHost) => {})
+room.onDisconnect(() => {}); room.onError((code, message) => {})
+room.onReconnecting((attempt) => {}); room.onReconnect(() => {}); room.onReconnectFailed(() => {})
+room.isHost; room.players /* Map, includes you */; room.playerId; room.code
+room.connected; room.ping; room.maxPlayers; room.playerCount
+room.leave()                          // also stops the automatic reconnect
+```
+
+**Join errors** reject the promise as a `RoomError` with `.code`: `ROOM_FULL`, `NOT_FOUND`,
+`FORBIDDEN`, or an auth failure when no ticket arrived (opened outside a Funpixel host).
+
+**Runtime errors** arrive on `onError`: `RATE_LIMITED` (move that send to `sendBuffered`, which
+throttles itself) and `SUPERSEDED` (this connection was replaced: call `room.leave()` and offer a
+Rejoin button).
+
+**Payload shapes.** `send('score', 5)` arrives as `{ value: 5 }`; an array arrives as an object
+with keys `0, 1, …`. Wrap values: `send('score', { points: 5 })`. Keys and event names starting
+with `_` (`_sync`, `_evt`, `_batch`, `_state_req`, `_state_snap`) belong to the SDK.
+
+**Limits.** 60 messages a second per player plus a burst of 120, the excess dropped silently. A
+state snapshot over about 200 KB is not sent (the SDK logs one warning): keep the world lean.
+
+**Keys.** `getGameKey()` reads the host name: the preview or published game's key on Funpixel,
+`'local'` on `localhost`. Pass it through untouched; never invent or hard-code a key.
+
+## Reconnects and host migration
+
+- **Reconnects.** The SDK reconnects by itself (up to four tries). After it does, the roster is
+  replaced without join or leave events: reconcile peers in `onReconnect`. Pause input on
+  `onDisconnect`, resume on `onReconnect`, show "connection lost" on `onReconnectFailed`; the
+  render loop that was running keeps running (a second one doubles the speed). `SUPERSEDED` means
+  this connection was replaced (another tab of the same account, or the owner removed the
+  player): `room.leave()` then a Rejoin button, since otherwise the SDK reconnects and steals the
+  slot back.
+- **Host migration.** When `onHostChange` says you are the host, register `provideState` and
+  every host-only `sync` again from your local mirror, which is why every client keeps one.

package/templates/common/.agents/skills/funpixel-game-spine/references/room-modes.md

@@ -0,0 +1,40 @@
+# Room modes
+
+Pick one from the design and say which in the design note. The relay offers one thing: this game's
+shared rooms, filled lowest first, with overflow rooms when one is full. A code brings a friend into
+the room you are in. No mode makes a room private, so never promise privacy in copy or UI.
+
+| Mode | When | The player sees |
+|---|---|---|
+| Lobby (default) | Matches with a start: duels, co-op runs, party games | A join button named with the game's own verb, a waiting screen with the players, the host's Start |
+| Invite codes | Playing with friends is the point | Join, plus "Join with code"; the code as a large copyable element; an invite link |
+| Drop-in | A shared world with no matches: a lounge, a sandbox, a persistent board | Nothing: the game joins during loading and others simply appear |
+
+## Lobby
+
+- The primary button calls `autoJoin`; label it the way a player of this world would say it.
+- The host starts the match with `room.send('game_start', {})`; every client starts on
+  `room.on('game_start', …)`, guarded by a local `started` flag.
+- The room code, if shown, carries `data-funpixel-selectable` (or is a real `<input readonly>`), or
+  players cannot copy it.
+- Offline: the solo game, never a dead card. It is what verify sees.
+
+## Invite codes
+
+- Two entries: "Play" (`autoJoin`, which joins this game's shared room) and "Join with code" (a
+  real `<input>` into `Room.join(code)`: uppercase, 8 characters, inline "No room with that code"
+  on `NOT_FOUND` or `FORBIDDEN`).
+- A URL with `?room=CODE` skips the title: `Room.auto({ game, maxPlayers })` joins directly.
+- After joining, show the code large and selectable with a copy-link button writing
+  `${location.origin}${location.pathname}?room=${room.code}`.
+- `ROOM_FULL` on a code join: say the room is full; never drop the player into another room.
+- Game keys stay off while the code input has focus: skip keydown when
+  `e.target instanceof HTMLInputElement`.
+
+## Drop-in
+
+- No lobby, no code, no waiting gate. Call `autoJoin` behind the loading screen and start at once.
+- The world is complete with one player; others appearing or leaving is ambient (a subtle cue,
+  never a modal).
+- `ROOM_FULL`: a small "World is full, retrying" toast and a retry every 10 seconds.
+- Any failure: solo play with one small toast. Sharing is the game's URL itself.

package/templates/common/.agents/skills/funpixel-game-spine/references/sdk.md

@@ -0,0 +1,114 @@
+# The @funpixel/sdk surface
+
+No model was trained on this package, so guessing its API costs a build, and a guess that
+type-checks can do nothing at runtime. This skill is the short list worth using, from the studio's budget
+audit. Everything else the package exports is optional: use
+the web platform (`localStorage`, `requestFullscreen`, `screen.orientation`, the engine's loader
+and tweens).
+
+## Tools
+
+- No MCP tool teaches the SDK; this skill is the reference. `build` or `probe` show whether it
+  works in the platform's browser.
+- Local: `npx @funpixel/tools doctor` warns on an unpinned SDK; `npx @funpixel/tools verify` runs
+  the game.
+- A name error is a lookup: find the name below or in `node_modules/@funpixel/sdk/dist/*.d.ts`.
+  A cast, `?.` or widened type that makes a wrong name compile hides it until runtime, where it
+  does nothing.
+
+## The surface
+
+1. Pin it exactly: `"@funpixel/sdk": "0.7.0"`, no caret. The root export is `setupGameResize`
+   only; everything else comes from a subpath (`/audio`, `/multiplayer`, `/save`, `/liveParams`,
+   `/device`).
+2. **Resize.** `setupGameResize(cb: (width: number, height: number) => void, win?: Window): () => void`
+   from `@funpixel/sdk`.
+   - It calls `cb` once, synchronously, at the call: create the renderer first.
+   - Size from `w, h`, never `innerWidth`; a Studio message can carry a different size.
+   - Remove Pixi `resizeTo: window` and any `resize` listener: they miss iframe resizes, and two
+     resizers fight. Zero and unchanged sizes are dropped. It returns a teardown.
+3. **Audio.** `new AudioEngine(opts?: { ctx?: AudioContext; iosPatch?: boolean })` from
+   `@funpixel/sdk/audio`, with `.ctx`, `.master`, `init()` and `unlock(): Promise<void>`.
+   - The iPhone ringer switch is the game's call. `iosPatch: false` respects it (the switch mutes
+     the game, the casual-game norm, and what a new game passes); `true`, the default for games
+     made before this was a choice, plays through it, for games where sound is the point. Keep
+     an existing game's choice.
+   - Connect every source to `audio.master`: the mute toggle drives it, and under `iosPatch: true`
+     anything on `ctx.destination` is muted by the switch anyway.
+   - `unlock()` latches on its first call even if resuming failed. Call it from `click`,
+     `pointerup`, `keydown` or `touchend` (WebKit did not resume on `pointerdown`); while
+     `audio.ctx.state !== 'running'`, call `audio.ctx.resume()` on the next gesture.
+   - There is no play or load API: decode once with `ctx.decodeAudioData`, one `BufferSource` per
+     hit. One engine per game; a second `AudioContext` escapes the patch.
+4. **Multiplayer**, only when the design is multiplayer:
+   `Room.autoJoin(getGameKey(), { game, maxPlayers })` from `@funpixel/sdk/multiplayer`. The
+   [multiplayer](multiplayer.md) reference has the echo, roster and host-state traps.
+5. **Save.** `new SaveManager<T>({ key, version, defaults, migrations?, onSaveError?, debounceMs? })`
+   from `@funpixel/sdk/save`, with `.data`, `update(partial)`, `flush(): { ok, error? }` and
+   `reset()`.
+   - `update` persists 500 ms later: `flush()` at the end of a run and on `visibilitychange`.
+   - The merge is shallow: a nested object is replaced, not merged.
+   - A corrupt save loads as `defaults`, silently. Migrations are keyed by the target version; a
+     gap stops migration silently.
+   - `onSaveError` fires only on the debounced path: check `flush().ok` and tell the player.
+6. **Live tuning.** `initLiveParams(schema)` from `@funpixel/sdk/liveParams`, where each entry is
+   `{ type: 'number' | 'boolean' | 'color' | 'select', value, min?, max?, step?, options?, name? }`;
+   it returns `get(key)`, `subscribe(key, (v, prev) => …)`, `set(key, v)` and `all()`.
+   - A misspelt key returns `undefined` and the physics become `NaN`.
+   - A value copied into a constant at load never updates: read `get()` in the loop, or subscribe.
+   - A bad schema entry leaves the params empty, silently: check `Object.keys(params.all())`.
+     Values change live only in the Studio preview.
+7. **Safe area on a canvas.** `safeArea.insets(): { top, right, bottom, left }` from
+   `@funpixel/sdk/device` reads zeros unless the CSS sets
+   `:root { --sai-top: env(safe-area-inset-top); … }` for all four sides and the viewport meta has
+   `viewport-fit=cover`. Re-read after rotation. A DOM HUD uses
+   `max(16px, env(safe-area-inset-*))` in CSS instead.
+
+## What not to reach for
+
+| Export | Use instead | Why |
+|---|---|---|
+| `haptics` | `navigator.vibrate?.(ms)` | It is exactly that, and a no-op on every iPhone |
+| `fullscreen`, `orientation` | the platform calls with `.catch()` | The wrapper only swallows the rejection |
+| `Grid`, `findPath` | your own A*, or `easystarjs` | Four-neighbour only and slow on big grids |
+| `fx` shake, pop, flash | a render offset or a tween | Overlapping calls leave the stage offset or tinted for good |
+| `leaderboard()`, `host` | nothing yet | Only the Studio answers; published games wait 1.5 to 2 s for nothing |
+| `gameState()`, `motion`, `preload`, `register` | `SaveManager`, `sensors`, the engine loader | Duplicates, or no host acts on them |
+
+## Worked example
+
+A runner that saves its best distance and tunes gravity live:
+```ts
+import { setupGameResize } from '@funpixel/sdk';
+import { AudioEngine } from '@funpixel/sdk/audio';
+import { SaveManager } from '@funpixel/sdk/save';
+import { initLiveParams } from '@funpixel/sdk/liveParams';
+
+await app.init({ background: '#101018' });          // renderer first: the resize fires at once
+setupGameResize((w, h) => { app.renderer.resize(w, h); game.layout(w, h); });
+
+const audio = new AudioEngine({ iosPatch: false });  // the ringer switch mutes it
+addEventListener('pointerup', () => audio.unlock(), { once: true });
+
+const save = new SaveManager({ key: 'runner', version: 1, defaults: { best: 0 } });
+const params = initLiveParams({ gravity: { type: 'number', value: 1800, min: 600, max: 3000 } });
+if (!Object.keys(params.all()).length) console.error('live params rejected');
+
+function onRunEnd(distance: number) {
+  if (distance > save.data.best) save.update({ best: distance });
+  if (!save.flush().ok) showToast('Could not save your best run');
+}
+// in update(dt): vy += (params.get<number>('gravity') ?? 1800) * dt;
+```
+
+## Common mistakes
+
+- `leaderboard.submit(score)`: `leaderboard` is a factory, so the call throws.
+- A caret on the SDK version: the platform build and your build resolve different code.
+- `import { AudioEngine } from '@funpixel/sdk'`: only `setupGameResize` is at the root.
+- Connecting a sound straight to `ctx.destination`: the mute toggle misses it, and a rhythm game
+  on `iosPatch: true` goes quiet on a silenced iPhone.
+- Treating `safeArea.insets()` zeros as "no notch".
+- Relying on `haptics` for feedback: nothing happens on iPhone, so pair it with a visible cue.
+
+Where this comes from: ours, from the SDK and its budget audit; a few device notes began in our platform prompts.

package/templates/common/.agents/skills/funpixel-game-spine/references/three.md

@@ -0,0 +1,62 @@
+# Three.js contracts
+
+Each of these builds cleanly and breaks the game or the checks when missed. Generated models have
+their own traps: skill `funpixel-3d`.
+
+- Export after setup: `window.THREE = THREE`, `window.__THREEJS_SCENE__ = scene`,
+  `window.__THREEJS_RENDERER__ = renderer` (what `profile` reads), `window.camera = camera`. Verify projects the player through that
+  camera to decide whether it can be seen.
+- Every mesh, group and light gets a `.name`, including loaded model roots
+  (`gltf.scene.name = 'player'`).
+- One loop: `renderer.setAnimationLoop(() => { const dt = Math.min(clock.getDelta(), 0.1); update(dt); renderer.render(scene, camera); })`.
+  With animated models, `mixer.update(dt)` runs every frame or the character freezes in its bind
+  pose.
+- Size by CSS: `renderer.setSize(w, h, false)` plus `canvas.style.width = canvas.style.height = '100%'`;
+  cap `renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5))`, because a pixel ratio of 3 fills
+  nine times the pixels.
+- Decoders are required and same-origin: `DRACOLoader` with `setDecoderPath('/draco/')`,
+  `KTX2Loader` with `setTranscoderPath('/basis/')` and `detectSupport(renderer)` before any load,
+  and `setMeshoptDecoder(MeshoptDecoder)`. Vendor the decoder files into `public/`; without them
+  every model load fails and a fallback cube appears. A missing-module error on one of them means
+  fix the path, never delete the import.
+- Generated models need an environment map (they export metallic materials and render flat grey
+  without one) and tone mapping; with an environment map, cut analytic lights to at most three.
+- Colliders are simple proxies (a capsule, a box you size), never `Box3.setFromObject` on a skinned
+  mesh: the pose inflates it and every clip jitters the hitbox.
+- More copies of a rigged model use `SkeletonUtils.clone`, never `root.clone()`.
+- Instanced scenery: one `InstancedMesh` has one bounding sphere, so it is never culled in parts;
+  split huge fields into chunks.
+- three r186 (the scaffold's) removed `PCFSoftShadowMap`: it silently becomes `PCFShadowMap` with one
+  console warning, so code written for an older three changes its shadow look. Use `PCFShadowMap` and
+  soften with `light.shadow.radius`.
+- Phone budget: about 100 draw calls, at most three lights, no texture over 2048, shadows from the
+  key light only.
+
+## The 3D world starter
+
+`funtools init` gives a 3D line the world starter (`--framework three-world`), one small file per
+concern, each with its numbers in one table you tune rather than rewrite:
+
+- `rules.ts` + `layout.ts` + `bot.ts`: engine-free movement (`MOVE`: run speed, acceleration, air
+  control, a held jump higher than a tap, coyote and buffer 0.1 s, a dash), platforms and pillars
+  from a seed, a sharp bot; Node tests and `test/probes.ts` play them with no frame.
+- `shots.ts` (`SHOTS`) + `camera-rig.ts` (`RIG`): the camera plan as named shots (the title's
+  slow orbit over the play world, play's follow, a beat's `reveal`), each a lens, a height and a
+  distance, blended with `shoot(name, seconds)`; the rig follows with look-ahead on velocity, a ray
+  to the eye that pulls in fast and eases out slowly, and a steady yaw so the stick means the same
+  thing all round; upright phones pull back. `__FPX_CAMERA__` reports the shot and its numbers, so
+  `funtools score --target` prints moves such as `SHOTS.play.height 4.4 → 6.1`.
+- `world.ts` + `palette.ts`: ACES tone mapping, sRGB output, a gradient sky with fog in its horizon
+  colour, hemisphere + one shadowing key light + a cool rim, ground coloured by noise, instanced
+  scatter past the edge, drifting motes. Colours are the CSS tokens, so the UI and the world change
+  together.
+- `models.ts`: a `.glb` at `public/assets/models/<name>.glb` replaces its placeholder with no code;
+  placeholders are designed shapes in the palette and stay listed in `state.art.placeholders`
+  until their model lands. `assets/assets.json` lists them to generate, reference sheets first.
+- `controls.tsx` + `input.ts`: a stick born where the thumb lands, jump and dash in the right
+  thumb's arc, inside the safe areas; keys and a gamepad reach the same verbs.
+- `budget.ts` (`BUDGET`): 120 draw calls, 300k triangles, pixel ratio 1.5 at most, stepping the
+  shadows and then the pixel ratio down on long frames; `state.render` reports them.
+- `screens.tsx`: the title over the orbiting world, banners over a softened world, a stamped ending.
+
+Keep the shape when the game grows: new rules in engine-free files, their numbers in a table.

package/templates/common/.agents/skills/funpixel-gdd/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: funpixel-gdd
+description: Use when starting a game from an idea or in an empty folder (start here, with flow start), planning the whole game, writing or growing its design document (GDD, a design doc; a long game in chapters), or when a request changes the genre, core verb or win condition or asks for a complete game. Covers invention, genre cards, the first look and playable, the release bar and the hand-back.
+---
+
+# Starting and planning a game
+
+A GDD is where a game is decided before it is built, and where the next session or a critic
+learns what it is: a Part 1 that says what the game is and why, a Part 2 whose targets and named
+tests come before code. It is the contract: the owner decides what it holds; inside it, the how is
+yours to invent, and the creator's vision wins over any row here. While the GDD is being written, no gate applies: the template and the lint are a checklist
+to consult at the end, not the order to write in.
+
+One document, `design/GDD.md` (an older `design/README.md` reads the same). The hooks read its `## AD rules`, `## Actors`, `## Juice` and `## Fix round`.
+
+## Starting from an idea
+
+`npx @funpixel/tools flow start` names the next step; the path our complete games took is [references/start.md](references/start.md) and
+[references/the-path.md](references/the-path.md). In short: brief back; the first look (key art,
+the hero's sheet); a first playable from it, which the owner plays; the design around it, locked; then the slice through real input (skill
+`funpixel-verify`); then rounds against the plan's target frames until the owner says yes. A genre
+recipe (`references/genre-<card|platformer|puzzle|racing|rpg|shooter|simulation|strategy|survival>.md`)
+is a starting point; the creator's choices win. The release
+bar our best games shared is [references/floors.md](references/floors.md); the hand-back says what
+plays now with its literal controls, what is not in yet, and the next steps, with every
+stand-in named. An existing game's change goes to skill `funpixel-game-spine`; a missing `verify.json`
+is an evidence gap, not a rebuild.
+
+## Invent first, then fill the template
+
+A plan filled template-first lost 3 of 3 blind seats to one that spent its time on design (one
+game, 1 Oct 2026). The order that won, in [references/invent-first.md](references/invent-first.md):
+
+1. **Six forcing questions**, in `## The invention`: what the core object means, why the verb
+   exists in this world, who wants what by name, what the twist costs in feeling and in play, the
+   one system that lives and reacts to the player, what only this game has. A generic answer means
+   the idea is not there yet.
+2. **A hit per axis** (mechanic, feel, touch controls, layout, surface satisfaction, readability,
+   market), each with take, avoid and a source link, in `## Hits, per axis`.
+3. **The studio pitch**: cards for genre and fidelity, depth, the core that burns, the story
+   standard, extras with their cost; pick each with why; the owner approves them at the lock
+   (`pitch ask` makes each theirs).
+4. **Worth building at this length?** Your numbers' minutes against the owner's target, beside the
+   first playable; recommend dropping a weak idea ([references/worth.md](references/worth.md)).
+5. **Named behaviour tests** in Part 2, before code.
+6. **Our lessons as defaults**: modelled places, a GPU tier, every attack tells, teach once at the
+   element, a camera that never fights the player, controls off the play.
+
+Places that differ, fun with depth, phone controls: [references/level-and-fun.md](references/level-and-fun.md).
+
+## Tools
+
+- `npx @funpixel/tools init <folder> --idea "<one line>"` picks engine, recipe and orientation,
+  seeds `design/GDD.md` and commits the game to git (never a temp folder);
+  `create_game` is for an agent with no local files.
+- `npx @funpixel/tools gdd`: the invention answered or generic, hits per axis, named tests, the
+  locked core, then missing sections; no score, since completeness is not quality.
+- `npx @funpixel/tools pitch`: the studio pitch's cards, picks and lock; `variety --within`: the
+  place pictures against each other.
+- `gdd page`: the living plan page (`design/GDD.html`), agreed a section at a time; `greenlight page`: the lock's. The studio's best pages and pages of its own: references/pages.md.
+- First look: `generate_image`, `generate_sound`, `generate_music` with the game's id; `loudness` measures the
+  cues against their targets. Sign-in: `funtools whoami`, `funtools login`.
+
+## What a great GDD holds
+
+Copy [references/gdd-template.md](references/gdd-template.md) to `design/GDD.md`. What makes each
+section strong is in [references/sections.md](references/sections.md).
+
+1. **The invention, the hits and the studio pitch** (above); **the promise**: one line, the thesis
+   in one frame or number, the 6-second ad; **pillars and decisions** against their alternatives.
+2. **The core loop and its numbers**: the three to five numbers that are the whole game, each with
+   why exactly that value, and the rule that stops the boring optimum.
+3. **The first minute and the hook**: first input by 0:05, a moment ladder, 2 to 4 wow moments.
+4. **Content**: kinds that each bend the core rule and read by silhouette, stages that each add one
+   thing, a climax; a counted content list and an art budget
+   ([references/plan-at-size.md](references/plan-at-size.md)).
+5. **Places and the living world**: each place its own shape, material, era and light, its rule
+   and a picture; one living system with a job in play; a rival whose want is half right ([references/world-and-identity.md](references/world-and-identity.md)).
+6. **Experience**, what stills miss ([references/experience.md](references/experience.md)).
+7. **Look, actors, audio, HUD and screens, juice, controls**: colour as assignment, AD rules
+   checkable in one frame, target frames; a phone mockup with every element numbered.
+8. **Scope, money model, build plan, risks**, and lessons that apply.
+9. **Part 2**: targets and named behaviour tests now; rewritten from the code once it runs, and from
+   then on it wins ([references/as-built.md](references/as-built.md)).
+
+Mid and deep games add `design/spec/`, data the game loads ([references/spec-folder.md](references/spec-folder.md)).
+
+## Design measures: advice
+
+`gdd` ends with six numbers and why: elements per hour (good games: 1.4–3), the spine, sources
+(`gdd --sources`), peers, length totals, Steam's refund window. Advice: you read and decide, the owner
+decides; a field the GDD lacks is not given ([references/design-measures.md](references/design-measures.md)).
+
+## Versions and the track
+
+v0.1 before code, v0.2 after the first look, one per stage or per request bending a pillar. The stages and what each leaves behind: [references/track.md](references/track.md).
+
+## The first look
+
+The key art and the hero's sheet first (the first playable is built from them); then, while
+planning, the whole game: `npx @funpixel/tools firstlook` names its set. Say each paid job's cost. Each piece: [references/first-look.md](references/first-look.md).
+
+**Image tools down?** Tell the owner, keep writing, stand in with marked code-drawn vignettes, and put
+"pictures owed" in `## Open questions`; never fake a picture.
+
+## Worked example
+
+Brief: "paper boats race down a rainy gutter". The boat is a child's message home, so a sunk boat
+loses a line of it; the living system is the rain, a clock that floods the shortcuts.
+
+## Common mistakes
+
+- Filling the template before inventing: complete, clear, forgettable.
+- One genre hit as the whole research; places that differ only in name.
+- Rules as prose instead of test names; a generated frame taken for the game.
+- Calling unfinished stand-ins a deliberate style, or leaving the GDD at its first draft.

package/templates/common/.agents/skills/funpixel-gdd/references/as-built.md

@@ -0,0 +1,40 @@
+# Part 2: the game as built
+
+Part 1 is the plan and its reasons. Part 2, once the game runs, is the game: written from the code,
+not from memory of the plan. From then on, where the two disagree Part 2 wins, and Part 1 is
+corrected or points to the Part 2 section that replaced it. The test of a good Part 2: someone new
+to the game could rebuild it in another engine from Part 2 and the tests alone. The
+team's robot game passed that test: its Unity port matched the web build exactly.
+
+## What it holds
+
+| Part | From the code |
+|---|---|
+| World, step, units | the unit, the fixed step and its cap, the random generator and how it is seeded, the order of one step, the rule that the simulation imports nothing from the renderer |
+| Each actor | every constant with its unit (speed, radius, health, cooldown), its state machine, its tell, strike and recover times, what it emits |
+| Levels as data | the data shape, one real level in it, and the level laws each checked by a test (every room reaches the exit; finishable with no upgrades; resources at least 1.3 times what a median bot uses) |
+| Events and saves | every event the simulation sends the view; the save's fields and version; what a suspend or resume keeps |
+| Performance | frame, draw-call, light, memory and download budgets per device, and how the game degrades before the device does |
+| The behaviour contract | tests named after the rules they pin, a determinism test (same seed, same inputs, same events), bots over several seeds |
+
+## How to write it
+
+- Read the constants file, the step function and the tests, not the design. Copy numbers with
+  their unit and the file they live in.
+- Rewrite rather than patch: a Part 2 that starts as the plan's targets and is edited toward the
+  code keeps plan numbers nobody checked.
+- Keep a drift list: each number where the code and Part 1 differed, which one won, and why. A
+  deliberate change is a decision; an accidental one is a bug to decide on.
+- Name what is not built yet as not built. A planned feature stays in Part 1 until a test or a
+  recorded playthrough shows it running.
+- Write each value beside where it lives (`src/tuning.ts · FUSE_S = 3.0`), a shape a short script
+  can compare to the code on every build (one game checked 213 numbers that way). Where a value
+  moved from its target, "the reason was not recorded" is better than a guessed one.
+- Keep a list of the defects writing the spec found; writing one game's found five.
+- Say what nothing has observed yet (unheard, never played on a phone, fun unproven) and leave the
+  person's own play as a question for them until it happens.
+
+The owner's platformer shows the moment it pays: after the first world was playable, the design was
+rewritten from the code as a port spec, and the bots that walk every level found design bugs (a
+ledge 0.2 units too high, a boss attack you could stand beside and never be hit by) before any
+person played.

package/templates/common/.agents/skills/funpixel-gdd/references/design-measures.md

@@ -0,0 +1,24 @@
+# The design measures
+
+`npx @funpixel/tools gdd` ends with six numbers read off the GDD, each with why and the peers' figures. They come
+from one game's field report (10 Oct 2026), and its owner's rule holds them: "Advise, never gate." Each is advice.
+Read them, decide what to do, and leave the call on the game's size and scope to the owner. A dense, systemic game
+can be the choice; the lint then says "dense: is each element learned (used again after its teach)?", never "too
+many".
+
+A field the GDD does not have is **not given**: no verdict, never a failure. Every field below is optional. Only
+`npx @funpixel/tools gdd --strict` makes a warn fail (exit 1), for a CI that asks for it; nothing in the kit passes
+it.
+
+| Measure | What it reads | The line |
+|---|---|---|
+| Elements per hour | `design/spec/elements.json` (`[{id, kind, name, debut_place, debut_beat_t, uses}]`), else `## Elements`, else the tables under `## Content` (`### Roster` and its kin, the player's row left out) | new mechanics, enemies, tools and systems ÷ first-playthrough hours; good games sit at about 1.4–3 (Prey 1.4, Scorn 2.2, Superhot 2–3); warns above about 4; any element used fewer than twice after its teach is "check by hand" |
+| The spine | `## The spine`: a `Spine:` sentence, clauses split by `;`, and a table of system, the clause it serves (quoted or by number), genre beat | a system that serves no clause warns: one game cut the systems that mapped to none |
+| Sources | every table with a Source column (the identity lock's and the asset script's are pictures, not claims), footnotes `[^n]` with their `[^n]: …` line, `[source?]` markers | a marked claim with no source line warns; "approx, from memory" is kept and listed as secondhand; `gdd --sources` lists them all |
+| Peers | `## Worth against the genre` or `## Peers` | each peer's length and elements per hour: the report's figures where it has them, the GDD's own figure when its row carries a link, else unknown, never guessed |
+| Length totals | the parts' minutes: `design/spec/places/*.json` `target_minutes.first_time`, else a Length column in `## Chapters`, `## Places` or `### Stages` | summed against `Play length:` (or `**Length:**`), the difference shown; warns past 10% (or 2 minutes); the owner's `target_minutes` is shown, never judged |
+| Steam two-hour check | `**Hook at:**`, else a part marked `(hook)` (the hook lands as it begins), else the first timed row of `## The hook`; Steam named in `**Platforms:**` or `store/answers.json` | Steam refunds anything played under 2 h: warns when the GDD's own timeline puts the hook later; a first playthrough under 2 h is told to frame the first ending as one of several |
+
+Elements per hour uses the parts' summed minutes when every part has them (the report's method), else the stated
+length. The peers are games of hours, so a game under an hour reads dense by this rate; say so in the GDD when it is
+the choice.

package/templates/common/.agents/skills/funpixel-gdd/references/design-note.md

@@ -0,0 +1,88 @@
+# The design note
+
+The design note is the game's design document: `design/GDD.md`, from the template in skill
+`funpixel-gdd` (`references/gdd-template.md`), with `/design/` listed in `.harnessignore`. An older
+game's `design/README.md` is read the same way, with `design/gameplay.md` for tables that outgrew
+it; there is one document, never a note and a GDD beside it. A small game fills only the sections
+it needs. It is what the next session and the person read first, so it states decisions, not
+intentions. Update it when a decision changes; a stale note is worse than none.
+
+The hooks and funtools read these parts by name: `**Pitch:**` and `**The 6-second ad:**`, `## Look`,
+`## AD rules` (five numbered rules), `## Juice` (a table with a visual and a sound column), `## Actors`
+(a table with a Motion column), `## Criteria` and, only while a round is unfinished, `## Fix round`.
+`funtools gdd` mirrors every section of the template; `check_plan` grades the older short fields.
+
+What each line is for:
+- **The 6-second ad** keeps the pitch concrete: if nothing in the first seconds would make a
+  stranger tap, the concept needs a sharper hook before it needs code.
+- **Core loop** in one sentence tests the concept: a second "and also" means two games.
+- **Depth** is where a finished level still loses to the genre hit: critics picked the hit for a
+  longer, denser run and a reason to replay. Fill the `Depth:` line under the core loop from bot
+  runs; the options and genre numbers are in the game-logic skill's depth reference.
+- **The first minute** puts the signature on screen early: one game's first cut showed it at
+  3:45, and the fix moved it under 30 s.
+- **Juice** maps actual events to visible responses and explicit audio choices, including silence.
+  Remove inapplicable example rows: a loss or reward tier invented to fill the template is a
+  promise the game then has to keep.
+- **The player's journey** keeps the design about play: every later table serves that walk from a
+  visible start to the first payoff, through controls a stranger can find.
+- **Actors** describes the role, how it moves and its state feedback. Motion is `moves` (seen
+  moving), `animates` (its picture or pose changes) or `still` (it may rest: a board piece, a
+  sign). `scene --motion` samples about a second and judges each actor against that column; an
+  actor it cannot find is reported as not observed, and a still piece and a missing attack
+  response differ.
+- **Fix round** exists only while a round is unfinished: each open panel or player finding by
+  name with its next step. The Stop hook reads it to report an honest unfinished hand-back;
+  delete it when the round is done.
+- **Genre card and adaptation** (the GDD's header) record choices for continuity. Recipes do not
+  restrict the creator; derive the controls and checks from the intended game when no recipe fits.
+- **AD rules** are the art's pass/fail lines. Every prompt is built to satisfy them and every
+  capture is judged against them, so each must be checkable in one frame: a colour count, a line
+  weight, a size at which a thing still reads. "Moody" or "polished" is not a rule. Change one only
+  on purpose, and write the change here first.
+- **Criteria** say what a player must be able to see, each checkable from the running game with no
+  code open: a mechanic, how the run ramps, the feedback on a hit, what tells actors apart, how a
+  newcomer learns the goal. Agents fail most at feedback and presentation (research 15), so two
+  or more of those earn their place. `funpixel.json` takes strings or `{ "id", "kind", "text" }`; `funtools doctor` warns when a
+  made game has none.
+- **Open questions** hold everything you had to guess. Ask them in the hand-back, after the person
+  has played, not before you start.
+
+## Variety moves
+
+Left alone, an agent answers a brief with the average game for it: on one machine, two fresh games
+became a lantern on a night pond, and six shipped the same title card (centred panel, big word, pill
+Play, three round icons) in different colours. When a choice is still open, these are options, not
+steps; whatever the person fixed in their own words (a palette, a genre, a verb, a title) stays.
+One move per game is plenty.
+
+- **Write the obvious game down first,** and the version that only dodges it (darker, cosier,
+  colours inverted). Then pick something that is neither, or keep the obvious one on purpose.
+- **Flip one rule the brief never stated:** the player moves, time runs forward, the screen is lit,
+  the hero is small. Reverse one and see what the game becomes.
+- **Take a spine from another genre:** a racing line through a puzzle, a merge inside a platformer,
+  a rhythm to a builder.
+- **Find the verb outside games** (pour, fold, stitch, sweep, blow, herd) before the stock ones
+  (tap, jump, shoot); it often brings its own feel and sound.
+- **Change the stage, not the subject:** the hour, the material, the scale, the camera.
+- **Let the title screen be the game:** the world or the hero under the name, not a card over a
+  blur.
+
+`npx @funpixel/tools variety` measures the result against the other games on this machine
+(palette distance, core verb and genre, title-screen layout, motif nouns, title words) and names
+what is close; each signal is "not observed" when a side declares nothing. Record a move you made
+with `npx @funpixel/tools decide`, so the next session keeps it. Naming the reflex and flipping one
+rule are ideas from scenario-labs/skills (MIT; THIRD_PARTY_NOTICES.md).
+
+## As-built truth and the runbook
+
+Read [gameplay-contract.md](gameplay-contract.md) when filling the gameplay tables. Values come
+from the simulation constants, not a second independently maintained set of numbers; once the game
+runs, the GDD's Part 2 is written from them (skill `funpixel-gdd`). Label a planned feature
+`planned` until a test or a recorded playthrough shows it running. `check_plan` checks the older
+note fields; a pass does not validate these tables.
+
+Keep `design/runbook.md` as a small table: step, status (`planned`, `active`, `proved`, `blocked`),
+source revision/fingerprint, test or capture path, finding, next action. At session end record the
+literal resume command, outstanding jobs/assets and spend actually recorded. A generated target
+or agent verdict is not the person's approval; link their actual decision or say `not reviewed`.