@pixelvibing/cli 0.50.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "PixelVibing: pixel art game assets from the command line, and the Skills that teach coding assistants to make them.",
   "license": "MIT",
   "homepage": "https://pixelvibing.com",

package/skills/pixelvibing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixelvibing
-description: Start here for this game's PixelVibing art — who is signed in, the style guide first, which Skill makes which kind of art, and listing, pulling, tagging, exporting and sealing what the platform made with pixel-vibing-cli or the PixelVibing MCP server. Use whenever the game needs art made, found, pulled into the project or taken into the engine.
+description: Start here for this game's PixelVibing art — who is signed in, the style guide first, which Skill makes which kind of art, and listing, pulling, tagging, exporting and sealing what the platform made, following its jobs, and reading or changing the project, its art and its map, with pixel-vibing-cli or the PixelVibing MCP server. Use whenever the game needs art made, found, pulled into the project, fixed up or taken into the engine.
 ---
 
 # PixelVibing art for this game
@@ -13,17 +13,22 @@ there is ever sent back: art enters the project only by being generated.
 Two ways reach the platform, and they reach the same project:
 - **The CLI**, `pixel-vibing-cli`. Every command takes `--json`, which prints its answer as
   JSON on standard output. Progress and errors go to standard error, and a failure exits 1.
+  `pixel-vibing-cli --help` lists every command, and `pixel-vibing-cli <command> --help` every
+  option of one, with what each is for: read it before running a command you have not used,
+  and whenever a Skill does not name the option you need. Never guess an option.
 - **The MCP server** `pixelvibing`, which `setup` configured in this harness. Its tools take
   the platform project's id as `project`; `whoami` below names it.
 
 ## Before anything
 
 1. `pixel-vibing-cli whoami --json` says who is signed in and which platform project
-   this folder generates for (the MCP server's `whoami` says the account alone).
-   - Not signed in: ask the person to run `pixel-vibing-cli login`.
+   this folder generates for (the MCP server's `whoami` says the account alone). A token
+   reaches one platform project, the one this folder is linked to; the MCP server's
+   `list_projects` names it.
+   - No token for this folder's project: ask the person to run `pixel-vibing-cli login` here.
    - Never ask for a token, and never write one into a file or a command you show.
    - No platform project: `pixel-vibing-cli link <project>`, or `link --idea "<what the
-     game is>"` to make one.
+     game is>"` to make one; both sign in through the browser and keep a token for it.
 2. Read `pixelvibing/style-guide.md`, or run `pixel-vibing-cli guide show` (MCP:
    `get_style_guide`), before deciding what to ask for. It says what the game is and how its
    art looks, and every generation is held to it. Write instructions in its terms. The
@@ -40,10 +45,9 @@ Load the Skill for the kind before you generate it:
 | reference art to draw the rest from, a look to hold to, or a level's area as pixel art | `pixelvibing-concept-art` |
 | skill or item icons that match | `pixelvibing-icons` |
 | a HUD, a menu, an inventory, a dialog box | `pixelvibing-ui` |
-| another of a result, a change to it, or setting it in motion | `pixelvibing-change` |
-
-No tool makes terrain sets, animated terrain, sounds, rotations or a creature's states: the
-person makes those in the editor, `pixel-vibing-cli editor`, and you pull them as any asset.
+| another of a result, a change to it, setting it in motion, a pose, turning it, a creature's state | `pixelvibing-change` |
+| ground that joins everywhere, or ground that moves | `pixelvibing-terrain` |
+| a sound effect, a line of speech, a piece of music | `pixelvibing-sound` |
 
 ## What every generation shares
 
@@ -57,8 +61,9 @@ person makes those in the editor, `pixel-vibing-cli editor`, and you pull them a
   and the style guide before it draws. When you wrote the instruction in full yourself —
   read the guide, looked at the references, know what the person wants — pass
   `--no-enrich` (MCP: `enrich: false`) and it is drawn from your words as written. Leave it
-  on for a person's few words. It is an object's, a creature's, concept art's, an icon set's
-  or an animation's: a variant, an edit and a UI refuse it.
+  on for a person's few words. It is an object's, a creature's, concept art's, an icon set's,
+  an animation's, a pose's, a rotation's or an animated terrain set's: a variant, an edit, a
+  creature's state, a terrain set, a UI and a sound refuse it.
 - **Following a job.** The CLI follows the job and pulls the asset when it is done. Over
   MCP, `generate` answers the job's id: follow it with `get_job`, then
   `pixel-vibing-cli pull <job id>` lands it in the folder.
@@ -100,6 +105,72 @@ MCP: `list_assets`, `get_asset` (its images, each with an address that downloads
 - **Using the art.** Use the pictures where they are, or copy them into the game's own
   asset folders. A copy is not tracked.
 
+## Jobs
+
+```bash
+pixel-vibing-cli jobs [--kind <kind>]... [--all] --json
+pixel-vibing-cli job show <id> --json
+pixel-vibing-cli job cancel <id>
+pixel-vibing-cli job redo <id> --yes
+pixel-vibing-cli job rate <id> kept|redone|rejected [--reason "<why>"]
+pixel-vibing-cli undelivered [--kind <kind>]... --json
+```
+
+MCP: `list_jobs`, `get_job`, `cancel_job`, `redo_job`, `rate_job`, `list_undelivered`.
+
+- `jobs` lists the newest 50 of this project's jobs; `undelivered` the generations nothing in
+  the art came from yet, to pull or to drop.
+- `job cancel` stops one that has not started, and what was held for it comes back.
+- `job redo` asks a generation again from the same input with the style guide as it is now: it
+  uses the limit as a new one does, so say so first.
+- `job rate` records what became of a result: `kept` when it is used, `redone` when it was
+  asked again, `rejected` when it is not wanted. Rate a result when the person says.
+
+## The project, its art and its map
+
+```bash
+pixel-vibing-cli project show --json
+pixel-vibing-cli project rename "<name>"
+pixel-vibing-cli project settings [--view <camera>|none] [--outline <outline>] [--sprite-size <px>]
+pixel-vibing-cli art show --json
+pixel-vibing-cli map show --json
+```
+
+MCP: `get_project`, `rename_project`, `change_project_settings`, `list_style_guide_versions`,
+`get_art`, `list_art_records`, `list_art_drafts`, `get_map`, `list_map_versions`,
+`read_map_sectors`.
+
+- **Settings** change every generation after; a project's tile size is fixed when it is made.
+- **The art and the map are the editor's.** Their changes — `art land`, `art change`,
+  `art remove`, `art restore`, `art describe`, `art record`, `art tileset`, `art draft`,
+  `art reference`, `art provenance`, `map write`, `map size` (MCP: `land_art`, `change_art`,
+  `remove_art`, `restore_art`, `describe_art`, `keep_record`, `claim_tileset`, `keep_draft`,
+  `add_reference`, `append_provenance`, `write_map_sectors`, `resize_map`) — are the editor's
+  own operations, given as JSON with `--body`, each against the revision it read. Prefer
+  `pull` to land an asset and the editor to arrange the art; reach for these only when the
+  person asks for that exact change. Nothing is lost: a removal is kept as a draft that
+  `art restore` brings back, and every sector keeps its earlier versions. Nothing here deletes.
+- **A stale change** changes nothing and says the current revision: read again, then send it
+  against that.
+
+## Images
+
+```bash
+pixel-vibing-cli image upload <png> --json
+pixel-vibing-cli image get <id> [--out <file>]
+```
+
+MCP: `upload_image` (a PNG as base64) and `get_image` (the image, and an address that downloads
+it). An uploaded image is this project's, and its id is what `--source`, `--last`, the ground
+pictures, `art land` and `art reference` take. A token reads only the images its project names:
+its art's, its jobs', and the ones uploaded for it.
+
+## Conversations
+
+`pixel-vibing-cli threads --json` and `thread show <id>` (MCP: `list_assistant_threads`,
+`get_assistant_thread`) read the platform assistant's conversations about this project, to see
+what was decided there.
+
 ## Taking the art into the game
 
 ```bash

package/skills/pixelvibing-change/SKILL.md

@@ -1,42 +1,86 @@
 ---
 name: pixelvibing-change
-description: Change art this game already has on PixelVibing — another of an object (a variant), an object or a creature changed as you say (an edit), or one set in motion (an animation) — through the PixelVibing MCP server's generate tool, from a picture the platform keeps. Use when a result is close but not right, or needs another like it, or has to move.
+description: Change art this game already has on PixelVibing — another of an object (a variant), an object or a creature changed as you say (an edit), one set in motion (an animation) or drawn in a still pose (a pose), a creature turned to face every way (a rotation) or drawn in a state such as hurt or mid-walk, kept with its sprite — with pixel-vibing-cli or the PixelVibing MCP server, from a picture the platform keeps. Use when a result is close but not right, needs another like it, has to move, turn or take a pose.
 ---
 
 # Changing a result
 
 Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
 
-The CLI has no command for these: they are the MCP server's `generate`, made from a
-picture the account keeps, by its image id.
+Every change is made from a picture the account keeps, by its image id.
 
 ## Finding the picture
 
-`get_asset` with the asset's id or name (from `list_assets`, or `pixel-vibing-cli list
---json`) answers its `images`; each one's `id` is a `source_image`. Never invent an image id:
-use only one a tool answered.
+`pixel-vibing-cli list --json` and `pixel-vibing-cli job show <id> --json` name assets and the
+images they made; MCP: `get_asset` with the asset's id or name answers its `images`, each one's
+`id` the picture to change. A sprite's own picture is among `parts` in
+`pixel-vibing-cli motion show <sprite> --json` (MCP: `get_sprite_motion`). Never invent an image
+id: use only one a command or a tool answered.
 
 ## The kinds
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
+```bash
+pixel-vibing-cli generate variant --source <image id> --instruction "in autumn colours" --yes --json
+pixel-vibing-cli generate edit --source <image id> --source-name knight --instruction "give it a red cape" --yes --json
+pixel-vibing-cli generate animate --source <image id> --instruction "walks to the right" [--into outfit/fox --name walk-east] --yes --json
+pixel-vibing-cli generate pose --source <image id> --instruction "mid-walk" [--into outfit/fox --name mid-walk --direction south] --yes --json
+pixel-vibing-cli generate rotate --source <image id> --instruction "a knight in plate armour" [--into outfit/knight --views 4|8] --yes --json
+pixel-vibing-cli generate state --source <image id> --state hurt [--directions 4|8] --instruction "a knight in plate armour" [--into outfit/knight] --yes --json
+```
+
+MCP, with `generate`:
+
 ```json
 { "project": "<id>", "kind": "variant", "source_image": "<image id>", "instruction": "in autumn colours", "max_percent": 40 }
 { "project": "<id>", "kind": "edit", "source_image": "<image id>", "source_name": "knight", "instruction": "give it a red cape", "max_percent": 40 }
+{ "project": "<id>", "kind": "rotate", "source_image": "<image id>", "instruction": "a knight in plate armour", "max_percent": 40 }
 { "project": "<id>", "kind": "animate", "source_image": "<image id>", "instruction": "walks to the right", "enrich": false, "max_percent": 40 }
+{ "project": "<id>", "kind": "pose", "source_image": "<image id>", "instruction": "mid-walk", "into": { "sprite": "outfit/fox", "name": "mid-walk", "direction": "south" }, "max_percent": 40 }
+{ "project": "<id>", "kind": "creature-state", "source_image": "<image id>", "state": "hurt", "instruction": "a knight in plate armour", "max_percent": 60 }
 ```
 
 - **`variant`** draws another of an object, keeping what makes it that object; the
-  instruction says what differs.
+  instruction says what differs. Up to 3 `--reference` PNGs.
 - **`edit`** changes an object or a creature as the instruction says, and only that.
-  `source_name` is what the picture is called, so the instruction can name it.
+  `--source-name` is what the picture is called, so the instruction can name it.
 - **`animate`** sets an object or a creature in motion. The instruction is the motion, from
   its first frame to its last: what moves, how far, and how it returns. It takes no
-  reference; the platform chooses how many frames. Pass `enrich: false` when the motion is
-  written in full; leave it on for a person's few words.
+  reference; the platform chooses how many frames. `--last <image id>` (MCP: `last_image`)
+  ends it on a frame of your own. Pass `--no-enrich` (`enrich: false`) when
+  the motion is written in full; leave it on for a person's few words.
+- **`pose`** draws an object or a creature in a still pose. The instruction is the pose: a
+  label such as `mid-walk`, or what changes in a few words. It takes no reference.
+- **`rotate`** turns a creature standing into the directions it faces. The instruction says
+  what it is, so each side is drawn as the same creature.
+- **`state`** (MCP: `creature-state`) draws a creature in a state past standing — mid-walk,
+  mid-run, mid-attack, jump, crouch, hurt, death — in 4 directions, or 8.
+
+## A sprite's motion
+
+A sprite keeps its motion with it, in three groups, each piece at an address:
+
+| Group | What it is | Address |
+|---|---|---|
+| views | one picture a direction | `<sprite> › view › <direction>` |
+| poses | a still picture under a label, in a direction or more | `<sprite> › pose:<label> › <direction>` |
+| animations | a named list of frames | `<sprite> › animation:<name>` |
 
-`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands it. An animation
-lands as `<name>/<n>`, one picture a frame, and an export packs its frames as an animation.
+`pixel-vibing-cli motion show <sprite> --json` (MCP: `get_sprite_motion`) answers all three,
+each picture by its image id. Give an animation or a pose `--into <sprite> --name <name>`
+(MCP: `into`) and it is kept with the sprite as the job finishes; the name is kebab-case, a
+creature's animation one the game plays, such as `walk-south`; a pose faces south unless a
+direction is given. A rotation kept with its sprite becomes its views (`--views 4|8`), and a
+creature's state its poses under the state's name. An animation kept with its sprite takes how
+long each frame is shown (`--frame-ms`, MCP `into.frame_ms`) and how the game plays it
+(`--play loop|every|change`, MCP `into.play`). Drawn again at the same address, the new one
+takes the address and the old one is still kept. One that finished without being kept is kept later with
+`pixel-vibing-cli motion keep <job id>` (MCP: `keep_motion`).
 
-## Not here
+## After
 
-Turning a creature into eight directions, a creature's states, terrain sets and animated
-terrain, and sounds are made in the editor, `pixel-vibing-cli editor`.
+The CLI follows the job. A variant, an edit, a rotation, a state, or an animation or a pose not
+kept with its sprite is pulled into the folder: an animation lands as `<name>/<n>`, one picture
+a frame, and an export packs its frames as an animation. Over MCP, `get_job` follows the job and
+`pixel-vibing-cli pull <job id>` lands it.

package/skills/pixelvibing-concept-art/SKILL.md

@@ -13,6 +13,8 @@ reference to what follows.
 
 ## With the CLI
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
 ```bash
 pixel-vibing-cli generate concept-art --instruction "<the picture>" [--size <w>x<h>] [--transparent] [--tag <tag>]... [--reference <png>]... [--no-enrich] --yes --json
 pixel-vibing-cli generate concept-art --instruction "<the area>" --pixel-art --tiles <cols>x<rows> [--no-enrich] --yes --json

package/skills/pixelvibing-creature/SKILL.md

@@ -9,6 +9,8 @@ Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit
 
 ## With the CLI
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
 ```bash
 pixel-vibing-cli generate creature --instruction "<who>" [--reference <png>]... [--no-enrich] --yes --json
 ```
@@ -39,6 +41,5 @@ pixel-vibing-cli generate creature --instruction "<who>" [--reference <png>]...
 ## After
 
 - It lands as `pixelvibing/out/<name>.png`.
-- A change to it, or a walk, an attack, an idle: the `pixelvibing-change` Skill.
-- Its eight directions and its states (hurt, dead, attacking) are made in the editor,
-  `pixel-vibing-cli editor`.
+- A change to it, a walk, an attack, an idle, its directions or its states (hurt, dead,
+  attacking): the `pixelvibing-change` Skill.

package/skills/pixelvibing-icons/SKILL.md

@@ -9,6 +9,8 @@ Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit
 
 ## With the CLI
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
 ```bash
 pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|item> [--size <16|32|64>] [--instruction "<theme>"] [--no-enrich] --yes --json
 ```

package/skills/pixelvibing-object/SKILL.md

@@ -9,6 +9,8 @@ Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit
 
 ## With the CLI
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
 ```bash
 pixel-vibing-cli generate object --instruction "<what>" --size <cols>x<rows> [--reference <png>]... [--no-enrich] --yes --json
 ```

package/skills/pixelvibing-sound/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pixelvibing-sound
+description: Generate sounds for this game on PixelVibing — a sound effect such as a coin picked up or a door creaking, a line of speech in a voice, or a piece of music — with pixel-vibing-cli or the PixelVibing MCP server, written as MP3 files. Use when the game needs audio.
+---
+
+# Sound
+
+Load the `pixelvibing` Skill first: who is signed in, the limit.
+
+## With the CLI
+
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
+```bash
+pixel-vibing-cli generate sfx --instruction "<what it sounds like>" [--seconds <s>] [--loop] [--out <file>] --yes --json
+pixel-vibing-cli generate speech --text "<what is said>" --voice <voice> [--out <file>] --yes --json
+pixel-vibing-cli generate music --instruction "<the piece>" [--out <file>] --yes --json
+```
+
+Each writes its sound as an MP3 into `pixelvibing/sounds/`, or to the file `--out` names, once
+its job is done. `pixel-vibing-cli generate --help` lists the voices.
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "kind": "sfx", "description": "a coin picked up, bright and short", "seconds": 1, "max_percent": 30 }
+{ "project": "<id>", "kind": "speech", "text": "Welcome aboard, traveller.", "voice": "<voice>", "max_percent": 30 }
+{ "project": "<id>", "kind": "music", "description": "a calm harbour theme on strings", "max_percent": 30 }
+```
+
+with the tool `generate_sound`. `get_job` follows the job and, once done, names its `sounds`;
+`get_sound` answers one as MP3 audio.
+
+## Writing it
+
+- **A sound effect.** What makes the sound and how it feels: "a wooden door creaking open,
+  slow", "a coin picked up, bright and short". `--seconds` sets its length; `--loop` makes it
+  loop seamlessly, for rain, wind or an engine.
+- **Speech.** The words exactly as they are said, in a voice. Keep a line short; one line a
+  generation.
+- **Music.** The mood, the instruments and the tempo: "a calm harbour theme on strings and a
+  soft accordion".
+- **Original sound.** Never another game's music or theme, and never a real person's voice:
+  when the person names one, make original sound in its spirit and say so.
+- **Where it goes.** The game loads the MP3 from where it was written; copy it into the game's
+  own audio folder when that is where the engine looks. Sounds are not part of the map, the
+  export or the sealed container.

package/skills/pixelvibing-style-guide/SKILL.md

@@ -11,6 +11,9 @@ and shading, its scale in pixels, and what never belongs in it. Every generation
 platform makes for this project is held to it, so a guide that no longer describes the
 game makes art that no longer fits it.
 
+`pixel-vibing-cli guide <show|pull|push|revise|versions> --help` lists every option of each: read it for any option
+this Skill does not name.
+
 ## When to change it
 
 - The game gains a place, a biome, a faction, an era, or a kind of thing it did not have.

package/skills/pixelvibing-terrain/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pixelvibing-terrain
+description: Generate a terrain set for this game on PixelVibing — sixteen tiles where one ground meets another, such as grass over water — and set a terrain set in motion, such as water rippling or lava flowing, with pixel-vibing-cli or the PixelVibing MCP server. Use when the game's map needs ground that joins everywhere, or ground that moves.
+---
+
+# Terrain
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+A terrain set is sixteen tiles where an upper ground meets a lower one, every way their
+corners can meet, so the editor's brush paints the two together and every edge joins.
+
+## A terrain set
+
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
+```bash
+pixel-vibing-cli generate terrain --upper grass --lower water --instruction "<how they look and meet>" \
+  [--upper-image <png> --lower-image <png>] [--role style|source|variant] [--cells 32|64] \
+  [--elevation 0-3] [--spread <0.1-0.7>] [--raggedness <0-1>] [--seed <n>] --yes --json
+```
+
+MCP:
+
+```json
+{ "project": "<id>", "upper": "grass", "lower": "water", "instruction": "a soft sandy shore", "max_percent": 40 }
+```
+
+with the tool `generate_terrain`; `upper_image` and `lower_image` are images of the account's,
+both or neither.
+
+- **The grounds.** Name each in a word or two, as the style guide would. The upper ground is the
+  one that sits on top where they meet: grass over dirt, snow over rock, dirt over water.
+- **The instruction.** How the two look and how the edge between them looks: a sandy shore, a
+  sharp cliff, scattered pebbles. Use the style guide's words; never restate its camera.
+- **Pictures of the grounds.** Give both when the game already has the look, such as tiles
+  from a concept art; the set is drawn from them.
+- **Landing it.** A terrain set is landed from the editor's Library, which cuts it into the
+  cells its brush paints: tell the person to open it there, `pixel-vibing-cli editor`. `pull`
+  lands nothing for a terrain set.
+
+## Setting one in motion
+
+One ground moves in a seamless loop while the other stays still: water rippling against a
+shore, lava churning beside rock.
+
+```bash
+pixel-vibing-cli generate terrain-animation --terrain <asset id or name> [--instruction "<how it moves>"] --yes --json
+```
+
+MCP: `animate_terrain` with the terrain set's asset id or name as `terrain`, and `motion`.
+
+- **Which set.** One the project keeps, from `generate terrain`: `pixel-vibing-cli list terrain
+  --json` (MCP: `list_assets` with kind `terrain`) names them.
+- **The motion.** A few words, or none: the platform chooses which ground moves and how, from
+  the grounds' names. Say it when the person wants a particular motion, such as slow waves.
+- **After.** The editor writes the frames back onto the set when the person opens it.
+
+## Following it
+
+The CLI follows the job and says where it is done. Over MCP, `get_job` follows it.

package/skills/pixelvibing-ui/SKILL.md

@@ -13,6 +13,8 @@ and `references/ui.example.json` is a whole HUD laid out.
 
 ## With the CLI
 
+`pixel-vibing-cli generate --help` lists every option `generate` takes, with what each is for: read it for any option this Skill does not name, rather than guessing one.
+
 ```bash
 pixel-vibing-cli generate ui --sketch <file.json> --instruction "<the set, in a line>" [--reference <png>]... --yes --json
 ```