@pixelvibing/cli 0.49.1 → 0.50.0

package/README.md

@@ -12,7 +12,9 @@ pixel-vibing-cli setup
 
 `setup` signs you in in the browser, makes the directory a local project, which means a
 `pixelvibing.json` and a `pixelvibing/` folder, links it to one of your platform
-projects, and installs the Skills into `.claude/skills/` or `.codex/skills/`. It also
+projects, and installs the Skills into `.claude/skills/` or `.codex/skills/`: a hub, the
+style guide's, and one for each kind of art. A block in `AGENTS.md`, and in `CLAUDE.md` when
+there is one, names which Skill to load for which request. It also
 configures the remote MCP server in `.mcp.json` or `.codex/config.toml`, by a command
 that prints the token's header when the harness connects, so the token is in no file.
 Each step it finds done already is skipped.
@@ -27,7 +29,7 @@ Each step it finds done already is skipped.
 | `guide pull\|push\|revise\|show\|versions` | Read and write the project's style guide |
 | `seal` | Seal `pixelvibing/out/` into `pixelvibing/build/assets.eac` |
 | `export default\|pixi\|phaser\|godot` | Pack the art into sprite sheets and the map into placed sprites, for an engine |
-| `update` | Replace the installed Skills with the ones this version ships, and bring the MCP server's entry to it |
+| `update` | Replace the installed Skills with the ones this version ships, add those it ships since, rewrite their block in `AGENTS.md`, and bring the MCP server's entry to it |
 | `mcp headers` | Print the header a harness sends the remote MCP server, from the kept token |
 | `editor` | Open the PixelVibing desktop app on the project |
 

package/dist/pixel-vibing-cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { resolve, dirname, join, relative, sep, basename } from "node:path";
+import { resolve, dirname, join, relative, sep, basename, isAbsolute } from "node:path";
 import { realpath, promises } from "node:fs";
 import { promisify, parseArgs } from "node:util";
 import { randomBytes, createHash } from "node:crypto";
@@ -4165,6 +4165,12 @@ async function referenceOf(context, path) {
   return bytes;
 }
 async function requestOf(context, asked, args) {
+  const request = await shapedRequest(context, asked, args);
+  if (!flagOf(args, "no-enrich")) return request;
+  if (request.kind === "ui-sketch") throw new CliError("--no-enrich is not a UI's: its layout is read as it is");
+  return { ...request, body: { ...request.body, enrich: false } };
+}
+async function shapedRequest(context, asked, args) {
   const kind = KIND_NAMES[asked] ?? asked;
   const known = GENERATED[kind];
   if (known === void 0) throw new CliError(`generate makes ${Object.keys(GENERATED).join(", ")} (or ui), not ${asked}`);
@@ -4247,7 +4253,7 @@ async function followed(context, platform, jobId) {
 const generate = {
   name: "generate",
   summary: "Generate an object, a creature, concept art, icons or a UI on the platform, then pull it",
-  usage: "<object|creature|concept-art|icons|ui> [--instruction <text>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--yes]",
+  usage: "<object|creature|concept-art|icons|ui> [--instruction <text>] [--size <c>x<r>|<w>x<h>|<px>] [--transparent] [--pixel-art] [--tiles <c>x<r>] [--tag <tag>]… [--names <list>] [--purpose skill|item] [--sketch <json>] [--reference <png>]… [--no-enrich] [--yes]",
   options: {
     instruction: {
       type: "string",
@@ -4277,6 +4283,10 @@ const generate = {
     },
     reference: { type: "string", multiple: true, value: "<png>", description: "an image to draw from" },
     quality: { type: "string", value: "<quality>", description: "the platform's to choose now; ignored, and said so" },
+    "no-enrich": {
+      type: "boolean",
+      description: "draw from --instruction as written, without the platform writing a fuller one from it and the style guide; not a UI's"
+    },
     yes: { type: "boolean", short: "y", description: "start it without asking, once what it uses of your limit is said" },
     as: { type: "string", value: "<name>", description: "land it under this name instead of the platform's" },
     aside: { type: "boolean", description: "keep a folder's own map and art under pixelvibing/before-platform/, and write it from the platform" }
@@ -4752,7 +4762,7 @@ const move = {
     );
   }
 };
-const version = "0.49.1";
+const version = "0.50.0";
 const manifest = {
   version
 };
@@ -4767,7 +4777,7 @@ function mcpEntry(apiUrl) {
   if (apiUrl === DEFAULT_API_URL) return { url: DEFAULT_MCP_URL, headers: `npx --yes ${PINNED_PACKAGE} mcp headers` };
   return { url: `${apiUrl}/mcp`, headers: `npx --yes ${PINNED_PACKAGE} mcp headers --api ${apiUrl}` };
 }
-async function textOf(path) {
+async function textOf$1(path) {
   try {
     return await readFile(path, "utf8");
   } catch (error) {
@@ -4820,7 +4830,7 @@ function codexWith(text2, entry, onlyWhereConfigured) {
 async function configureHarness(root, harness, entry, onlyWhereConfigured = false) {
   const file = harness === "claude" ? CLAUDE_FILE : CODEX_FILE;
   const path = join(root, file);
-  const text2 = await textOf(path);
+  const text2 = await textOf$1(path);
   const next = harness === "claude" ? claudeWith(text2, entry, onlyWhereConfigured) : codexWith(text2, entry, onlyWhereConfigured);
   if (next === null) return "absent";
   if (next === text2) return "current";
@@ -4956,9 +4966,127 @@ async function updateSkills(root, skills) {
   }
   return updated;
 }
+const BLOCK_OPEN = "<!-- pixelvibing:skills -->";
+const BLOCK_CLOSE = "<!-- /pixelvibing:skills -->";
+const ROUTED_FILES = [
+  { file: "AGENTS.md", made: true },
+  { file: "CLAUDE.md", made: false }
+];
+function descriptionOf(skill) {
+  return /^---\n(?:.*\n)*?description: (.+)\n(?:.*\n)*?---\n/.exec(skill.text)?.[1]?.trim() ?? "";
+}
+function routingBlock(skills) {
+  const lines = skills.map((skill) => `- \`${skill.name}\` — ${descriptionOf(skill)}`);
+  return [
+    BLOCK_OPEN,
+    "## PixelVibing art",
+    "",
+    "This game's art is made on PixelVibing. Before making, finding, pulling or exporting any of it,",
+    "load the Skill for the request from `.claude/skills/` or `.codex/skills/` and follow it,",
+    "starting with `pixelvibing`. Never write a PixelVibing token into a file or a command.",
+    "",
+    ...lines,
+    BLOCK_CLOSE
+  ].join("\n");
+}
+function markerLines(text2, marker) {
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  return [...text2.matchAll(new RegExp(`^[ \\t]*${escaped}[ \\t]*(?=\\r?$)`, "gm"))].map((found) => ({
+    start: found.index,
+    end: found.index + found[0].length
+  }));
+}
+function withBlock(text2, block) {
+  const newline = text2.includes("\r\n") ? "\r\n" : "\n";
+  const written = block.replace(/\n/g, newline);
+  const opens = markerLines(text2, BLOCK_OPEN);
+  const closes = markerLines(text2, BLOCK_CLOSE);
+  if (opens.length === 0 && closes.length === 0) {
+    const before = text2.replace(/(\r?\n)*$/, "");
+    return `${before === "" ? "" : `${before}${newline}${newline}`}${written}${newline}`;
+  }
+  const [open] = opens;
+  const [close] = closes;
+  if (opens.length !== 1 || closes.length !== 1 || open === void 0 || close === void 0 || close.start < open.end) return null;
+  return `${text2.slice(0, open.start)}${written}${text2.slice(close.end)}`;
+}
+async function writablePath(root, path) {
+  let linked;
+  try {
+    linked = (await lstat(path)).isSymbolicLink();
+  } catch (error) {
+    if (error.code === "ENOENT") return path;
+    throw error;
+  }
+  if (!linked) return path;
+  let target;
+  try {
+    target = await realpath$1(path);
+  } catch {
+    return null;
+  }
+  const within = relative(await realpath$1(root), target);
+  return within !== "" && !within.startsWith("..") && !isAbsolute(within) ? target : null;
+}
+async function textOf(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function replaceFile(path, text2) {
+  const aside = join(dirname(path), `.${basename(path)}.pixelvibing-${process.pid}`);
+  await writeFile(aside, text2);
+  try {
+    await rename(aside, path);
+  } catch (error) {
+    await rm(aside, { force: true });
+    throw error;
+  }
+}
+async function writeRouting(root, skills) {
+  const block = routingBlock(skills);
+  const routed = [];
+  for (const { file, made } of ROUTED_FILES) {
+    const path = await writablePath(root, join(root, file));
+    if (path === null) {
+      routed.push({ file, state: "outside" });
+      continue;
+    }
+    const text2 = await textOf(path);
+    if (text2 === null && !made) {
+      routed.push({ file, state: "absent" });
+      continue;
+    }
+    const next = withBlock(text2 ?? "", block);
+    if (next === null) routed.push({ file, state: "unreadable" });
+    else if (next === text2) routed.push({ file, state: "current" });
+    else {
+      await replaceFile(path, next);
+      routed.push({ file, state: "written" });
+    }
+  }
+  return routed;
+}
+function routingWords(routed) {
+  const why = {
+    unreadable: `holds ${BLOCK_OPEN} and ${BLOCK_CLOSE} other than once each, on lines of their own, in that order`,
+    outside: "is a link to a file outside this repository"
+  };
+  return {
+    done: routed.filter((each) => each.state === "written").map((each) => `named the Skills to load in ${each.file}`),
+    warnings: routed.flatMap((each) => {
+      const reason = why[each.state];
+      return reason === void 0 ? [] : [`${each.file} ${reason}: it was left as it is.
+`];
+    })
+  };
+}
 const setup = {
   name: "setup",
-  summary: "Sign in, make and link the local project, and install the Skills, doing only what is missing",
+  summary: "Sign in, make and link the local project, install the Skills and name them in AGENTS.md, doing only what is missing",
   usage: "[--harness claude|codex]… [--project <id|name> | --idea <text>] [--name <name>] [--provider <name>]",
   options: {
     harness: {
@@ -5005,19 +5133,24 @@ const setup = {
 `);
       }
     }
+    const routing = await writeRouting(local.root, skills);
+    const said = routingWords(routing);
+    done.push(...said.done);
+    for (const warning of said.warnings) context.io.warn(warning);
     answer(
       context,
-      { root: local.root, project: linked, harnesses: installed },
+      { root: local.root, project: linked, harnesses: installed, routing },
       done.length === 0 ? "Nothing to do: this repository is set up." : `Set up: ${done.join("; ")}.`
     );
   }
 };
 const update = {
   name: "update",
-  summary: "Replace the installed Skills this CLI ships differently, and add those it ships since",
+  summary: "Replace the installed Skills this CLI ships differently, add those it ships since, and name them in AGENTS.md",
   run: async (context) => {
     const local = await projectHere(context.io.cwd);
-    const updated = await updateSkills(local.root, await shippedSkills());
+    const skills = await shippedSkills();
+    const updated = await updateSkills(local.root, skills);
     if (updated.length === 0) throw new CliError("no Skills of this CLI are installed here: `pixel-vibing-cli setup` installs them");
     const entry = mcpEntry(apiUrlOf(context));
     const harnesses = [];
@@ -5027,7 +5160,11 @@ const update = {
       ...result.installed.map((name) => `installed ${HARNESSES[result.harness]}/skills/${name}`),
       ...result.mcp === "written" ? [`brought the MCP server in ${HARNESS_FILES[result.harness]} to this version`] : []
     ]);
-    answer(context, { harnesses }, written.length === 0 ? "The Skills are current." : `Updated: ${written.join("; ")}.`);
+    const routing = await writeRouting(local.root, skills);
+    const said = routingWords(routing);
+    written.push(...said.done);
+    for (const warning of said.warnings) context.io.warn(warning);
+    answer(context, { harnesses, routing }, written.length === 0 ? "The Skills are current." : `Updated: ${written.join("; ")}.`);
   }
 };
 const PROGRAM = "pixel-vibing-cli";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelvibing/cli",
-  "version": "0.49.1",
+  "version": "0.50.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: Make pixel art for this game with pixel-vibing-cli — objects, creatures, concept art and interface art (a UI laid out as JSON, skill and item icons) generated on the PixelVibing platform, listed, pulled into the project's art and its folder, and exported or sealed for the game. Use when the game needs a sprite, a prop, a creature, concept art to draw from, a level's art, its HUD or its icons, or art already made for it.
+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.
 ---
 
 # PixelVibing art for this game
@@ -10,78 +10,60 @@ and the platform project it generates for; `pixelvibing/` holds its art. The pla
 keeps every asset, and `pixelvibing/` holds only what was pulled from it. Nothing written
 there is ever sent back: art enters the project only by being generated.
 
-Every command below takes `--json`, which prints its answer as JSON on standard output.
-Progress and errors go to standard error, and a failure exits 1.
+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.
+- **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.
+   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`.
    - 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.
-2. Read `pixelvibing/style-guide.md`, or run `pixel-vibing-cli guide show`, 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 `pixelvibing-style-guide` Skill says
-   when the guide itself should change.
-
-## Generating
-
-```bash
-pixel-vibing-cli generate object --instruction "<what>" --size <cols>x<rows> --yes --json
-pixel-vibing-cli generate creature --instruction "<what>" [--reference <png>]... --yes --json
-pixel-vibing-cli generate concept-art --instruction "<what>" [--size <w>x<h>] [--transparent] [--tag <tag>]... --yes --json
-pixel-vibing-cli generate concept-art --instruction "<what>" --pixel-art --tiles <cols>x<rows> --yes --json
-pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|item> [--size <16|32|64>] --yes --json
-pixel-vibing-cli generate ui --sketch <file.json> --instruction "<the set, in a line>" --yes --json
-```
-
-Each generation uses part of the account's usage limit for the month.
-- **What it uses.** The command prints the most it uses and what is left, as shares of the
-  limit, before it starts. Without `--yes` it asks, and with nobody at the terminal it starts
-  nothing. Tell the person how much of their limit a batch will use before you start one.
-- **The instruction.** Describe the thing as a person would: its look, its material, what
-  it is for in the game. Describe the thing itself, not a prompt for a model.
-- **The options.**
-  - `--size` is an object's footprint in whole tiles, `1x1` unless given.
-  - `--tiles` is how many tiles a pixel-art concept art is across, `6x4` unless given.
-  - No quality is given: the platform draws each asset at the quality it needs. The share
-    printed is the most it may use, and what it does not use is given back.
-  - `--reference` is a PNG to draw from, repeated for several: at most 8 for an object
-    or a concept art, 3 for a creature or a UI, none for icons. A UI's references are a style
-    to follow (frames, materials, a way of drawing), never what to draw.
-- **Concept art.** The free kind: reference art, a place, a character sheet, a sample menu —
-  whatever the instruction asks. It is drawn as ordinary art, not pixel art, to draw the
-  rest from: make one first, tagged `anchor`, and pass its pulled picture
-  (`pixelvibing/ref/<name>.png`) as `--reference` to what follows.
-  - `--size` is its size in px, `<w>x<h>`, multiples of 16 within `1536x1024` or
-    `1024x1536`, `1536x1024` unless given. `--transparent` cuts its background away, for
-    one thing alone.
-  - `--pixel-art` draws it as a level design instead: pixel art of an area some `--tiles`
-    across, which the editor takes apart into objects and terrain.
-  - `--tag` says what it is for, repeated for several, at most 8: `anchor`, `level-design`,
-    `ui`, `character`, `environment`, `prop`, or one of the project's own.
-- **Interface art.** When the game shows the player something over the world, make it here
-  rather than drawing it in code:
-  - `icons` makes up to 16 icons that match, from `--names`: `--purpose skill` for a
-    hotbar or a skill tree (each on a square badge), `--purpose item` for an inventory,
-    potions or loot (each alone). `--size` is 16, 32 (the default) or 64 px.
-  - `ui` draws a game's interface (a HUD, a menu, an inventory) from a layout in JSON:
-    a canvas and up to 16 components, each with a `label` (its role, never drawn), a
-    `kind` (`rect`, `ellipse` or `polygon`), its position and size (`x`, `y`, `width`,
-    `height` in the canvas's pixels) and, as it needs, `caption` (text drawn on it), `note`
-    (how it looks), `border` (a frame that stretches by nine-slice) and `hollow` (its inside
-    transparent). Read `references/ui.md` before writing one: it gives every field and rule,
-    `references/ui.schema.json` is the JSON Schema the file follows (name it with
-    `"$schema"`), and `references/ui.example.json` is a whole HUD laid out. Each component
-    comes back as its own piece. `ui-sketch` is the same kind by its platform name.
-  - The art never carries text or numbers, but a UI's captions: draw labels,
-    counts and values in the game.
-- **Success.** The asset is pulled at once. The answer's `files` are where its pictures
-  are, relative to `pixelvibing/`.
+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
+   `pixelvibing-style-guide` Skill says when the guide itself should change.
+
+## Which Skill makes what
+
+Load the Skill for the kind before you generate it:
+
+| The game needs | Skill |
+|---|---|
+| a prop, an item, a building, a piece of scenery | `pixelvibing-object` |
+| a character, an enemy, an animal, a monster | `pixelvibing-creature` |
+| 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.
+
+## What every generation shares
+
+- **The limit.** Each generation uses part of the account's usage limit for the month. The
+  CLI prints the most it uses and what is left, as shares of the limit, before it starts;
+  without `--yes` it asks, and with nobody at the terminal it starts nothing. The MCP
+  server's `get_prices` says each kind's most, and `generate` starts only within
+  `max_percent`. Tell the person how much of their limit a batch will use before you start one.
+- **The quality** is the platform's to choose. What a generation does not use is given back.
+- **Enrichment.** Unless told otherwise, the platform writes a fuller instruction from yours
+  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.
+- **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.
 - **Failure.** A reached limit starts nothing and names the page where the person adds to
-  it with a pack or a plan: tell them, and do not retry. A failed job prints its reason.
+  it with a pack or a plan: tell them, and do not retry. A failed job says its reason.
 
 ## Listing and pulling
 
@@ -91,6 +73,9 @@ pixel-vibing-cli pull <id|name> [--as <name>] --json
 pixel-vibing-cli tag <id|name> [<tag>...] [--none] --json
 ```
 
+MCP: `list_assets`, `get_asset` (its images, each with an address that downloads it),
+`list_concept_art`, `list_references`, `list_tags`, `tag_asset`.
+
 - **Listing.** `list` answers the newest 50 assets. When there are more, it gives a
   `next` id for `--before`. A kind is the generation that made the asset: `object`,
   `creature`, `concept-art`, `rotate`, `animate`… `--tag` lists only the concept art
@@ -101,8 +86,8 @@ pixel-vibing-cli tag <id|name> [<tag>...] [--none] --json
   sees it too, and then writes the folder from the platform. An asset of one picture
   lands as `<name>`, one of several as `<name>/<n>`; an icon set's pieces as `ui/icon/<name>`
   and a UI's as `ui/sketch/<label>`, each under `pixelvibing/out/`. A concept art is kept
-  as a reference, under
-  `pixelvibing/ref/`. Pulling again lands nothing while the art still holds it.
+  as a reference, under `pixelvibing/ref/`. Pulling again lands nothing while the art
+  still holds it.
 - **Collisions.** `pull` lands nothing under a name the art holds for something else. When
   it refuses, give the asset another name with `--as`. A terrain set is landed from the
   editor's Library, never from `pull`.

package/skills/pixelvibing-change/SKILL.md

@@ -0,0 +1,42 @@
+---
+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.
+---
+
+# 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.
+
+## 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.
+
+## The kinds
+
+```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": "animate", "source_image": "<image id>", "instruction": "walks to the right", "enrich": false, "max_percent": 40 }
+```
+
+- **`variant`** draws another of an object, keeping what makes it that object; the
+  instruction says what differs.
+- **`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.
+- **`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.
+
+`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.
+
+## Not here
+
+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`.

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

@@ -0,0 +1,56 @@
+---
+name: pixelvibing-concept-art
+description: Generate concept art for this game on PixelVibing — the anchor look everything holds to, a place, a character sheet, a sample menu, or a level design drawn as pixel art to take apart — with pixel-vibing-cli or the PixelVibing MCP server's generate tool, and tag it for what it is for. Use before a set of assets, so they draw from one look, or to lay out an area of a level.
+---
+
+# Concept art
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+Concept art is the free kind: whatever the instruction asks, drawn as ordinary art, not
+pixel art, to draw the rest from. Make one first, tagged `anchor`, and pass it as a
+reference to what follows.
+
+## With the CLI
+
+```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
+```
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "kind": "concept-art", "instruction": "<the picture>",
+  "size": { "width": 1536, "height": 1024 }, "background": "transparent", "tags": ["anchor"],
+  "reference_images": ["<image id>"], "enrich": false, "max_percent": 40 }
+{ "project": "<id>", "kind": "concept-art", "instruction": "<the area>", "pixel_art": true,
+  "tiles": { "cols": 6, "rows": 4 }, "max_percent": 40 }
+```
+
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` keeps it under
+`pixelvibing/ref/`. `list_concept_art` (by a tag too) answers each concept art's image ids,
+which every other generation takes as `reference_images`.
+
+## Writing it
+
+- **The instruction.** Brief it as an art director would: what is in the picture, where,
+  how it looks, the light, and how its parts meet. Use the style guide's words.
+- **The size.** `--size` (MCP `size`) in px, `<w>x<h>`, multiples of 16 within `1536x1024`
+  or `1024x1536`, `1536x1024` unless given. `--transparent` (`background: "transparent"`)
+  cuts the background away, for one thing alone.
+- **Tags** say what it is for, at most 8: `anchor` (the look everything holds to),
+  `level-design`, `ui`, `character`, `environment`, `prop`, or one of the project's own
+  (`list_tags`). `pixel-vibing-cli tag` (MCP `tag_asset`) changes them later.
+- **References.** Up to 8 to draw from, such as the anchor itself.
+- **A level design.** `--pixel-art --tiles <c>x<r>` (MCP `pixel_art`, `tiles`) draws an area
+  of the map as pixel art some tiles across, `6x4` unless given, tagged `level-design`; the
+  editor takes it apart into objects and terrain.
+- **Enrichment.** Pass `--no-enrich` (`enrich: false`) when the brief above is complete;
+  leave it on when all you have is the person's few words.
+
+## After
+
+- Pass its picture, `pixelvibing/ref/<name>.png`, as `--reference` (or its image id as
+  `reference_images`) to the objects, creatures and UI that should match it.
+- Concept art is a reference, not game art: it is never exported.

package/skills/pixelvibing-creature/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pixelvibing-creature
+description: Generate one creature for this game on PixelVibing — a hero, a villager, an enemy, an animal, a monster — standing whole on one tile, with pixel-vibing-cli or the PixelVibing MCP server's generate tool. Use when the game needs a character drawn, before it is animated or turned.
+---
+
+# A creature
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+## With the CLI
+
+```bash
+pixel-vibing-cli generate creature --instruction "<who>" [--reference <png>]... [--no-enrich] --yes --json
+```
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "kind": "creature", "instruction": "<who>", "reference_images": ["<image id>"],
+  "enrich": false, "max_percent": 40 }
+```
+
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands it.
+
+## Writing it
+
+- **The instruction.** One or two sentences: its body and build, its colours, what it
+  wears or carries, and its part in the game ("the blacksmith who sells blades"). Use the
+  style guide's words for the look; never restate its camera or outline. No other game's
+  characters or names, and no text in the picture: when the person names a franchise, make
+  original art in its spirit and say so.
+- **One creature, standing.** It is drawn whole, standing, on one tile. A pose, a crowd or a
+  scene is concept art (`pixelvibing-concept-art`).
+- **References.** Up to 3: a character sheet or a concept art tagged `character` or
+  `anchor` keeps it on model.
+- **Enrichment.** Pass `--no-enrich` (`enrich: false`) when the instruction above is
+  complete; leave it on when all you have is the person's few words.
+
+## 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`.

package/skills/pixelvibing-icons/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pixelvibing-icons
+description: Generate a set of up to 16 matching icons for this game on PixelVibing — skills on square badges for a hotbar or a skill tree, or items alone for an inventory, potions or loot — with pixel-vibing-cli or the PixelVibing MCP server's generate tool. Use when the game shows the player icons rather than drawing them in code.
+---
+
+# An icon set
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+## With the CLI
+
+```bash
+pixel-vibing-cli generate icons --names "<name>,<name>,..." --purpose <skill|item> [--size <16|32|64>] [--instruction "<theme>"] [--no-enrich] --yes --json
+```
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "kind": "icons", "names": ["fire bolt", "ice wall"], "purpose": "skill",
+  "icon_size": 32, "instruction": "<theme>", "enrich": false, "max_percent": 40 }
+```
+
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each icon.
+
+## Writing it
+
+- **The names.** One per icon, at most 16, none twice: what the skill or the item is, in a
+  few words ("red health potion", "rusty key"). Make a whole set in one generation, so the
+  icons match.
+- **The purpose.** `skill` draws each on a square badge, for a hotbar or a skill tree;
+  `item` draws each alone, for an inventory or loot; `item` unless given.
+- **The size.** 16, 32 or 64 px a side, 32 unless given: the size the game shows them at.
+- **The theme.** `--instruction` is optional: what the icons have in common, their colours
+  and framing. Use the style guide's words.
+- **No references.** An icon never carries text or numbers: draw counts and labels in the game.
+- **Enrichment.** Pass `--no-enrich` (`enrich: false`) when the theme is complete; leave it
+  on when all you have is the person's few words.
+
+## After
+
+- Each lands as `pixelvibing/out/ui/icon/<name>.png`.
+- More icons later: a new set, with the first set's theme, so they still match.

package/skills/pixelvibing-object/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pixelvibing-object
+description: Generate one object for this game on PixelVibing — a prop, an item, a building, a tree, a piece of scenery — on a footprint of whole tiles, with pixel-vibing-cli or the PixelVibing MCP server's generate tool. Use when the game needs one thing that stands on the map or sits in an inventory.
+---
+
+# An object
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+## With the CLI
+
+```bash
+pixel-vibing-cli generate object --instruction "<what>" --size <cols>x<rows> [--reference <png>]... [--no-enrich] --yes --json
+```
+
+## With the MCP server
+
+```json
+{ "project": "<id>", "kind": "object", "instruction": "<what>", "size": { "cols": 1, "rows": 1 },
+  "reference_images": ["<image id>"], "enrich": false, "max_percent": 40 }
+```
+
+`get_prices` gives `max_percent`'s floor; `get_job` follows the job; then
+`pixel-vibing-cli pull <job id>` lands it under `pixelvibing/out/`.
+
+## Writing it
+
+- **The instruction.** One or two sentences of the thing itself: its shape, its material
+  and colours, the details that make it read at its size, and what it is for in the game.
+  Use the style guide's words for the look; never restate its camera or outline, the
+  platform adds them. No artist's or other game's names, and no text in the picture.
+- **The footprint.** `--size` (MCP `size`) is how many tiles it stands on, `1x1` unless
+  given: a crate is `1x1`, a cart `2x1`, a house `3x3`. The platform sizes the drawing to the
+  project's tile size.
+- **References.** Up to 8 pictures to draw from: a concept art tagged `anchor` keeps every
+  object on one look (`pixelvibing/ref/<name>.png` for the CLI, its image id from
+  `list_concept_art` for MCP), and a sketch or an earlier object keeps a shape.
+- **Enrichment.** Pass `--no-enrich` (`enrich: false`) when the instruction above is
+  complete; leave it on when all you have is the person's few words.
+
+## After
+
+- It lands as `pixelvibing/out/<name>.png`, named from what was drawn; `--as` lands it under
+  another name.
+- Another like it, a change to it, or setting it in motion: the `pixelvibing-change` Skill.
+- Never generate the same object again to fix a detail: change it, or open the editor.

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

@@ -38,5 +38,9 @@ Do not change it for one asset: say that in the asset's instruction instead.
      top, and push.
 4. `pixel-vibing-cli guide versions` lists every version, with how and when each was made.
 
+The MCP server reaches the same guide: `get_style_guide` reads it, `write_style_guide` keeps a
+new version on top of the one you read (its `base`), and `revise_style_guide` asks for a
+revision by an instruction. After either, `pixel-vibing-cli guide pull` brings the file up to date.
+
 Tell the person what you changed and why, since the guide shapes every later generation.
 Art made before the change was made under the old guide, and nothing remakes it by itself.

package/skills/pixelvibing-ui/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pixelvibing-ui
+description: Generate a game's interface on PixelVibing — a HUD, a menu, an inventory, a dialog box — from a layout of up to 16 labelled shapes in JSON, each drawn as its own matching piece that stretches by nine-slice, with pixel-vibing-cli or the PixelVibing MCP server's generate tool. Use when the game shows the player an interface over the world, rather than drawing one in code.
+---
+
+# A UI
+
+Load the `pixelvibing` Skill first: who is signed in, the style guide, the limit.
+
+Read `references/ui.md` before writing a layout: it gives every field and rule.
+`references/ui.schema.json` is the JSON Schema the file follows (name it with `"$schema"`),
+and `references/ui.example.json` is a whole HUD laid out.
+
+## With the CLI
+
+```bash
+pixel-vibing-cli generate ui --sketch <file.json> --instruction "<the set, in a line>" [--reference <png>]... --yes --json
+```
+
+## With the MCP server
+
+The layout goes in the call itself, as `canvas` and `shapes`, with the same fields:
+
+```json
+{ "project": "<id>", "kind": "ui-sketch", "instruction": "gothic iron with green enamel",
+  "canvas": { "width": 256, "height": 256 },
+  "shapes": [{ "label": "Health bar", "kind": "rect", "x": 8, "y": 8, "width": 96, "height": 16, "border": 2, "note": "a full red health bar" }],
+  "reference_images": ["<image id>"], "max_percent": 40 }
+```
+
+`get_job` follows the job; then `pixel-vibing-cli pull <job id>` lands each piece.
+
+## Writing it
+
+- **The instruction** is the set's theme in a line, up to 600 characters; what each piece
+  is goes in its `label` and `note`.
+- **References**, up to 3, are a style to follow (frames, materials, a way of drawing),
+  never what to draw. A concept art tagged `ui` is the usual one.
+- **Text.** Only a `caption` is drawn as text. Counts, values and names change in play: the
+  game draws them.
+- **No enrichment switch.** A UI's layout is read as it is; `--no-enrich` and `enrich` are
+  refused for it.
+- `ui-sketch` is the same kind by its platform name.
+
+## After
+
+- Each piece lands as `pixelvibing/out/ui/sketch/<label>.png`, a framed one with its
+  nine-slice insets, which an export carries to the engine.