@funpixel/tools 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,115 @@
+Funpixel GDK and funtools (@funpixel/tools)
+
+Required Notice: Copyright 2026 Funpixel (https://funpixel.ai)
+
+These files are licensed under the PolyForm Shield License 1.0.0, below, together with the
+additional permission that follows.
+
+## Additional Permission: Making Games
+
+In addition to the permissions in the license below, the licensor grants you permission to use the
+software, and to make changes and new works based on it, to make, test, publish, sell and run your
+own games and other playable works, whether or not you charge for them. The games you make are yours:
+this license does not reach a game's own code, art, sound, text or other content, or what you earn
+from it, and a game you make is not a product that competes with the licensor's, wherever you
+publish it.
+
+This permission does not cover providing the software, or a product or service based on it, that
+lets others make games (a game-making tool, kit, platform or service). That remains subject to the
+Noncompete section of the license below.
+
+The parts of this package under other licenses keep them: see NOTICE (the bundled devtools, MIT)
+and bench/LICENSE (the Blender bench scripts, GPL-3.0-or-later) where present, and
+THIRD_PARTY_NOTICES.md for the GDK.
+
+---
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/NOTICE

@@ -0,0 +1,28 @@
+@funpixel/tools is licensed under the PolyForm Shield License 1.0.0 with an additional permission to
+make games (LICENSE). It also carries, under their own licences, what the Funpixel Studio uses:
+
+  dist/vendor/verify     @funpixel/verify — the in-page probe scripts verify, capture, look and
+                         play run (Funpixel).
+  dist/devtools/inspector  @funpixel/inspector, MIT (Funpixel): the inspector UI and the hooked
+                         engines `funtools dev` maps the game's engine to. The hooked engines are
+                         builds of three.js (MIT, Copyright 2010-2024 three.js authors), PixiJS
+                         (MIT, Copyright 2013-2023 Mathew Groves, Chad Engler) and Preact (MIT,
+                         Copyright 2015-present Jason Miller); the inspector UI carries
+                         source-map-js (BSD-3-Clause, Copyright 2009-2011 Mozilla Foundation and
+                         contributors). PixiJS ships inside it the dependencies its own build
+                         bundles, under their licences. Their licence texts are in
+                         dist/devtools/LICENSES.
+  dist/devtools/profiler @funpixel/profiler, MIT (Funpixel).
+  dist/devtools/kapture  @funpixel/kapture, MIT (Funpixel): the capture driver a preview carries.
+  bench/                 the Blender bench scripts, GPL-3.0-or-later, under their own
+                         bench/LICENSE; funtools runs them through Blender as a separate program.
+
+`funtools compose` renders through HyperFrames (https://github.com/heygen-com/hyperframes), Copyright HeyGen
+Technology Inc. and the HyperFrames contributors, Apache-2.0 (the Apache License 2.0). It is not in this
+package: compose runs the pinned version (package.json peerDependencies, an optional peer) as its own program,
+from node_modules when installed beside funtools, else through `npx hyperframes@<version>`, which fetches it with
+its own licence and NOTICE. funtools does not modify it. The starter compositions load GSAP
+(https://gsap.com, its own licence) from jsDelivr at render time; it is not in this package either.
+
+The optimize helper's codecs (Draco, Basis Universal, meshoptimizer) are not in this package: they
+ship in @funpixel/optimize-<platform>-<arch> with their own licences.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @funpixel/tools — `funtools`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Funpixel CLI: make a game the platform builds as-is, check it locally for free, generate its assets, and
+publish it as a draft you own or to another host. Node only (macOS, Linux, Windows; Node 22.18+ runs the
+TypeScript source, `dist/` serves Node 20.11+).
+
+## Start here
+
+```
+npm i -g @funpixel/tools            # or npx @funpixel/tools …
+funtools flow start my-game --idea "<the game in one line>"
+cd my-game && npm install
+funtools flow                        # where the game is, and the one next step
+```
+
+With the Funpixel GDK plugin in your agent (Claude Code, Cursor, Codex), say `/fp:new "<the game>"`:
+the agent briefs it back, makes the key art and a first playable you steer in the chat, plans the
+whole game around it with you, then builds it round after round against the plan's target frames,
+with the game open beside the chat. `funtools flow` is the one driver; the commands below are the
+tools it names.
+
+## License
+
+PolyForm Shield 1.0.0, with an added permission to make, publish and sell your own games: the games
+you make are yours. Building a competing game-making tool or service on it is not permitted. See
+`LICENSE`; the bundled devtools are MIT and the Blender bench scripts GPL-3.0-or-later (`NOTICE`).
+
+## Commands
+
+| Command | What it does | Exit |
+|---|---|---|
+| `init [dir] [--framework pixi\|three-world\|three] [--name "Title"] [--offline]` | A new game with the platform's scaffold (a 3D line, or `three-world`, gets the 3D world starter: camera rig, lit world, controller, phone stick, frame budget; every starter seeds the GDD with its genre defaults and `assets/assets.json` with its cast) — title, play, pause and game-over screens, a HUD, keyboard/touch/pointer verbs, juice behind a reduced-motion check, `public/assets/` paths that draw a placeholder until a file lands — the `__FPX_*` hooks wired through `src/fpx-hooks.ts`, checks in `funpixel.json`, and agent files for every agent. With an API key it mints the game's id on the server (`POST /v1/games/drafts`) and writes it into `funpixel.json`; offline, the first publish mints it. `funpixel.json` `guidance_hash` records which GDK guidance (AGENTS.md, CLAUDE.md, `.agents/skills`) the game was made with | 0 / 3 |
+| `dev [dir] [--no-devtools] [--relay [--bots N]]` | The game's own Vite dev server with the platform's inspector and profiler mounted as a preview carries them. `--relay` adds a local relay on :7370 (the `funpixel-relay` binary: `FUNPIXEL_RELAY_BIN`, PATH, or the monorepo's `target/debug`; Redis at `REDIS_URL`) and the parent-frame bridge: open `/__funpixel/play` in two tabs, each its own player with a dev ticket minted for this machine only, and they meet in `dev-<game_id>`. `--bots N` (1–15) seats N headless bot players there first, through the same bridge and SDK path: each plays by calling a random `__FPX_VERBS__` verb, else holding a `__FPX_KEYS__` key (never Escape, `KeyP`, `KeyM`), else tapping, about twice a second, until dev stops; the first bot hosts | |
+| `doctor [dir] [--add-hooks]` | Static: will the platform build it, can verify measure it, is the headless Chromium verify needs installed (else the exact install command), and is the game's agent guidance (`guidance_hash`) the one this funtools ships (a warning with `upgrade` when it is older). `--add-hooks` writes `fpx-hooks.ts` into a game funtools did not make and prints the three lines to wire it | 0 ok · 1 will break |
+| `doctor --host [claude\|codex\|cursor\|kiro] [dir] [--json]` | Reads the host agent's own permission settings (detected from `CLAUDECODE`, `CODEX_*`, `CURSOR_AGENT` when no name is given; Kiro is named): which commands the kit runs they let through, which shapes hosts often refuse (chains, heredocs, substitutions, loops, python) with a plain call for each, and the allowlist lines you could add yourself. Never writes a settings file | 0 · 3 unknown host |
+| `test [dir] [--node] [--json]` | The game's `npm test`, its exit recorded with the build fingerprint in `.funtools/tests.json` (the GDK hooks read it). `--node` runs `test/**/*.test.ts` with this Node alone — no npm, nothing on PATH, imports without an extension resolve to `.ts` — and an `npm test` that cannot start (exit 126/127) falls back to it | 0 · 1 · 3 |
+| `check [dir] [--viewport desktop\|phone\|both] [--front-door\|--click sel] [--no-test] [--json]` | Build, the rules suite and `verify` in one call, for hosts that refuse `npm run build && …`: a red build stops there, a failing suite still runs verify | 0 · 1 · 2 · 3 |
+| `feedback collect <folders…>` / `feedback log "<what happened>" [--kind k] [--cost-usd n]` | `collect` ranks what creators said about the kit; `log` appends one stamped dev-log line to `.funtools/devlog.jsonl` (no heredoc) | 0 · 2 · 3 |
+| `upgrade [dir]` | Refresh the files `init` wrote; an edited file keeps yours, the new one lands beside it. Moves `guidance_hash` forward once every guidance file is current. `upgrade --self`: the newest funtools on npm and the exact command that installs it (npx, a dev dependency or global), never run for you | 0 |
+| `smoke [dir] [--json]` | Static, over what ships: visible placeholder text, asset references that will 404, orphan assets, imports a clean install can't resolve, size budgets, and (warnings) game rules tied to the renderer — `src/rules.ts`, `src/sim/`, `src/logic/` or `src/rules/` importing an engine, Preact or the DOM (directly or through a local file) or calling `Math.random()`, and hits decided from display objects' bounds | 0 · 1 a player will see it |
+| `verify [dir\|url] [--viewport desktop\|phone\|both] [--watch] [--checks f.json] [--manifest funpixel.json] [--no-sweep] [--json\|--report]` | The hosted game probe, run locally: mechanic checks, self-tests, levels, the bot sweep, render health, sound, fonts, sound files, the page load and two seconds of play. Writes `verify.json` (verdict + fingerprint). One retry on software GL (SwiftShader) when the context is lost or there is no WebGL | 0 pass · 1 fail · 2 not observed · 3 error |
+| `verify [dir] --players 2 [--json]` | Two headless tabs in one room on the local relay (as `dev --relay`), the real SDK and the relay's own frames: both join with one host, the host acts (its verbs, keys or a tap) and the guest must receive it and see a number in its `__FPX_STATE__` move that sat still before, a late third tab gets the host's snapshot (or its sync stream), and the guest is told of a new host when the host leaves. Does not write verify.json | 0 pass · 1 fail · 2 not observed · 3 error |
+| `pack [dir] [--dry-run] [--no-build] [--json] [--out f.tar.gz]` | Exactly what an upload carries, a content leak scan, the server's limits and a build from a copy of only the staged files. Never uploads | 0 · 1 must not be uploaded |
+| `gen <kind> ["prompt"] [options] [--out path] [--no-wait] [--yes] [--strip-title] [--json]` | Run a Tools API job — `image`, `texture` (a seamless tile, refused uncharged if it shows a seam), `strip`, `sprite`, `sound`, `music`, `model3d`, `skybox` (a 360° equirect sky), `find-material` / `material` (search and copy Poly Haven's free CC0 HDRIs, texture sets and glTF models, licence and source recorded; a set lands in `public/assets/materials/<name>/` with its own file names), `inspect` (the Blender bench on a model a job made), `optimize-model` (decimate it to a triangle budget), `fracture` (break it into shards), `lod` (its levels of detail, `model.lod1.glb` onwards) or `rig` (clips authored onto a bare biped rig, or a donor's rig fitted onto a bare mesh, after a free rig check) — follow its event stream (resuming a dropped one after its last event), and save the files into the game, `public/assets/{images,sprites,sfx,music,models}/<prompt-slug>.<ext>` by default — the folders the scaffold reads — never over a file it did not name. A price above the confirm line needs `--yes` or a "y" at the prompt. A picture prompt that carries the game's `funpixel.json` name is warned about (image models letter it and garble it); `--strip-title` sends it without. `--no-wait` prints the job id | 0 done · 1 the job failed · 2 refused before it ran (a refused key included) · 3 error |
+| `estimate <kind> ["prompt"] [options] [--json]` | What that `gen` would cost, in credits, and whether it needs a confirm | 0 · 2 · 3 |
+| `job <id> [--wait] [--out path] [--json]` | A job's status; `--wait` follows it to the end and saves its files where `gen` would | as `gen` |
+| `jobs [--tool name] [--status s] [--limit 1-100] [--cursor c] [--json]` | Your account's jobs, newest first, one page at a time (`GET /v1/jobs`); `--tool` takes a tool or a gen kind, `--status` is queued, running, succeeded, failed or cancelled; a page with more prints the command for the next | 0 · 2 · 3 |
+| `optimize [dir] [--check] [--json]` | What the agent's asset rule would flag: an image of 400 KB or more, 4+ loose sprites (the rule's own numbers). `funpixel.json` `optimize.allow` exempts a backdrop | 0 · 1 breach (`--check`) |
+| `optimize <compress\|pack-atlas\|unpack-atlas\|pack-strip\|optimize-mesh> <path…> [--write] [--json]` | The Studio's asset optimizer on local files, offline and free, through the native helper `funpixel-optimize` (`FUNPIXEL_OPTIMIZE_BIN`, the `@funpixel/optimize-<os>-<cpu>` package, PATH, `~/.funpixel/bin`, or this checkout's `cargo build -p funpixel-optimize`; darwin-arm64 builds and runs). A dry run unless `--write`; after a packing op, the brief for your agent to change the loading code. | 0 · 3 |
+| `playable [dir] --network applovin\|unity\|ironsource\|mintegral\|google\|meta\|tiktok [--no-play] [--json]` | The game as one ad network's playable: one HTML file in `dist-playable/index.html` (built from `playable.html` when there is one, with the game's own Vite and `vite.playable.config.ts` if present; every script, stylesheet and file the page names folded in as data), weighed against that network's ceiling (a warning in the last 10%), failed on anything it would fetch at runtime and on markup the network requires, then played offline on a 390x844 phone with the network's call to action stubbed: not before the first touch, not on the first tap, once on the end card, after a number in `__FPX_STATE__` rose. Ceilings: the GDK skill's `references/networks.md` | 0 pass · 1 fail · 2 not observed · 3 |
+| `reel [dir\|url] [--seconds 12] [--fps 12] [--viewport desktop\|phone] [--frames-only] [--out f.mp4] [--json]` | A vertical share video of the game being played, cut locally: the built game served as verify serves it, toured through its `__FPX_VIEWS__` (a title screen for a moment, the `motion: true` view for the bulk, an ending screen last) and driven by its own `__FPX_VERBS__` — the checks' verbs first, never reset/pause/mute, and never a check verb no check ties to a key or tap when others are (a setup such as `fillUp`) — or its `__FPX_KEYS__`, about four presses a second; filmed at `--fps` and encoded with `ffmpeg` to a 1080x1920 H.264 MP4, framed as the platform's share video frames its stills (portrait fills the frame; landscape is shown whole over a blurred copy). Writes `.funtools/reel/reel.mp4` (never shipped). A portrait game (`metadata.orientation`) films on a phone. With no `ffmpeg` on PATH, or `--frames-only`, the PNG frames in `.funtools/reel/frames/` are the output. A game with no hooks gets a passive reel of what it does on its own; a reel whose every frame is the same picture warns | 0 · 3 |
+| `trailer [dir\|url] [--seconds 30] [--fps 15] [--formats 16x9,9x16] [--viewport desktop\|phone] [--music f \| --no-music] [--title t] [--key-art f] [--logo f] [--cta t] [--intro clip.mp4] [--outro clip.mp4] [--out dir] [--json]` | A store/social trailer cut from REAL play. The game is filmed as `reel` films it, with its `__FPX_MOMENT__` payoffs marked on the frames they happen on; the music bed (the game's own, from `public/assets/music/` or named `music`/`bgm`/`theme`, or `--music`) is decoded with `ffmpeg` and its beat found (onset autocorrelation, 70–180 BPM; no clear pulse = 120 BPM); every segment is whole beats and the music starts on a beat, so every cut lands on one. The edit: a title card (key art from `design/key-art.png`, `cover`/`poster`/`splash`, or `--key-art`, else a blurred frame of play; the logo or the name over it), gameplay shots placed so the heaviest payoffs land three quarters in, the rest spread over the take, in the order played; an end card (`--cta`, default "Play free"). `--intro`/`--outro` add generated clips (`gen video`) as cards only: before the title or the end card, at most 4 s and a fifth of the trailer, each labelled "Generated video · not gameplay" on screen. Cards are drawn in the headless browser. Writes `.funtools/trailer/trailer-16x9.mp4` (1920x1080), `trailer-9x16.mp4` (1080x1920) and `trailer.json` (every segment's `source`: `gameplay`, `card`, `generated`) — never shipped. Needs `ffmpeg` | 0 · 3 |
+| `model <inspect\|render\|finalize> <asset-id\|file> [--frames n] [--size px] [--keep-clips a,b] [--out path] [--json]` | The hosted Blender bench on a model a job of yours made (`inspect_model`, free; `render_model`: views round it, a front view and a contact sheet; `finalize_model`: broken materials repaired, clips not kept dropped, the proof rendered; pictures in `.funtools/renders/<name>/`, never shipped): by asset id, or by the file `gen` saved it as — `gen` and `job --wait` record which job made each file in `.funtools/assets.json` (never shipped), so nothing is uploaded. A file changed since, or one no job made, is for `--local` | as `gen` |
+| `model level <spec.json> [--size px]`, `model skin <asset-id\|file> [--tone #rrggbb]`, `model retexture <asset-id\|file> "new look" [--palette #a,#b] [--game-id id] [--quality q] [--roughness] [--normal]` | The bench's authoring jobs (`build_level`, `author_skin`, `retexture_model`): a level spec built into `public/assets/models/<name>.glb` with colliders and named markers; a character's exposed skin marked by a vision pass and painted one tone; a new look repainted onto the same mesh. Their pictures go to `.funtools/renders/<name>/`, never shipped | as `gen` |
+| `model --local <inspect\|normalize\|decimate\|render\|finalize> <model> [--out path] [--target-triangles n] [--height-m m] [--frames n] [--size px] [--keep-clips a,b] [--json]` | The same bench scripts on your own Blender 4.2+ (`FUNPIXEL_BLENDER_BIN`, Applications, Program Files or PATH): free, offline. `normalize`, `decimate` and `finalize` write `<name>.<verb>.glb`; `render` and `finalize`'s proof write PNGs to `.funtools/renders/<name>/`; `level <spec.json>` writes `public/assets/models/<name>.glb` and its plan and view | 0 · 1 Blender refused it · 3 |
+| `model clips <model.glb\|gltf> [--json]` | The animation clip names in the file, read locally (no Blender, free), and every name that sits inside another (`run` / `run_fast`, `idle` / `idle_long`, `walk` / `walkback`), repeats or has no name: a lookup by name that matches loosely plays the wrong clip with no error | 0 every name apart · 1 a collision · 2 no clips (not observed) · 3 unreadable |
+| `judge structure <picture\|folder…> [--prompt t]` · `judge identity <model.glb\|views…> [--concept f] [--medium model\|sprites]` · `judge report [n]` | Checks on generated art an aesthetic score cannot make, each one seat prompt in `.funtools/judge/<n>/` for your own agent (no model called). `structure`: five fixed yes/no questions with evidence (matched pairs, part counts, attachment, lettering, the frame); any no fails, never averaged into a score. `identity`: a model's rendered views (`.funtools/renders/<name>/`; render them with `model`) or a sprite set against its concept, per trait (silhouette, palette, key features, proportions) with the worst view; major drift fails, minor warns. `report` decides by fixed rules; an answer about a picture that changed since is not counted | prepare 0 · 2 nothing to judge · 3; report 0 · 1 · 2 not observed · 3 |
+| `login [--key fp_live_…\|-]` / `logout` | Sign in in a browser (device code) and keep a new API key in the OS credential store (Keychain, Credential Manager, libsecret); `--key` stores one you made, `-` reads it from stdin. `FUNPIXEL_API_KEY` wins when set; `FUNPIXEL_KEY_STORE=none` turns the store off. Details: https://docs.funpixel.ai/agents/funtools/ | 0 · 1 declined · 3 |
+| `whoami` | The account, plan and key funtools is using (`GET /v1/me/key`) | 0 · 1 refused · 3 |
+| `usage [--days 1-92] [--this-key] [--json]` | Credits charged by tool and by day (`GET /v1/me/usage`), this UTC month or the last `--days`; `--this-key` counts only the key in use | 0 · 1 refused · 3 |
+| `budget [--json]` | The key's monthly credit cap, what it spent this UTC month, the spend alerts crossed (50, 80, 100%) and the wallet. Read-only: a key never changes its own cap (Settings › Developers) | 0 · 1 refused · 3 |
+| `publish [dir] [--target funpixel\|itch\|pages\|folder] [--yes] [--json]` | `funpixel` (default): upload the staged game as a draft; the id comes from `funpixel.json` (or `--game-id`), and the first upload writes it back, so every publish updates one draft; prints your verify and the server's own. `itch` (`--itch user/game[:channel]`, butler), `pages` (`--project name`, wrangler) and `folder` (`--out dir`) ship the build only: the exact command is shown, and it runs only with `--yes` or your "y". A folder copy goes into an empty folder or one funtools wrote, and never deletes a file it did not write. Every publish is a line in `.funtools/publish.jsonl`. `--json` prints the server's reply (its `status` word, and `code` on a refusal) plus `ok`, `target` and the numeric `http_status` | 0 · 1 refused · 2 handed over, not performed · 3 |
+
+`gen` options: image/sprite `--size WxH --quality low|medium|high --target-size px` (the delivered file's longest side, scaled down on the server, never up), image `--transparent`; sound
+`--duration secs --loop`; music `--length clip|full --instrumental`; model3d `--image-url https://… |
+--image-asset id`, `--style standard|lowpoly`, `--animations walk,run`; inspect `--asset id`; optimize-model `--asset id --budget food|prop|thin_walled|set_piece|character`
+`[--device phone|desktop] [--height metres]`; skybox `--negative "…"`; find-material `--type hdri|texture|model --limit 1-20`; material `--type hdri|texture|model (--id id | "keywords") --resolution 1k|2k`; fracture `--asset id [--pieces 2-32] [--seed n]`; lod `--asset id [--levels 1-4] [--ratio 0.05-0.95]`; rig `--asset id [--clips idle,walk | --donor id]`; render `--asset id [--frames 1-12] [--size 64-1024]`; finalize `--asset id [--keep-clips Idle,Walk]`; level `--spec file.json [--size 256-1024]`; skin `--asset id [--tone #rrggbb]`; retexture `"new look" --asset id [--palette …] [--game-id …] [--quality …] [--roughness] [--normal]`;
+video `"prompt" [--duration 5|10] [--aspect 16:9|9:16|1:1] [--image-asset id | --image-url https://…]` (a generated clip, saved to `.funtools/video/`, never shipped: trailer material, never gameplay)
+`[--min-triangles n]`. `gen`, `estimate`, `job`, `jobs`, `whoami`, `usage`, `budget` and `publish` need an `fp_live_` key (paid plans): `FUNPIXEL_API_KEY`, or the one `login` stored.
+
+Verify reads the game's `window.__FPX_STATE__`, `__FPX_VERBS__`, `__FPX_VIEWS__`, `__FPX_KEYS__`, `__FPX_SELFTEST__`,
+`__FPX_AUDIO__` and `__FPX_LEVELS__` — the contract is in the GDK's verify skill (`references/checks.md`) — or a game's own globals
+through the `hooks` map in `funpixel.json`. `scripts/verify-parity.sh` (in `funpixel-mono/`) proves local verify and
+the hosted probe agree.
+
+## Update notice
+
+Once a day a command starts a detached check of the npm registry for a newer `@funpixel/tools` (3 s timeout; the command
+never waits for it) and keeps the answer in the user config dir (`$XDG_CONFIG_HOME`, `%APPDATA%` or `~/.config`, under
+`funpixel/`). When it names a newer version, the next command prints one line on stderr after its output. Never in CI,
+with `--json`, or off a terminal; `FUNTOOLS_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER`) turns it off, and
+`FUNTOOLS_REGISTRY` / `npm_config_registry` pick the registry.
+
+## Output
+
+Every command prints the same way (`src/ui.ts`): a heading, items as `✓ pass`, `✗ FAIL`, `○ not observed`,
+`! warn`, `– skip` and `· note`, and a last line `✓ <command>: …`. Errors read `funtools <command>: <what happened> —
+<what to do next>`. Colour only on a TTY with `NO_COLOR` unset (`FORCE_COLOR` forces it); plain ASCII marks on a
+terminal that cannot draw the others (or `FUNTOOLS_ASCII=1`). `--json` prints JSON and nothing else.
+
+## Scripts
+
+In the source repository, not in the npm package:
+
+- `scripts/verify-corpus.ts` — verify a library of games and record each verdict with its evidence.
+- `scripts/publish-evals.ts` — stage, pack and build a list of game directories and record which would be
+  refused locally, and why. Uploads nothing.
+- `scripts/critic-panel.ts` — the four-persona blind critic panel the quality bar gates on (paid,
+  balance-checked and budget-capped), and `scripts/bar/` — its evidence builder and the bar's objective
+  measures (palette, frame diffs, code signals, time to control).
+
+## Develop
+
+    npm ci && npm run typecheck && npm test && npm run build
+
+`npm pack` (prepack) makes the package self-contained: the Blender bench scripts (`bench/`), the
+`@funpixel/verify` page scripts (`dist/vendor/verify`, the built imports pointed at them) and the
+Studio's devtools — inspector with its hooked engines, profiler, Kapture capture driver — in
+`dist/devtools/`, from `libs/funpixel-{inspector,profiler,kapture}/dist` (build them first, or set
+`FUNPIXEL_<NAME>_DIR`). `dev` and `capture` look for a devtool in `FUNPIXEL_<NAME>_DIR`, then the
+package's copy, then the checkout's dist. `NOTICE` names what is bundled and under which licence.