@pix3/cli 1.6.0

package/kit/files/.claude/skills/pix3-verify/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: pix3-verify
+description: How to check and run a Pix3 change — `pix3 check` / `pix3 validate` / `pix3 read`, the diagnostic codes, reading merge-log entries (the editor kept a human's value over yours), the live channel (`pix3 serve` + `pix3 mcp --workspace`, `game_run` with `expect` hashes, the barrier's answer fields and error codes), and how to report what was and was not verified. Use after every batch of edits to .pix3scene or scripts/*.ts, and before telling the user a change is done.
+---
+
+<!-- Pix3 agent kit 1.6.0 -->
+# Verify a change
+
+Leave files that load and type-check, run the game when the live channel is there, and tell
+the human exactly what to press and what they should see.
+
+## 1. `pix3 check` after every batch
+
+```bash
+pix3 check            # validate (both levels) + tsc over the scripts + merge-log + versions
+pix3 check --json     # the same, machine-readable
+pix3 validate [paths] [--json]   # scenes/prefabs only, no type-check
+pix3 smoke scenes/main.pix3scene # then: run the game headless for 120 frames, report what threw
+pix3 tree [scene]                # outline of a scene (or of the project) instead of reading it
+```
+
+If `pix3` is not on your PATH, run the pinned one from `.mcp.json`: `npx -y @pix3/cli@1.6.0 check`.
+
+Exit code 1 = at least one **error**. Fix every error before reporting; warnings (off-screen
+nodes, zero size, unused assets, out-of-range values) are for judgement.
+
+`--json` answers `{ ok, errorCount, warningCount, files, diagnostics, notes, typecheck,
+mergeLog, kit, … }`:
+
+- `files` — every scene validated and every script type-checked, as
+  `[{ "file": "scenes/main.pix3scene", "sha256": "…" }]` (the key is `file`, not `path`) — the
+  **sha256 of its raw bytes**. These are the hashes `expect` and `pix3 ack --sha256` take.
+- `diagnostics` — one list: `{ severity, code, file, line?, nodeId?, path?, message, fix? }`.
+- `typecheck` — `{ ok, errors, tsconfig, mode, files, typescript, skipped }`; tsc errors are
+  `E_TYPE` diagnostics in the list above; `skipped` says why tsc did not run at all.
+- `mergeLog` — the newest `.pix3/merge-log.jsonl` entries (section 2).
+- `kit` — `{ version, cliVersion, upToDate }`: `pix3 kit --update` when it is stale.
+
+The first `check` on a machine may install TypeScript once into `~/.pix3/typescript/` (it
+prints the `npm install` it runs; `--offline` refuses and prints the command instead).
+
+**A project with its own `package.json` needs `npm install` before `pix3 check` can
+type-check.** Such a project has its own `tsconfig.json` and type-checks against its own
+`node_modules`; without them `check` reports one `E_DEPENDENCIES_MISSING` (fix: `npm install`)
+and skips tsc — the scenes are still validated. Run `npm install` once, then `check` again.
+
+Codes and what they usually mean:
+
+| Code | Usual cause / fix |
+| --- | --- |
+| `E_YAML` | Bad indentation, unquoted `#colour`, a `:` inside an unquoted string |
+| `E_UNKNOWN_NODE_TYPE` | Typo in the node type — use the suggested name |
+| `E_UNKNOWN_COMPONENT` | `user:X` with no exported `class X extends Script` that has `static getPropertySchema()` in `scripts/`; or a `core:` name that does not exist |
+| `E_UNKNOWN_PROPERTY` | Key not read for that node / component — check `pix3-nodes`; a flat `horizontalAlign` belongs in `layout:` |
+| `E_PROPERTY_TYPE` | `"10"` for a number, a colour without quotes, an enum value not in the list |
+| `E_MISSING_RESOURCE` | `res://` path typo, or the asset was never written |
+| `E_MISSING_PREFAB`, `E_PREFAB_*`, `E_DUPLICATE_ID` | Fix the `instance:` path; a prefab file needs exactly one root; ids are unique |
+| `E_EMOJI_AS_ART` | A `label`/`text` that is only emoji — use a sprite or `ColorRect2D` |
+| `E_SVG_INVALID`, `E_SVG_NO_SIZE`, `W_SVG_VIEWBOX_ONLY` | An `.svg` sprite without `xmlns` or without `width`/`height` in px — see the SVG template in `pix3-nodes` |
+| `W_SVG_EXTERNAL_REF` | An `.svg` that links a file, URL or font — it will draw without it; inline it |
+| `E_TYPE` | A TypeScript error in a script (`TS2339: Property … does not exist …`) |
+| `E_TYPECHECK_UNAVAILABLE` | TypeScript could not be installed — run the printed command |
+| `E_DEPENDENCIES_MISSING` | A project with its own `tsconfig.json` and no `node_modules` — `npm install`; tsc was skipped |
+| `W_RUNTIME_VERSION_MISMATCH` / `W_RUNTIME_NOT_INSTALLED` | A project with its own `tsconfig.json` type-checks against its own `node_modules/@pix3/runtime` — `npm install` it at the CLI's version |
+| `W_KIT_OUTDATED` | This kit is older than the CLI — `pix3 kit --update` |
+
+`pix3 validate --help` and `pix3 check --help` list every code. Level 2 of validate compiles
+and loads your scripts to check the properties of `user:` components; with `--no-hydrate` (or
+when scripts cannot be loaded) those are **not** checked — say so if your change depends on them.
+
+### `pix3 smoke` — when no editor is connected
+
+`pix3 smoke <scene>` (after a green `check`) runs that scene in Node: your scripts compiled, the
+scene loaded by the real loader, `--frames N` steps of 1/60 s (default 120). **Name the scene you
+changed** — the game is `pix3 smoke scenes/main.pix3scene`. Input is empty, so a menu never
+presses PLAY: smoking the menu (the build's entry scene) proves nothing about the game. With no
+scene, smoke runs several, one line each and exit 1 if any fails: the top-level scenes your
+uncommitted changes reach (git: the scene, a prefab or overlay it instances, a `user:` script it
+attaches), else — no git, nothing changed, or a change it cannot trace — every top-level scene,
+`scenes/main.pix3scene` first (`--changed` / `--all` force either; `--json` then answers
+`{ ok, selection, reason, runs: [one report per scene] }`). Exit 1 lists every
+`E_SMOKE_SCRIPT` (a hook threw: script, node, frame — 0 = `onAttach`/`onStart` — and a stack
+pointing at your `.ts` line), `E_SMOKE_CONSOLE_ERROR`, `E_SMOKE_UNHANDLED` (a rejected promise
+nobody awaited), `E_SMOKE_DOM` (a browser API the headless run lacks — `domAccess` names it; a
+browser-only feature, not necessarily a bug: say so). `W_SMOKE_MISSING_RESOURCE` is a `res://`
+typo. Exit 2 = it could not run (`E_SMOKE_NO_SCENE`: pass the scene; `E_SMOKE_TIMEOUT`: a loop
+that never ends). Nothing is drawn, heard or tapped: a green smoke run proves the game starts and
+runs without throwing, not that it plays — report it as exactly that, and tell the human what to
+press and what they should see (section 4). With the live channel, `game_run` (section 3) is the
+stronger check.
+
+**No live channel: the fallback, in this order** — `pix3 check` (green), then
+`pix3 smoke <the scene you changed>` (green), then ask the human to press Play in that scene,
+naming what to press and what they should see.
+
+## 2. Merge-log: the editor kept the human's value
+
+The human edits the same files in the editor. When you write a value over one the human set
+after your last read, the editor keeps the human's value and logs it to
+`.pix3/merge-log.jsonl`; `pix3 check` prints the newest entries, e.g.
+`scenes/main.pix3scene  merged: the editor KEPT 1 human value(s) over yours`.
+
+When you see one:
+
+1. `pix3 read <file>` — prints the current file and records that you have read this version
+   (`.pix3/ack.json`).
+2. Decide: is your value still intended given what the human did? If yes, write it again —
+   it now sticks. If unsure, ask the human (that is your one question this turn).
+
+Without step 1 the editor keeps restoring the human's value on every write you make, even if
+you write the same number the human chose.
+
+`check` prints `note: … read confirmation for a version the editor has not recorded — ignored`
+as a note, not a merge-log line: your `pix3 read` named bytes the editor has no record of
+having loaded or written (e.g. a version that was on disk only between two of its polls).
+Nothing was lost and nothing is protected by it; no action unless a KEPT line follows. (`pix3 ack <file> --sha256 <hash>` confirms a
+version whose hash you took from `pix3 check --json` without printing it again.)
+
+## 3. Live channel — run the game yourself
+
+Available when the human runs `pix3 serve` in the project and connects the editor to it
+(File → Connect to Workspace…); your MCP client starts `pix3 mcp --workspace` from `.mcp.json`
+(`pix3 setup claude|codex` prints the registration for a client without it). Without a server
+every tool answers `no_workspace_server`; without a connected window, `no_editor`.
+
+The 14 tools:
+
+- `project_status` — Whether a Pix3 editor window is connected to this project, what it has open, external versions it has not applied yet, unreadable files, merge conflicts and the latest merge-log entries (why a write of yours did not land as written).
+- `play_start` — Enter play mode.
+- `play_stop` — Exit play mode.
+- `play_restart` — Restart play mode.
+- `play_status` — Whether the game is playing, and what the last frame drew (draw calls, visible meshes).
+- `game_run` — Run the game frame by frame until a predicate holds (`until`, OR), fails (`fail`) or a budget runs out, or run a stored routine from design/tests/routines (`routine`, `args`).
+- `game_input` — Send real input to the running game (steps: tap / key / keys / drag / hover / invoke / wait) and report the reaction; `observe` watches nodes over the window.
+- `game_observe` — Read live node state of the running game (by name or id) without sending input.
+- `read_errors` — Recent runtime errors captured in the editor (console.error, window errors, rejections).
+- `read_logs` — Recent editor log entries; `since` (epoch ms) returns only newer ones.
+- `viewport_screenshot` — A screenshot as an image: the running game while playing, else the editor viewport.
+- `generate_asset` — Generate an image with the editor's configured image provider (the user's keys — the editor asks the user to allow this for the session), post-process it and save it into the project.
+- `generate_sfx` — Generate a prototype sound effect (WAV under res://sfx/) with the editor's LLM (asks the user to allow this for the session).
+- `get_selection` — What the human has selected in the editor right now (node ids, primary, hovered).
+
+The loop after a batch of edits:
+
+1. `pix3 check --json` → take the `sha256` of every file you wrote from `files`
+   (`{ file, sha256 }` entries).
+2. A barrier tool — `game_run`, `play_start` or `play_restart` — with
+   `expect: { "<path>": "<sha256>", … }`: the run starts only if the disk holds exactly those
+   versions and the editor loaded them.
+3. Green = no error, `matchesAgent: true`, `matchesDisk: true`, empty `changedDuringRun`. Then
+   `read_errors`, `game_observe` / `viewport_screenshot` to see what happened.
+4. `disk_differs_from_agent` with `mergeLog: true` → the editor merged your file with a human
+   edit: `pix3 read` it (section 2). With `recovery` → someone overwrote it; the named file under
+   `.pix3/recovery/` holds your version. Otherwise write the file again.
+
+### Two ways to prove behaviour
+
+**Every barrier call stops the game and starts it again from the files on disk.** `game_run`
+included: it is always a run from a fresh start, so it can never judge state that an earlier
+`game_input` produced — that state is gone before its first frame. Pick the pattern by what
+causes the behaviour:
+
+- **(a) Autonomous behaviour** (spawns, timers, physics, a HUD that counts on its own):
+  one `game_run` with `expect`, predicates in `until` (any one ends the run as a pass) and
+  `fail` (any one ends it as a failure), e.g. `until:
+  [{ kind: "nodeProperty", name: "ScoreLabel", path: "text", op: "contains", value: "10" }]`,
+  `fail: [{ kind: "newErrors" }]` (a script threw). Read `verdict`, then the result's
+  `newErrors` count, then `read_errors` when it is not 0.
+- **(b) Input-driven behaviour** (taps, keys, combos): `play_start` or `play_restart` with
+  `expect` (the barrier, once) → one or more `game_input` calls → `game_observe` / `read_logs`.
+  `game_input` and `game_observe` are observing tools: they neither stop nor resync, so the
+  state builds up across calls. Do **not** end with `game_run` to "check the result" — it
+  restarts the game.
+
+### `game_input` — what the steps really do
+
+- **Coordinates** (`x`, `y` on `tap` / `drag` / `hover`) are the 2D design space the scene
+  file uses: origin at the **centre**, **Y up**, the same numbers as a node's `position`. With
+  the 2D camera at rest, `{ x: 0, y: 0 }` is the centre of the viewport and the top edge of a
+  1080 x 1920 design is `y: 960` — not `(540, 960)` or `(960, 540)`. Coordinates follow the 2D
+  camera; a node under a `CanvasLayer2D` (a HUD) is pinned to the screen instead, so for HUD and
+  buttons prefer `target: "<node name or id>"`, which projects the node's live position the
+  right way for either.
+- **`tap` holds the pointer down 700 ms by default** (so a `Button2D` sees a real press). For
+  fast repeated hits — a combo window, a rhythm check — pass `holdMs` (e.g. `holdMs: 50`) and a
+  short `wait` between taps; `frames` instead of `ms` / `holdMs` counts game ticks.
+- **One call is capped at 15 s** of requested time (holds + drags + waits); longer answers
+  `Input script too long` — split it into several `game_input` calls.
+- **Input goes through the engine's `InputService`**: `PointerEvent`s on the game canvas and
+  `KeyboardEvent`s on `window`. Scripts that read `this.input` see it. A game that listens for
+  DOM `mouse*` / `click` / `touch*` events, keys on `document`, or on a canvas of its own does
+  **not** — verify such input by hand.
+
+### Reading the answers
+
+- **Barrier answers** carry `revision`, `startupMs` (how long the game took to start),
+  `matchesAgent` / `agentExpectations`, `matchesDisk`, `changedDuringRun`,
+  `editorWroteDuringRun`, `editorChangedSinceAgentWrite` and `result` (the editor tool's own
+  answer). **Observing answers** are `{ revision, stale, result }`.
+- `revision` is the running game's file → hash map: every open scene, every script the build
+  read, `pix3project.yaml` — it can run to hundreds of lines. Check `stale` and the match
+  flags; never paste `revision` into a report.
+- **Labels and HUD text.** An observed node reports its rendered `text` only at the window's
+  **start and end** — `observed.<node>.before.text` / `.after.text` in `game_input`,
+  `nodes.<node>.text` (and `movement.<node>.before` / `.after` with `sampleMs` or `frames`) in
+  `game_observe`;
+  there is no per-frame text timeline. The one-line `verdict` does not count a text change:
+  it can say `NO ACTIVITY` while the label went from `x1` to `x3`. For HUD text, read the text
+  fields, never the verdict alone.
+- **Timing proofs** ("the combo resets after 1 s", "x3 appears on the third hit"): add
+  temporary `console.info('[combo] x3')` markers in the script, note the current epoch ms
+  before the input, run it, then `read_logs` with `since` set to that value — every console line
+  the game prints arrives with its own epoch-ms `timestamp`, so the gaps between markers are the
+  timing. **Remove the markers afterwards** and run `pix3 check` again.
+- **Movement below ~0.5 units reads as `moved: false`**, and a shake that returns to rest
+  inside the window has no endpoint delta at all — a small camera shake is not provable from
+  `moved`. Take a `viewport_screenshot` mid-shake or log the offset with a marker.
+- **Sound**: synthetic input is not a user gesture, so the browser may keep Web Audio
+  suspended; nothing in the answers says whether a sound was heard. Report it as "code path
+  verified, audibility not".
+- **Latency** (measured in trials): observing calls take about 1 s; a barrier call takes the
+  game's startup plus 1–2 s — a small 2D game a few seconds, a heavy 3D game 13–14 s
+  (`startupMs` says which). Batch several input steps into one `game_input` rather than many
+  calls.
+
+The contract, as the CLI documents it:
+
+A stdio MCP server the agent starts from its config (`.mcp.json`, `pix3 setup`). It has no port
+of its own: it finds the running `pix3 serve` of the project (`--project`, else the nearest
+ancestor of the cwd with `pix3project.yaml`) through `.pix3/workspace.json` and confirms it with
+`GET /ws/agent/status` + the control secret. When none runs, every tool answers
+`no_workspace_server` and stderr says ``Workspace server is not running. Run `pix3 serve` in
+<root>``; the next call looks again, so the agent never restarts its MCP server.
+
+**Presence.** While it runs, the process announces itself to that server
+(`POST /ws/agent/presence`, every 10 s and on start/stop; failures are silent and the next beat
+rediscovers a restarted server). That is what tells the editor an agent is attached, so it keeps
+the game, the viewport, file polling and reconnects running in a hidden or unfocused tab instead
+of pausing them for battery (`AgentKeepaliveService`; the user can switch this off in Settings →
+General). `PIX3_PRESENCE_HEARTBEAT_MS` overrides the cadence (tests).
+
+**Tools (v1, exactly):** `project_status`, `play_start`, `play_stop`, `play_restart`,
+`play_status`, `game_run`, `game_input`, `game_observe`, `read_errors`, `read_logs`,
+`viewport_screenshot` (the PNG comes back as an MCP image block), `generate_asset`,
+`generate_sfx`, `get_selection`. No scene-mutating tool: the agent edits files. Schemas are the
+window's (`GET /ws/agent/tools`), with a static fallback so `tools/list` works before a window
+connects (a `notifications/tools/list_changed` follows once a window's schemas are known).
+`play_start` / `play_restart` / `game_run` also take `expect: { path: sha256 }` — the sha256 of the
+raw bytes of every file the agent wrote.
+
+**The sync barrier** (plan §5 D) runs before `play_start`, `play_restart` and `game_run`:
+
+1. **Agent's expectations.** `expect` is checked against the disk (`/ws/agent/expect`) before
+   anything syncs. Any mismatch → `disk_differs_from_agent` with, per file: merged by the editor
+   (`mergeLog: true` — re-read it), or overwritten — with `recovery: ".pix3/recovery/…"` only when
+   a copy with exactly those bytes exists, else "no copy exists — write the file again". Nothing
+   starts. Without `expect` the answer says `agentExpectations: "none"`.
+2. **Editor = disk.** The window's internal `sync_barrier` holds autosave (edits accumulate and are
+   saved after the run), stops play, runs `syncNow()` (waits for the stabilisation window and the
+   script build; re-reads `pix3project.yaml` when the disk holds another version) and returns
+   `{loaded: {path: sha256}, errors}` — every open scene/prefab (any path), every source the last
+   script build read (the entry scripts **and every module the bundle pulled in**, e.g. `src/**`;
+   the hash recorded when the build read it, so nothing is re-read) and `pix3project.yaml`. An open
+   scene the editor holds no disk version of is a `load_failed` error, never silently left out. The
+   MCP process gives this call 100 s. These hashes (plus `expect`) are compared with `/ws/agent/hash` at that moment;
+   a mismatch retries the editor's sync for up to ~5 s. Then: loader/compiler errors →
+   `load_failed` (`{file, line, message, kind}`); a file that stays unreadable →
+   `pending_external`; hashes that never agree → `sync_timeout` with the differing paths. The
+   window then starts the game (`game_run` starts play itself; `play_restart` of a stopped game is
+   a start) and answers only once the game is actually running: up to 30 s, as soon as it runs,
+   failing fast (`load_failed` with the play-mode error) when play mode stops instead; `startupMs`
+   says how long the start took (always present in the answer: `null` means no start happened —
+   `game_run` found the game already running — never "0 ms"). The MCP process gives the tool call 120 s (the server's cap). The
+   hold is released (`sync_release`) after the run.
+3. **After the run** (for `game_run` when it finished; for `play_start` / `play_restart` right
+   after the start was acknowledged) the verified files are hashed again and
+   `/ws/agent/changes?since=<seq of the verification>` is read: `changedDuringRun` and
+   `editorWroteDuringRun`.
+
+The answer of a barrier tool:
+
+```json
+{
+  "revision": { "<path>": "<sha256 of the verified version>" },
+  "startupMs": 8123,
+  "matchesAgent": true,
+  "matchesDisk": true,
+  "changedDuringRun": [],
+  "editorWroteDuringRun": [],
+  "editorChangedSinceAgentWrite": [],
+  "result": { "…": "the editor tool's own result" }
+}
+```
+
+`startupMs` is always present: the milliseconds from the start request until the game was
+running, or `null` when no start happened (the game was already running, so there was nothing to
+measure). `matchesAgent` is `null` (with `agentExpectations: "none"`) without `expect`; `matchesDisk` is
+whether every verified hash still matched the disk at the final check; `changedDuringRun` is what
+the barrier did not verify: every file changed meanwhile by someone other than the editor, plus
+every verified file whose hash moved between the two checks with no editor write on record
+(`changeLogIncomplete: true` when the server's ring did not reach back); `editorWroteDuringRun` is
+every file whose only changes since the verification are the editor's own writes through the file
+API (e.g. a run report under `design/tests/reports/`) — known to the server, so not a
+detection. Both list files only, never directories; `editorChangedSinceAgentWrite` is
+the `expect` paths the merge log says the editor wrote after the check. **A green answer without
+marks means: at start disk = agent's expectations = verified version; at the final check the
+verified hashes match disk; detected changes are listed.** It does not mean the disk did not change
+during the run: `v1 → v2 → v1` between the two checks is invisible, and the game reads resources
+lazily.
+
+**Observing tools** (`play_status`, `game_input`, `game_observe`, `viewport_screenshot`,
+`read_errors`, `read_logs`) neither stop nor sync: `{ revision, stale, result }`, where `revision` is
+what the running game was verified against (`null` when play was not started through the barrier)
+and `stale: true` when the editor saw an external change during play or a `revision` path's disk
+hash moved since. Other tools (`project_status`, `play_stop`, `get_selection`, `generate_*`) answer
+with the editor's result as is. `project_status` without a window answers
+`{ connected: false, server, editor: null, message }` (not an error).
+
+**Error codes** (every error is `isError: true` with `{ "error": "<code>", "message", … }`):
+
+| Code | When |
+| --- | --- |
+| `disk_differs_from_agent` | Step 1: the disk does not hold the `expect` versions (`differing[]` with `recovery`, `mergeLog`, `hint`). |
+| `sync_timeout` | Step 2: the editor's loaded hashes did not match the disk within ~5 s (`differing[]` with `loadedHash` / `agentHash` / `diskHash`). |
+| `load_failed` | Step 2: the loader or the script compiler failed on the current files, or an open scene has no verified version (`errors[]`). At the start: the game was not running within 30 s, or play mode stopped (`result` carries it, with `startupMs`). |
+| `pending_external` | Step 2: a file stays unreadable (partial / invalid write); the editor keeps its last good version. |
+| `no_editor` | No window holds the lease, it did not answer (`reason: "no_reply"`), or it lost the lease mid-call (`reason: "lease_lost"`). |
+| `permission_denied` | `generate_*`: the human denied, or did not answer within 60 s. |
+| `no_workspace_server` | No `pix3 serve` runs for the project root. |
+
+Anything else the editor refuses (`unknown_tool`, `agent_disabled` when the human switched the
+channel off) is passed through as the editor wrote it.
+
+**Generation permission.** The first `generate_asset` / `generate_sfx` of a connection (server
+session + lease + `pix3 mcp` process) opens a prompt in the editor naming the process and what it
+calls itself (unverified); the call waits up to 60 s. Allowed → 20 generations, then it asks again.
+In memory only: a reconnect, a new `pix3 serve` run, a lease takeover or a new `pix3 mcp` process
+resets it; the status-bar Agent pill has a revoke button and switches the channel off.
+
+### MCP configuration
+
+`pix3 new` and `pix3 kit` write the project's `.mcp.json` (Claude Code's project format), **pinned
+to the CLI version that wrote it** — never a bare `@pix3/cli`:
+
+```json
+{ "mcpServers": { "pix3": { "command": "npx", "args": ["-y", "@pix3/cli@<X.Y.Z>", "mcp", "--workspace"] } } }
+```
+
+`pix3 setup [claude|codex]` prints (never runs) the registration for a project without one:
+`claude mcp add pix3 -- npx -y @pix3/cli@<X.Y.Z> mcp --workspace` (run in the project folder), and
+for Codex a `~/.codex/config.toml` block — `[mcp_servers.pix3]` with `command`, `args` (plus
+`--project <root>`, since that config is global) and `tool_timeout_sec = 180`. The Codex keys are
+the ones `tools/pix3-agent-bridge` passes to `codex exec -c mcp_servers.pix3.*`; the file form is
+best-effort, check `codex mcp --help` of your Codex version.
+
+**Dev mode.** From a checkout of the pix3 repo (the CLI runs from `packages/pix3-cli/src/`), or
+with `PIX3_CLI_DEV=1`, both write `node <repo>/packages/pix3-cli/src/index.ts mcp --workspace`
+instead, so the channel can be tried before that version is on npm. `PIX3_CLI_DEV=0` forces the
+pinned form.
+
+## 4. Report honestly
+
+A file that passes `check` loads and compiles. It is not a game that works. End the turn
+with:
+
+- what you changed (files), and whether `pix3 check` was green;
+- whether you ran it (the barrier answer, and which pattern: `game_run` predicates or
+  `game_input` + observed text / log markers) — or **what the human should do to see it**:
+  "press Play in `scenes/main.pix3scene`, tap the gold stars — the combo label top-right should
+  count x2, x3";
+- what you could not verify (feel, audibility, small shakes, anything the channel cannot see);
+- placeholders you left — art (`ColorRect2D`, tinted PNGs, hand-written SVGs) and sound. A sound
+  you made with `pix3 sfx` is a real `.wav`, not a placeholder in the file sense, but say it is a
+  synthesised stand-in and that you could not listen to it.
+
+If the human reports an error from the editor, ask for the exact text (the editor's console
+or the load error shown on the scene), fix the first one, and check again.
+
+## Known gaps
+
+- `pix3 check` shows the newest merge-log entries, not only the ones since your last write —
+  compare their age with when you wrote.
+- The barrier verifies the open scenes and the built scripts; prefabs and assets the game loads
+  lazily are only caught afterwards, in `changedDuringRun`.
+- `.pix3/kit-manifest.json` (how `pix3 kit --update` knows which files are still the kit's) is
+  in the gitignored `.pix3/`: on a fresh clone every kit file counts as edited and is skipped.

package/kit/files/.claude/skills/pix3-verify/reference.md

@@ -0,0 +1,21 @@
+<!-- Pix3 agent kit 1.6.0 — generated from docs/pix3-specification.md. Do not edit: pix3 kit --update regenerates it. -->
+# What the editor does with your files
+
+The engine specification's own statements, for when something surprises you. `SKILL.md`
+beside this file is the practical version. Source paths quoted here (`src/…`, `packages/…`) are files of the Pix3 engine repository, not of this project.
+
+## Strict profile — what `pix3 validate` checks
+
+**Strict profile — `pix3 validate`.** The loader stays forgiving (above); strictness lives in the CLI (`packages/pix3-cli/src/validate/`), which reports every problem as `{severity, code, file, nodeId?, path, line?, message, fix?}` (`--json` adds the sha256 of each validated file; exit code 1 on any error). Level 1 reads files only — no project code, no DOM: document/node/component shape, `type:` vocabulary, property keys and values, `core:` component config, `user:` components by existence (a file under `scripts/` with `extends Script` exporting that name), `res://` targets, prefab targets/cycles/roots, override targets, duplicate ids, emoji-as-art. Level 2 (on unless `--no-hydrate`) hydrates the scene with the real `SceneLoader` in plain Node (`@pix3/runtime/node`: canvas-only `document` shim, disk `ResourceManager`, existence-checking `AssetLoader`) after compiling the project scripts with native esbuild, and reports loader rejections/warnings, still-pending components, `user:` config keys against the compiled schema, and the renderability lint as warnings. "Unknown property" is decided by the **disk format**, not by `getPropertySchema()`: `packages/pix3-runtime/src/core/scene-disk-format.ts` lists, per node type, which keys the loader reads under `properties:` (flat schema names, `transform`/`layout`/`flow`/`material`/`stateTextureKeys` nesting, per-type extras and read-compat aliases), and `scene-disk-format.spec.ts` pins it against what `SceneLoader` actually honours and what `SceneSaver` actually writes. There are no scene-format migrations today: `version` other than `1.0.0` is only a warning.
+
+## Co-authoring mode — the editor's side of a shared folder
+
+- **Co-authoring mode (an external agent writes the same folder)** — plan `.plans/external-agent-authoring.md` §4.3/§5 C; code in `src/services/project/coauthoring/` + `autosave/`. Promise: a manual edit is never lost for good and never overwritten silently. (1) **Autosave** (`AutosaveService`): ~1 s after the last committed operation every dirty open `res://` scene is saved through `SaveSceneOperation` (`quiet`, invoked with `origin: 'system'`, never pushed to history). On for `workspace` projects, for local/browser folders with an agent kit (`AGENTS.md` at the root or a `.pix3/` directory, detected at open) or with the **Settings → General → Autosave scenes in local project folders** switch (`ui.autosaveLocalProjects`); never for cloud. Only the owner window saves (`ProjectOwnershipService`: workspace lease holder, or the Web Lock `pix3-project:<projectId>` holder — a second window queues for the lock; no lock API = owner). Held while that scene has a pending external version or a pointer gesture is in progress (`GestureStateService`). Status-bar pill: On disk / Autosave… / Saving… / Waiting for disk / Autosave off, plus **Stale** while play mode defers an external change. (2) **Pre-write check** (`SaveSceneOperation`): the file's current sha256 — always of the **raw bytes** (`coauthoring/disk-version.ts` → `readDiskVersion`; a BOM or CRLF is part of the hash, exactly as `pix3 serve` / `pix3 read` compute it) — must equal the version the editor last read or wrote (`SceneDiskStateService`, `path → {hash, genAtWrite}`, recorded by `LoadSceneCommand`, `ReloadSceneOperation` and every save); otherwise nothing is written, the path is reported to the external-change path and the outcome is `external-change` (the scene stays dirty; autosave retries after the reload). For workspaces the server's `If-Match` refusal (`WorkspaceConflictError`) maps to the same outcome. The dirty flag clears only after the write and only if no operation completed meanwhile. (3) **Recovery journal** (`RecoveryJournalService`): before every scene write, and before a reload replaces a dirty graph, the manual version goes to `.pix3/recovery/<encodeURIComponent(path)>/<ISO stamp with - for :.>-<hash8>.pix3scene`; ring per project of 200 versions / 7 days (the newest version of a scene never ages out), consecutive duplicates skipped; if `.pix3/` cannot be written (or the project is cloud) the versions go to IndexedDB. `.pix3/` is excluded from exports (`NON_SHIPPABLE_DIRECTORIES`), from FileWatch/workspace change dispatch and from `fileRefreshSignal` bumps. (4) **Protected set `P`** (`ProtectedSetService`): every operation pushed to history with origin `user`, and every undo/redo, is recorded via `recordHumanOperation` as the difference between the saved-form document before and after it (`external-merge/human-operation-diff.ts` — disk paths such as `properties.transform.position`, `components/@id/config/<key>`, whole-node create snapshots with `{parent, prevSibling}`, subtree tombstones on delete, LCS-based moves); reloads (tagged `NON_HUMAN_OPERATION_TAG`), `origin: 'external' | 'system'` and history-less operations only move the baseline. Persisted by the owner, debounced, to `.pix3/protected.json` = `{ format: 1, scenes: { <path>: ProtectedSetData } }`; every save records `(hash, genAtWrite)` via `recordEditorWrite`, and so does every version the editor accepts from disk as is — scene load and a plain reload, at the current gen (`SceneDiskStateService.acceptVersion` → `ProtectedSetService.trackAcceptedVersions`) — so a `pix3 read` of the bytes the editor opened is a known version, not `ack-unknown`. (5) **Stabilisation** (`ExternalChangeService`): a reported change (poll, push, refused pre-write check) is accepted when two snapshots (size + sha256) 300 ms apart match; files that change within one quiet window are delivered together to `onExternalBatch`, which the editor shell hands to `ExternalMergeService.handleBatch` (7); own writes are recognised by hash; a scene that does not parse (or that the loader rejects) keeps the last good graph, holds autosave for that path and after ~5 s logs "File not readable: …"; during play the change is detected but deferred (`coauthoring.stale`). FileWatch polls every 1 s while the document is **visible**, focused or not, and keeps polling during play. (6) **`ProjectSyncService.syncNow()`**: immediate scan (workspace manifest re-scan, or a poll of watched files + script sources vs. the last build), reports every open scene whose bytes differ, waits for the window to settle and for `ProjectScriptLoaderService.ensureReady()`, and returns `{ path: sha256 }` of the versions it holds. (7) **Merge instead of reload** (`ExternalMergeService`): the owner window reads `A` once as bytes and runs `mergeExternalVersion({ E, A, P, acks, externalHash, typeResolver })`, where `E` is the last version the editor wrote or accepted (`SceneDiskStateService.getEditorVersion`, set by load, accepting reloads and every save). Empty `P` and no acks → plain reload from `A` (fast path); `clean` with `M == A` → reload from `A`; `clean` otherwise or `conflicts` → journal the human version (`before-external`), reload from `M` (dirty), write `M` back through `SaveSceneOperation` (pre-write check), `conflicts` also opens the banner; `rejected` → the last good graph stays, nothing is written, the path is **held for a decision** (autosave waits) and a whole-scene banner offers *Accept agent's version* (reload `A`, release all of `P`) / *Keep mine* (`SaveSceneOperation({ overwriteExternalHash })` over exactly that version; the agent's file is journaled first). A non-owner window never merges — it reloads the disk. Every reload is non-destructive (selection kept by id — `ReloadSceneOperation` prunes only vanished ids; the camera state and the scene tree's collapsed ids are keyed by id and untouched; the viewport reconciles proxies incrementally), clears undo history and logs "… was changed outside Pix3 and reloaded — undo history was cleared", and highlights changed nodes in the scene tree for ~3 s (`coauthoring.recentlyChangedNodeIds`, class `tree-node__content--external-change`). (8) **Acks and merge log**: `.pix3/ack.json` = `{ acks: [{ path, sha256, at }] }` written by `pix3 read <path>` (prints the bytes, acks their hash) / `pix3 ack <path> --sha256 <h>`; `AckService` watches this one `.pix3/` file explicitly (2 s poll while visible; workspace push is let through `FileWatchService`), the merge re-reads it and passes that path's hashes as `acks`; `consumedAcks` are removed from the file (one-shot). Each `MergeLogEntry` (merge / ack-applied / ack-unknown, `mergedHash` stamped after the write) and each editor decision (accept-agent, keep-mine, restore-version) is appended by the owner to `.pix3/merge-log.jsonl` as `{ at, file, ... }`, a ring of 500 lines. (9) **Banner and restore** (`pix3-merge-banner`): "Agent changed N properties you edited in <scene> — yours were kept." with *Accept agent's version* (all), *Details* (each conflict: yours → agent's, per-item *Accept*) and *Restore my version before the agent's changes*. Accept = `AcceptAgentVersionCommand` → `AcceptAgentVersionOperation`: `acceptAgentVersion(P, conflicts)` then re-runs the merge of `A` against the released set, installs the result as a new graph instance; undo swaps the previous instance back (`SceneManager.setActiveSceneGraph(…, { disposePrevious: false })`) and restores `P`. Restore = `RestoreRecoveryVersionCommand` → `RestoreRecoveryVersionOperation`: a journal version as one undoable graph swap whose differences are recorded into `P` as one human operation. Right-clicking a scene/prefab tab (`LayoutManagerService.subscribeEditorTabContextMenu` → `pix3-recovery-menu`) offers *Restore my version…* over the last 10 journal versions. (10) **Second window**: a non-owner window is view-only — `CommandDispatcher` refuses every command outside a small allowlist (load/reload/prefab refresh, selection, `viewport.*`, `game.*`, `editor.open-*`; undo/redo and saves are refused) and sets `coauthoring.editBlockedAt`; local folders show "Project is being edited in another window — [Take over]" in `pix3-workspace-banner` (workspaces keep the lease banner). Take over (`ProjectOwnershipService.requestTakeOver`) posts on `BroadcastChannel('pix3-project:<id>')`; the owner runs its release hooks (`AutosaveService.handOver` = flush + journal whatever stays dirty; `ProtectedSetService.flush`), goes view-only and releases the Web Lock (the requester is queued first) and re-queues; no answer in 3 s → `steal: true`.
+
+## Live agent channel — the editor's side of `pix3 mcp --workspace`
+
+- **Live agent channel (`pix3 mcp --workspace`)** — plan §5 D over the workspace backend; wire contract in `packages/pix3-cli/README.md` ("Agent lane", "`pix3 mcp --workspace`"). The agent's stdio MCP server finds the project's running `pix3 serve` through `.pix3/workspace.json` and relays every tool through the server's control-secret agent lane (`/ws/agent/*`; bearer tokens and `Origin`-bearing requests refused) to the lease-holding window, where `WorkspaceAgentToolBridge` (`src/services/project/workspace/`, registered by the editor shell into `WorkspaceSessionService.setCallHandler`) executes exactly 14 tools through `AgentToolRegistry.execute` — `project_status`, `play_start/stop/restart`, `play_status`, `game_run`, `game_input`, `game_observe`, `read_errors`, `read_logs`, `viewport_screenshot` (image block), `generate_asset`, `generate_sfx`, `get_selection` — plus internal `sync_barrier` / `sync_release` / `tools_manifest`; no scene mutation. `play_start` / `play_restart` / `game_run` pass the **sync barrier**: `expect` hashes vs. disk (`disk_differs_from_agent`, with a `.pix3/recovery/` copy only when one exists), then `sync_barrier` (`AutosaveService.hold`, stop play, `ProjectSyncService.barrierRevision()` = `syncNow()` + every open scene/prefab + every source the last script build read, entry scripts and bundled modules alike, with the hash the loader recorded while reading + `pix3project.yaml`, re-read by `syncNow()` when the disk moved) compared with disk hashes for ~5 s (`sync_timeout` / `load_failed` / `pending_external`), run — a start answers once the game is actually running (≤ 30 s, fail-fast when play mode stops, `startupMs` in the answer) — and a second hash + change-log check (`changedDuringRun`; the editor's own file-API writes go to `editorWroteDuringRun`); the verified hashes become `coauthoring.playRevision`, which observing tools report with `stale`. `generate_*` ask the human once per connection (server session + lease + MCP process, 60 s, then `permission_denied`), 20 generations per allowance, revocable from the status-bar **Agent** pill (`pix3-agent-channel-indicator`), which also switches the channel off. `pix3 new` writes a pinned `.mcp.json`; `pix3 setup [claude|codex]` prints the registration.
+
+## Workspace backend — `pix3 serve`
+
+- **Workspace backend (pix3 serve)**: a project folder on another machine (VS Code Remote SSH) or one the browser cannot pick is opened over HTTP + WebSocket instead of File System Access. `pix3 serve` (`packages/pix3-cli/README.md` is the wire contract) serves one root on loopback with a pairing token; **File → Connect to Workspace…** (also on the welcome screen) takes the address — whatever local port the forward uses — and the token. The project then has `backend: 'workspace'`, and `ProjectStorageService` routes every read/write through `WorkspaceClient` (`src/services/project/workspace/`): listings and mtimes come from the server manifest (patched by the client's own mutations and pushed events), reads revalidate with `If-None-Match`, every write carries `If-Match` = the hash of the bytes this editor last read or wrote plus an `X-Mutation-Id`, and a `409 base_mismatch` becomes a `WorkspaceConflictError` — never a silent overwrite of an agent's edit. `WorkspaceSessionService` runs `/ws/events` (auth frame first, token never in the URL): pushed `change` batches go into `FileWatchService.notifyExternalChange`, i.e. the same listeners the FSA poller drives, so an open scene reloads through `ReloadSceneCommand` exactly as for a local folder; a reconnect re-scans the whole manifest; the edit **lease** decides which window may write (another holder → read-only banner with **Take over**); the granted `leaseId` is kept per `workspaceId` in `sessionStorage`, so a reloaded tab resumes its own lease inside the server's grace — or, when the new page connects before the old page's socket closed, the server moves the lease to the socket presenting the holder's `leaseId` (`lost {reason: 'resumed_elsewhere'}` on the old one); a stored id is presented only on a reload or after the old page's `pagehide` marked it, so a duplicated tab never takes it (a second tab never shares it), and a `busy {inGrace: true}` answer is retried after `hello.leaseGraceMs` (+500 ms; 11 s fallback) until granted or held by a connected window. The co-authoring bookkeeping under `.pix3/` (protected set, merge log, recovery journal, acks) is read and written through the same routes and listed by the manifest, but stays out of the revision and of change events (except `.pix3/ack.json`); only the server's own `.pix3/workspace.json`, `serve.lock`, `tmp/`, `link/` are refused. The protocol version is `WORKSPACE_PROTOCOL` (`workspace-protocol.ts`), refused on mismatch. The token lives in IndexedDB keyed by `workspaceId`; the recents entry stores `{ backend: 'workspace', endpoint, workspaceId }` and reopens with one click, and a rejected token or dead server opens the connect dialog — never a folder picker. Refused for a workspace in this slice: picker-based Save As, cloud/hybrid sync, Open in IDE.

package/kit/files/AGENTS.md

@@ -0,0 +1,203 @@
+<!-- Pix3 agent kit 1.6.0 — written by `pix3 kit`. You may edit it: `pix3 kit --update` never overwrites a kit file you changed. -->
+# AGENTS.md — Pix3 game project
+
+This folder is a **Pix3 game**: a 2D/3D browser game. You edit it by writing files. A human
+has the same folder open in the Pix3 editor, moves things with the mouse and presses Play;
+the editor saves their edits to the same files. The files are the whole contract.
+
+If it started from a **recipe** (`design/recipe.md` exists), it is a game that already plays.
+Change it; do not rebuild it.
+
+## Read first
+
+1. `design/recipe.md` (if present) — the map: stable node ids, tunables with ranges, extension
+   points, what must not be touched. It speaks in the in-editor agent's tool names; translate
+   them with the table in `.claude/skills/pix3-scene-format/SKILL.md` ("Recipe tool names").
+2. `README.md` — file layout of this project.
+3. The one scene or script you are about to change. Nothing else. Do not survey the repo.
+   To find it, and to find your way inside it, use `pix3 tree` (every scene and prefab with
+   node counts, types and components) and `pix3 tree <scene>` (one line per node: id, type,
+   position, size, layout, components, prefab instances; `--types Label2D,Button2D`,
+   `--depth 2`, `--props`) — not a read of whole scene files. Read the file itself right
+   before you edit it (rule 2).
+
+## Layout
+
+The layout is **whatever this project has** — do not assume folders. Three rules hold everywhere:
+
+- **Scenes**: find them with a glob `**/*.pix3scene` outside `node_modules/` (and `.pix3/`).
+  `defaultExportScenePath` in `pix3project.yaml` names the build's entry scene.
+- **`res://` is always relative to the project root** (the folder with `pix3project.yaml`), so
+  `res://src/assets/textures/x.png` is as normal as `res://sprites/x.png`. Copy the style the
+  scene you are editing already uses.
+- **Scripts** live under `scripts/**` or `src/scripts/**` (the only two roots the editor and
+  `pix3 check` scan). `export class X extends Script` → `type: user:X`.
+
+`pix3project.yaml` is the manifest (do not edit unless asked); `.pix3/` is editor + CLI
+bookkeeping (recovery journal, merge log, script types) — never edit it.
+
+Example — the layout a **recipe** project (`pix3 new`) ships; other projects differ:
+
+| Path | What |
+| --- | --- |
+| `scenes/*.pix3scene` | Scenes |
+| `scenes/ui/*.pix3scene` | Full-screen overlays (result card, modal), one file each, instanced hidden |
+| `scenes/prefabs/*.pix3scene` | Prefabs: a scene file with exactly ONE root node (a top-level `prefabs/` works too) |
+| `scripts/*.ts` | Script components |
+| `sprites/`, `audio/`, `fonts/`, `models/` … | Assets, referenced as `res://sprites/x.png` |
+| `design/` | Recipe contract, GDD, tests. `design/tests/` is written by the editor's harness |
+
+## The five rules
+
+1. **Playable change first, questions after.** Make the change the user asked for, in the
+   smallest form that plays, before asking anything. Choose small things yourself (a shade, a
+   speed, a count) and say so in one line. At most ONE question per turn, and only about a
+   fork that changes structure ("win by score or by time?"). Never open with a question.
+2. **Re-read a scene before you edit it.** The human may have changed it in the editor a
+   minute ago. Edit the lines you mean to change (search/replace), never regenerate a whole
+   scene from memory. After writing, if `pix3 check` lists **merge-log** entries where the
+   editor KEPT the human's value instead of yours, re-read the file with `pix3 read <file>`
+   (that is your read confirmation); if your value is still intended, write it again — or ask
+   the human. Without that re-read the editor keeps restoring the human's value on every
+   write you make, even if you write the same number.
+3. **Leave layout, colours and fine-tuning to the human.** If asked "a bit more to the left",
+   do it, then offer: "you can drag it in the editor — it saves on its own".
+4. **Run `pix3 check` after every batch of edits** and fix every error before you say "done".
+   It checks YAML, node types, properties, `res://` paths, prefabs, components, and
+   type-checks your scripts (tsc). With the live channel connected (MCP, below), then run the
+   game with `game_run` (or `play_restart`), **passing `expect`** — the sha256 of every file you
+   wrote, as `pix3 check --json` prints them under `files`. An answer with
+   `disk_differs_from_agent`, or a non-empty `changedDuringRun`, is not green.
+   **No editor connected?** `pix3 check`, then `pix3 smoke <the scene you changed>` — the
+   game is `pix3 smoke scenes/main.pix3scene`; the menu never presses PLAY headless, so a
+   smoke of the menu says nothing about the game. It runs that scene in Node for 2 s
+   (`--frames N` for more) and exits 1 on any script throw, `console.error` or unhandled
+   rejection, naming script, frame and source line. With no scene it runs several, a line
+   each: the scenes your uncommitted changes reach (git), else every top-level scene, game
+   first. Green means nothing threw; it does not mean it plays (nothing was tapped or drawn)
+   — so then tell the human what to press and what they should see.
+5. **Art: placeholder → SVG → `generate_asset`, never emoji.** Placeholder = `ColorRect2D`, or
+   a near-white PNG in `sprites/` tinted with a `core:tint` effect. Better art = an SVG you
+   write into `sprites/` — it works on a `Sprite2D` when the root has `xmlns` plus px
+   `width`/`height`; `pix3 validate` checks it (`E_SVG_*`); template in `pix3-nodes` — or
+   `generate_asset` through the live channel. A label/text that is only emoji is
+   refused — emoji are not art. List every placeholder you leave.
+
+## YAML essentials (`.pix3scene`) — details in `pix3-scene-format`
+
+```yaml
+version: 1.0.0
+metadata: { description: 'what this scene is' }
+root:
+  - id: game-root                  # unique in the scene; never rename an existing id
+    type: Group2D                  # exact node type name; a typo loads as an inert node
+    name: Game Root
+    properties:
+      width: 1080
+      height: 1920
+      transform: { position: [0, 0], scale: [1, 1], rotation: 0 }   # 2D, rotation in degrees
+    components:
+      - id: game-rules
+        type: user:GameRules       # user:<ExportedClassName> or core:<Builtin>
+        enabled: true
+        config: { targetScore: 18 } # keys = the script's schema names
+    children:
+      - id: result-overlay         # prefab/overlay instance: NO type, NO components
+        name: Result Overlay
+        instance: res://scenes/ui/result.pix3scene
+        properties: { visible: false }
+```
+
+- The sample assumes a 1080×1920 portrait 2D root; yours may not have one. Read
+  `viewportBaseSize` and `projectType` in `pix3project.yaml` first; a `3d` project may have loose
+  top-level 2D nodes (HUD) with no 2D root at all. Place new HUD relative to the HUD nodes that
+  already exist (same parent, same anchoring), not to an assumed screen size.
+- 2D space: design pixels, origin at the screen centre, **X right, Y up**. `position` is the
+  node's centre. Tree order is paint order: later/deeper draws on top.
+- **Quote every colour**: `color: "#141a2e"`. Unquoted, `#` starts a YAML comment.
+- Textures: `texture: { type: 'texture', url: 'res://sprites/ph-target.png' }`.
+- `visible: false` on an overlay instance hides it **in the editor only**; play mode reads
+  `initiallyVisible` on the overlay file's root. Keep both as the recipe has them.
+- The loader is forgiving — unknown types, unknown keys and wrong value types load silently
+  as nothing. That is why rule 4 exists.
+
+## Script essentials — details in `pix3-scripts`
+
+```ts
+import { Script, type PropertySchema } from '@pix3/runtime';
+
+export class Combo extends Script {
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = { windowSec: 1 };            // defaults; scene `config` merges over them
+  }
+  static getPropertySchema(): PropertySchema {  // REQUIRED, or the class is not registered
+    return { nodeType: 'Combo', properties: [/* one entry per config key */], groups: {} };
+  }
+  onStart(): void {}                           // scene is loaded
+  onUpdate(dt: number): void {}                // dt in seconds
+}
+```
+
+- One mechanic = one new script of 70–140 lines. Extend a recipe's scripts only where
+  `design/recipe.md` names an extension point; do not restructure them.
+- Talk between scripts the way the project already does. Recipes use signals on nodes:
+  `node.emit('touch-scored', 1)` / `node.connect('touch-scored', this, fn)` — never rename the
+  recipe's signals or node ids. An existing game may use its own event bus or store instead
+  (next section).
+- Transforms are mutated, never assigned: `node.position.set(x, y, 0)`, `node.rotation.z = rad`.
+- Types come from `@pix3/runtime`: `pix3 check` type-checks against the bundled declarations in
+  `.pix3/types/` (or against your own `node_modules` when the project has its own `tsconfig.json`).
+
+## Hosting an existing (non-recipe) game
+
+A game that was not made from a recipe has its own architecture; plug into it, do not add a
+second one.
+
+- **Find its event bus / state store** before writing a script:
+  `grep -rn "CustomEvent\|dispatchEvent\|addEventListener\|subscribe(\|EventTarget\|emit(" src scripts`.
+  Window `CustomEvent`s, an `EventTarget` singleton, or a store with `subscribe()` are all
+  normal; node signals are only one option. Listen to what the game already emits.
+- **Clean up by hand.** `Script.onDetach` auto-disconnects only **node signals** whose target is
+  the script (on its own node or any other). Window listeners, store subscriptions and timers
+  must be removed in `onDetach` (keep the handler in a field; call the
+  unsubscribe the store returned) — otherwise every play/stop in the editor leaves one more
+  live listener behind.
+- **Two instruction files.** The project's own `AGENTS.md` wins on **process** (planning first,
+  where config and tests go, commit rules); this kit wins on **Pix3 facts** (the YAML format,
+  the runtime API, `pix3 check`).
+- The project's own `package.json` means `npm install` before `pix3 check` can type-check.
+- **Use the game's own feedback mechanisms.** If its camera controller writes the camera's
+  position every frame, an engine `scene.juice.shake('camera')` / `core:Shake` on that 3D camera
+  (or on any node the game positions itself) is overwritten every frame and never shows — call
+  the game's own shake (grep `shake`) instead. The same holds for its own sound/tween helpers.
+
+## The CLI and the live channel
+
+- `pix3 check [--json]` — after every batch (rule 4). `--json` prints `files` (`{ file, sha256 }`,
+  sha256 of the raw bytes), `diagnostics`, `typecheck`, `mergeLog`, `kit`.
+- `pix3 read <file>` — print a file and confirm to the editor you read exactly these bytes.
+- `pix3 validate [paths…]` — scenes only, no type-check.
+- `pix3 smoke [scene] [--frames N] [--json]` — run a scene headless (no browser) and report
+  script throws with frame and stack, `console.error`, missing `res://` files; exit 1 on errors.
+  Name the game scene (`pix3 smoke scenes/main.pix3scene`); no scene = the scenes git changes
+  reach, else every top-level scene (`--all` forces that).
+- `pix3 tree [scene] [--types A,B] [--depth N] [--props] [--json]` — scene outline, one line
+  per node; no scene = project overview.
+- **Live channel (optional).** When the human runs `pix3 serve` in this folder and connects the
+  editor to it (File → Connect to Workspace…), the MCP server in `.mcp.json`
+  (`pix3 mcp --workspace`) gives you 14 tools: running and observing the game, screenshots,
+  asset/sfx generation. There is no scene-editing tool — you still edit files. Details and the
+  answer fields: `.claude/skills/pix3-verify/SKILL.md` ("Live channel").
+
+## Skills (read the one you need, when you need it)
+
+- `.claude/skills/pix3-scene-format/SKILL.md` — full YAML format, prefabs, overlays, recipe tool table
+- `.claude/skills/pix3-nodes/SKILL.md` — 2D node properties (Group2D, ColorRect2D, Sprite2D, Label2D, Button2D, Bar2D, CanvasLayer2D, PostProcess); every node in `reference.md` beside it
+- `.claude/skills/pix3-scripts/SKILL.md` — Script API: lifecycle, schema, scene/input/juice/tween/audio/physics, `core:` components, traps
+- `.claude/skills/pix3-verify/SKILL.md` — `pix3 check` / `validate` / `read`, merge-log, the live channel (`game_run` + `expect`)
+
+## Finish every turn with
+
+What changed (files), what `pix3 check` said, whether you ran the game (and what `game_run`
+answered) or what the human should press and see, placeholders left, and 2–3 concrete next steps.