#!/usr/bin/env python3
"""Conservative background removal and validation for PixelLab outputs.

This helper is intentionally deterministic. It removes:
- edge-connected pixels matching the sampled background color.

It also analyzes enclosed background-colored components so callers can safely
fall back to PixelLab when local deterministic removal is uncertain.

It never repaints RGB values. Removed pixels keep their original RGB and get
alpha set to 0.
"""

from __future__ import annotations

import argparse
import json
import sys
from collections import Counter, deque
from pathlib import Path
from typing import Any

try:
    from PIL import Image
except ImportError as exc:  # pragma: no cover - exercised by missing runtime
    print(f"error: Pillow is required: {exc}", file=sys.stderr)
    sys.exit(3)


RGBA = tuple[int, int, int, int]
RGB = tuple[int, int, int]


def parse_rgb(value: str) -> RGB | None:
    if value == "auto":
        return None
    parts = value.split(",")
    if len(parts) != 3:
        raise argparse.ArgumentTypeError("expected auto or R,G,B")
    try:
        rgb = tuple(int(part) for part in parts)
    except ValueError as exc:
        raise argparse.ArgumentTypeError("RGB values must be integers") from exc
    if any(channel < 0 or channel > 255 for channel in rgb):
        raise argparse.ArgumentTypeError("RGB values must be 0..255")
    return rgb  # type: ignore[return-value]


def pixel_luma(pixel: RGBA) -> float:
    r, g, b, _ = pixel
    return 0.2126 * r + 0.7152 * g + 0.0722 * b


def pixel_saturation(pixel: RGBA) -> int:
    r, g, b, _ = pixel
    return max(r, g, b) - min(r, g, b)


def color_close(pixel: RGBA, bg: RGB, tolerance: int) -> bool:
    if pixel[3] == 0:
        return False
    return max(abs(pixel[i] - bg[i]) for i in range(3)) <= tolerance


def idx_to_xy(index: int, width: int) -> tuple[int, int]:
    return index % width, index // width


def neighbors4(index: int, width: int, height: int) -> list[int]:
    x, y = idx_to_xy(index, width)
    out: list[int] = []
    if x > 0:
        out.append(index - 1)
    if x + 1 < width:
        out.append(index + 1)
    if y > 0:
        out.append(index - width)
    if y + 1 < height:
        out.append(index + width)
    return out


def neighbors8(index: int, width: int, height: int) -> list[int]:
    x, y = idx_to_xy(index, width)
    out: list[int] = []
    for dy in (-1, 0, 1):
        yy = y + dy
        if yy < 0 or yy >= height:
            continue
        for dx in (-1, 0, 1):
            if dx == 0 and dy == 0:
                continue
            xx = x + dx
            if 0 <= xx < width:
                out.append((yy * width) + xx)
    return out


def sample_background(
    pixels: list[RGBA], width: int, height: int, min_edge_share: float
) -> tuple[RGB, dict[str, Any]]:
    edge: list[RGB] = []
    for x in range(width):
        for index in (x, ((height - 1) * width) + x):
            pixel = pixels[index]
            if pixel[3] > 0:
                edge.append(pixel[:3])
    for y in range(1, height - 1):
        for index in ((y * width), (y * width) + width - 1):
            pixel = pixels[index]
            if pixel[3] > 0:
                edge.append(pixel[:3])
    if not edge:
        raise ValueError("no opaque edge pixels available for background sampling")
    color, count = Counter(edge).most_common(1)[0]
    share = count / len(edge)
    report = {
        "edge_opaque_pixels": len(edge),
        "edge_dominant_rgb": color,
        "edge_dominant_count": count,
        "edge_dominant_share": round(share, 3),
    }
    if share < min_edge_share:
        raise ValueError(
            "auto background sampling is ambiguous; pass --bg-color R,G,B "
            f"or use PixelLab fallback (dominant edge share {share:.3f})"
        )
    return color, report


def flood_edge_background(bg_like: list[bool], width: int, height: int) -> set[int]:
    queue: deque[int] = deque()
    seen: set[int] = set()

    for x in range(width):
        queue.append(x)
        queue.append(((height - 1) * width) + x)
    for y in range(height):
        queue.append(y * width)
        queue.append((y * width) + width - 1)

    while queue:
        index = queue.popleft()
        if index in seen or not bg_like[index]:
            continue
        seen.add(index)
        for neighbor in neighbors4(index, width, height):
            if neighbor not in seen and bg_like[neighbor]:
                queue.append(neighbor)
    return seen


def connected_components(mask: list[bool], width: int, height: int) -> list[list[int]]:
    visited: set[int] = set()
    components: list[list[int]] = []

    for start, enabled in enumerate(mask):
        if not enabled or start in visited:
            continue
        component: list[int] = []
        queue: deque[int] = deque([start])
        visited.add(start)
        while queue:
            index = queue.popleft()
            component.append(index)
            for neighbor in neighbors4(index, width, height):
                if mask[neighbor] and neighbor not in visited:
                    visited.add(neighbor)
                    queue.append(neighbor)
        components.append(component)
    return components


def component_bbox(component: list[int], width: int) -> tuple[int, int, int, int]:
    xs: list[int] = []
    ys: list[int] = []
    for index in component:
        x, y = idx_to_xy(index, width)
        xs.append(x)
        ys.append(y)
    return min(xs), min(ys), max(xs), max(ys)


def touches_exterior(index: int, exterior: set[int], width: int, height: int) -> bool:
    return any(neighbor in exterior for neighbor in neighbors8(index, width, height))


def classify_enclosed_component(
    component: list[int],
    *,
    pixels: list[RGBA],
    component_mask: set[int],
    exterior: set[int],
    outline_mask: list[bool],
    width: int,
    height: int,
    min_area: int,
    max_area_ratio: float,
    outline_coverage: float,
    max_exterior_outline_ratio: float,
) -> dict[str, Any]:
    image_area = width * height
    area = len(component)
    boundary: set[int] = set()
    direct_exterior = 0

    for index in component:
        for neighbor in neighbors8(index, width, height):
            if neighbor not in component_mask:
                boundary.add(neighbor)
                if neighbor in exterior:
                    direct_exterior += 1

    outline = [index for index in boundary if outline_mask[index]]
    exterior_outline = [
        index for index in outline if touches_exterior(index, exterior, width, height)
    ]
    opaque_boundary = [index for index in boundary if pixels[index][3] > 0]

    outline_ratio = len(outline) / max(1, len(opaque_boundary))
    exterior_outline_ratio = len(exterior_outline) / max(1, len(outline))
    bbox = component_bbox(component, width)

    report = {
        "area": area,
        "bbox": bbox,
        "boundary_pixels": len(boundary),
        "outline_ratio": round(outline_ratio, 3),
        "exterior_outline_ratio": round(exterior_outline_ratio, 3),
        "direct_exterior_contacts": direct_exterior,
    }

    if area < min_area:
        report["reason"] = "too_small"
        return report
    if area / image_area > max_area_ratio:
        report["reason"] = "too_large"
        return report
    if direct_exterior:
        report["reason"] = "touches_exterior_background"
        return report
    if outline_ratio < outline_coverage:
        report["reason"] = "weak_outline_boundary"
        return report
    if exterior_outline_ratio > max_exterior_outline_ratio:
        report["reason"] = "mostly_exterior_silhouette_outline"
        return report

    report["reason"] = "strong_outline_enclosed_bg_like"
    return report


def remove_background(args: argparse.Namespace) -> dict[str, Any]:
    source = Path(args.input)
    target = Path(args.output)
    if not source.exists():
        raise FileNotFoundError(source)

    image = Image.open(source).convert("RGBA")
    width, height = image.size
    pixels: list[RGBA] = list(image.getdata())

    if args.bg_color is not None:
        bg_color = args.bg_color
        sample_report: dict[str, Any] = {
            "mode": "explicit",
            "background_rgb": bg_color,
        }
    else:
        bg_color, sample_report = sample_background(
            pixels, width, height, args.min_edge_color_share
        )
        sample_report["mode"] = "auto"
    bg_like = [color_close(pixel, bg_color, args.tolerance) for pixel in pixels]

    exterior = flood_edge_background(bg_like, width, height)
    original_opaque = sum(1 for pixel in pixels if pixel[3] > 0)

    outline_mask = [
        pixel[3] > 0
        and not bg_like[index]
        and (
            pixel_luma(pixel) <= args.outline_luma
            or (
                pixel_luma(pixel) <= args.gray_outline_luma
                and pixel_saturation(pixel) <= args.gray_outline_saturation
            )
        )
        for index, pixel in enumerate(pixels)
    ]

    remaining_bg = [
        is_bg and index not in exterior for index, is_bg in enumerate(bg_like)
    ]
    components = connected_components(remaining_bg, width, height)

    remove: set[int] = set(exterior)
    enclosed_components: list[dict[str, Any]] = []

    for component in components:
        component_mask = set(component)
        component_report = classify_enclosed_component(
            component,
            pixels=pixels,
            component_mask=component_mask,
            exterior=exterior,
            outline_mask=outline_mask,
            width=width,
            height=height,
            min_area=args.min_enclosed_area,
            max_area_ratio=args.max_enclosed_area_ratio,
            outline_coverage=args.outline_coverage,
            max_exterior_outline_ratio=args.max_exterior_outline_ratio,
        )
        enclosed_components.append(component_report)

    output_pixels: list[RGBA] = []
    for index, pixel in enumerate(pixels):
        if index in remove and pixel[3] != 0:
            output_pixels.append((pixel[0], pixel[1], pixel[2], 0))
        else:
            output_pixels.append(pixel)

    output = Image.new("RGBA", (width, height))
    output.putdata(output_pixels)
    target.parent.mkdir(parents=True, exist_ok=True)
    output.save(target)

    significant_unresolved = [
        component
        for component in enclosed_components
        if component["reason"] != "too_small"
        and component["area"] >= args.min_enclosed_area
    ]
    remaining_bg_like = [
        index
        for index, is_bg in enumerate(bg_like)
        if is_bg and index not in remove and pixels[index][3] > 0
    ]
    remaining_opaque = sum(
        1 for index, pixel in enumerate(pixels) if index not in remove and pixel[3] > 0
    )
    removed_opaque = original_opaque - remaining_opaque
    removed_opaque_ratio = removed_opaque / max(1, original_opaque)
    enclosed_reasons = Counter(component["reason"] for component in enclosed_components)
    fallback_reasons: list[str] = []
    if remaining_bg_like:
        fallback_reasons.append("remaining_background_like_pixels")
    if significant_unresolved:
        fallback_reasons.append("significant_unresolved_enclosed_components")
    if removed_opaque_ratio >= args.max_removed_opaque_ratio:
        fallback_reasons.append("nearly_all_opaque_pixels_removed")
    if len(exterior) == 0:
        fallback_reasons.append("no_edge_connected_background_removed")
    status = "needs_pixellab_fallback" if fallback_reasons else "passed_conservative_checks"
    report: dict[str, Any] = {
        "input": str(source),
        "output": str(target),
        "width": width,
        "height": height,
        "background_rgb": bg_color,
        "background_sample": sample_report,
        "tolerance": args.tolerance,
        "removed_edge_connected_pixels": len(exterior),
        "removed_enclosed_pixels": 0,
        "original_opaque_pixels": original_opaque,
        "remaining_opaque_pixels": remaining_opaque,
        "removed_opaque_ratio": round(removed_opaque_ratio, 4),
        "remaining_background_like_pixels": len(remaining_bg_like),
        "local_result_status": status,
        "fallback_reasons": fallback_reasons,
        "significant_unresolved_enclosed_component_count": len(significant_unresolved),
        "significant_unresolved_enclosed_components_sample": significant_unresolved[
            : args.max_rejected_report
        ],
        "enclosed_background_like_component_count": len(enclosed_components),
        "enclosed_background_like_component_reasons": dict(enclosed_reasons),
        "enclosed_background_like_components_sample": enclosed_components[
            : args.max_rejected_report
        ],
        "method": "edge_connected_background_removal_with_enclosed_component_validation",
    }
    return report


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Remove edge-connected pixel-art backgrounds and report enclosed uncertainty."
    )
    parser.add_argument("input", help="Input PNG path")
    parser.add_argument("output", help="Output PNG path")
    parser.add_argument(
        "--bg-color",
        default=None,
        type=parse_rgb,
        metavar="auto|R,G,B",
        help="Background RGB. Defaults to auto-sampled most common edge color.",
    )
    parser.add_argument("--tolerance", type=int, default=2)
    parser.add_argument("--min-edge-color-share", type=float, default=0.6)
    parser.add_argument("--min-enclosed-area", type=int, default=4)
    parser.add_argument("--max-enclosed-area-ratio", type=float, default=0.10)
    parser.add_argument("--outline-coverage", type=float, default=0.75)
    parser.add_argument("--max-exterior-outline-ratio", type=float, default=0.25)
    parser.add_argument("--outline-luma", type=int, default=80)
    parser.add_argument("--gray-outline-luma", type=int, default=125)
    parser.add_argument("--gray-outline-saturation", type=int, default=24)
    parser.add_argument("--max-removed-opaque-ratio", type=float, default=0.95)
    parser.add_argument("--max-rejected-report", type=int, default=25)
    parser.add_argument("--report", help="Optional JSON report path")
    parser.add_argument("--quiet", action="store_true", help="Do not print JSON report")
    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)

    if args.quiet and not args.report:
        print("error: --quiet requires --report", file=sys.stderr)
        return 2

    try:
        report = remove_background(args)
    except Exception as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2

    if args.report:
        report_path = Path(args.report)
        report_path.parent.mkdir(parents=True, exist_ok=True)
        report_path.write_text(json.dumps(report, indent=2), encoding="utf-8")

    if not args.quiet:
        print(json.dumps(report, indent=2))

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""PixelLab Pip bark helper.

This helper is intentionally small and dependency-free. It keeps the bark and
auto configuration portable with the skill first, then falls back to a user
config directory only when the installed skill directory is not writable.
Config writes are atomic and key-preserving so agents never hand-edit the JSON.
"""

from __future__ import annotations

import argparse
import json
import os
import platform
import shutil
import subprocess
import tempfile
import wave
from pathlib import Path
from typing import Any


ASSETS_DIR = Path(__file__).resolve().parent
SKILL_DIR = ASSETS_DIR.parent
SKILL_CONFIG = SKILL_DIR / "pixellab-pip.json"
BARK_WAV = ASSETS_DIR / "bark.wav"


def user_config_path() -> Path:
    system = platform.system().lower()
    home = Path.home()

    if system == "windows":
        root = os.environ.get("APPDATA")
        base = Path(root) if root else home / "AppData" / "Roaming"
    elif system == "darwin":
        base = home / "Library" / "Application Support"
    else:
        root = os.environ.get("XDG_CONFIG_HOME")
        base = Path(root) if root else home / ".config"

    return base / "pixellab-pip" / "pixellab-pip.json"


def safe_user_config_path() -> Path | None:
    try:
        return user_config_path()
    except RuntimeError:
        return None


def read_json(path: Path) -> dict[str, Any] | None:
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        # ValueError covers json.JSONDecodeError and UnicodeDecodeError (a config
        # re-saved as UTF-16/UTF-8-BOM), so a malformed file degrades to the
        # graceful invalid-config path instead of an uncaught traceback.
        return None


def normalize_bark(value: Any) -> bool:
    if isinstance(value, bool):
        return value
    return True


def has_valid_bark_value(data: dict[str, Any]) -> bool:
    return "bark" not in data or isinstance(data["bark"], bool)


def read_config() -> tuple[dict[str, Any], Path | None, Path | None]:
    invalid_source: Path | None = None
    user_config = safe_user_config_path()
    paths = [SKILL_CONFIG]
    if user_config is not None:
        paths.append(user_config)

    for path in paths:
        if path.exists():
            data = read_json(path)
            if isinstance(data, dict) and has_valid_bark_value(data):
                return data, path, invalid_source
            if invalid_source is None:
                invalid_source = path
    return {"bark": True}, None, invalid_source


def bark_enabled() -> bool:
    data, _, _ = read_config()
    return normalize_bark(data.get("bark", True))


def write_text_atomic(path: Path, content: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    temp_path: Path | None = None
    try:
        with tempfile.NamedTemporaryFile(
            "w",
            encoding="utf-8",
            dir=str(path.parent),
            delete=False,
            prefix=f".{path.name}.",
            suffix=".tmp",
        ) as handle:
            temp_path = Path(handle.name)
            handle.write(content)
        temp_path.replace(path)
        temp_path = None
    finally:
        if temp_path is not None:
            temp_path.unlink(missing_ok=True)


def write_config(key: str, enabled: bool) -> Path:
    existing, _, _ = read_config()
    existing[key] = bool(enabled)
    content = json.dumps(existing, indent=2, sort_keys=True) + "\n"

    candidates = [SKILL_CONFIG]
    user_config = safe_user_config_path()
    if user_config is not None:
        candidates.append(user_config)

    errors: list[str] = []
    for path in candidates:
        try:
            write_text_atomic(path, content)
            return path
        except OSError as exc:
            errors.append(f"{path}: {exc}")

    raise RuntimeError("; ".join(errors) or "could not write config")


def playable_wav(path: Path) -> bool:
    try:
        with wave.open(str(path), "rb"):
            return True
    except (OSError, wave.Error):
        return False


def play_sound() -> bool:
    if not BARK_WAV.exists() or not playable_wav(BARK_WAV):
        return False

    system = platform.system().lower()

    if system == "windows":
        try:
            import winsound

            winsound.PlaySound(str(BARK_WAV), winsound.SND_FILENAME)
            return True
        except Exception:
            return False

    commands = []
    if system == "darwin":
        commands.append(["afplay", str(BARK_WAV)])
    else:
        commands.extend(
            [
                ["paplay", str(BARK_WAV)],
                ["pw-play", str(BARK_WAV)],
                ["aplay", "-q", str(BARK_WAV)],
                ["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", str(BARK_WAV)],
            ]
        )

    for command in commands:
        if shutil.which(command[0]) is None:
            continue
        try:
            completed = subprocess.run(
                command,
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                check=False,
                timeout=3,
            )
            if completed.returncode == 0:
                return True
        except (OSError, subprocess.TimeoutExpired):
            continue

    return False


def main() -> int:
    parser = argparse.ArgumentParser(description="PixelLab Pip bark helper")
    parser.add_argument("command", choices=["status", "bark", "on", "off", "play", "auto", "auto-on", "auto-off"])
    args = parser.parse_args()

    result: dict[str, Any] = {
        "ok": True,
        "bark": bark_enabled(),
        "config": None,
        "played": False,
        "sound": str(BARK_WAV),
    }

    try:
        if args.command == "bark":
            result["bark"] = not bark_enabled()
            result["config"] = str(write_config("bark", bool(result["bark"])))
            if result["bark"]:
                result["played"] = play_sound()
        elif args.command == "on":
            result["bark"] = True
            result["config"] = str(write_config("bark", True))
            result["played"] = play_sound()
        elif args.command == "off":
            result["bark"] = False
            result["config"] = str(write_config("bark", False))
        elif args.command == "play":
            if bark_enabled():
                result["played"] = play_sound()
            result["bark"] = bark_enabled()
        elif args.command == "auto":
            data, _, _ = read_config()
            current = data.get("auto") is True
            result["auto"] = not current
            result["config"] = str(write_config("auto", result["auto"]))
        elif args.command == "auto-on":
            result["auto"] = True
            result["config"] = str(write_config("auto", True))
        elif args.command == "auto-off":
            result["auto"] = False
            result["config"] = str(write_config("auto", False))
        elif args.command == "status":
            data, source, invalid_source = read_config()
            result["bark"] = normalize_bark(data.get("bark", True))
            result["auto"] = data.get("auto") is True
            result["config"] = str(source) if source else None
            result["invalid_config"] = str(invalid_source) if invalid_source else None
    except Exception as exc:
        result["ok"] = False
        result["error"] = str(exc)

    print(json.dumps(result, sort_keys=True))

    if not result["ok"]:
        return 1
    if args.command == "play" and result["bark"] and not result["played"]:
        return 2
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

[
  {
    "_pixellab": {
      "api_base_url": "https://api.pixellab.ai",
      "auth": {
        "type": "bearer",
        "env": "PIXELLAB_SECRET",
        "required_before_calls": true
      },
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/aura",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Configurable themed transparent aura candidates assembled into a review spritesheet, with optional user-approved synchronized V3 animation of the sheet.",
    "_comment_prompt": "/pixellab-pip create the aura blueprint",
    "TASK": {
      "instruction": "Resolve all blueprint variables from the current request, confidently inferred context, or their defaults; resolve `''` and `\"\"` as empty strings and collapse spaces left by an empty substitution. Treat the entire user-supplied aura theme wording, including a comma-separated list, as one literal scalar value: substitute it once into the existing description, do not split it across candidates, and do not expand the static generation into multiple calls. Resolve aura size as an image_size object with positive integer width and height accepted by generate-image-v2; interpret a single size such as 64 as {\"width\": 64, \"height\": 64}. Before any PixelLab call, validate the resolved request, require explicit current-user approval, confirm PIXELLAB_SECRET exists without exposing its value, and resolve output_directory by using the declared path when available or appending the lowest available suffix starting at -2. Create that directory empty and stop if any check fails.",
      "verify": "The resolved request is valid, approval and credential presence are confirmed, and the output directory is new, empty, and writable."
    }
  },
  {
    "POST /v2/generate-image-v2": {
      "description": "fully contained symmetrical {{aura theme | default: energy}} aura with vertical power spikes and a bottom energy ring",
      "image_size": "{{aura size | default: {\"width\": 64, \"height\": 64}}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Persist the background_job_id returned by the immediately preceding PixelLab call, then poll GET /v2/background-jobs/{background_job_id} gently with backoff. Treat top-level completed or last_response completed/done as success, failed as terminal failure, and never infer completion from the first returned image alone. Re-poll the same job after transient errors and never resubmit the paid generation. After a reasonable bounded wait, if the job remains pending, stop and report the saved ID and GET /v2/background-jobs/{background_job_id} as the resume route. On failure, stop and report it. On completion, save every image from last_response.images unchanged in response order as candidate-1.png through candidate-N.png. Derive N from the completed response rather than assuming it from the requested size. Assemble every candidate once in row-major order into candidates.png with ceiling(square root of N) columns and ceiling(N divided by columns) rows, leaving any unused trailing cells transparent, with no resizing, repainting, margins, or spacing. Present every numbered candidate for user review without selecting or discarding one automatically.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "The number of saved candidate PNGs equals the number returned; every candidate matches the resolved aura size, preserves transparency, and matches its returned payload; candidates.png contains every candidate exactly once at native size and each cell matches its source pixel-for-pixel."
    }
  },
  {
    "TASK": {
      "instruction": "After presenting the static candidates, ask whether the user wants to animate the entire candidates.png spritesheet. Explain before asking that continuing runs one additional paid animate-with-text-v3 job and that V3 treats the sheet as one image, so cell isolation is not guaranteed. If the user declines, finish successfully with the static outputs and stop before the following POST. If the user explicitly approves, verify candidates.png is at most 256 pixels on either axis and that width times height times 8 does not exceed 524288; stop before spending if either check fails. Before continuing, resolve the following first_frame path to {\"type\": \"base64\", \"base64\": \"<base64 PNG bytes from candidates.png>\", \"format\": \"png\"} in memory.",
      "inputs": [
        "candidates.png"
      ],
      "verify": "The workflow stops before the animation POST when approval is declined. When approved, candidates.png satisfies the V3 size and pixel-budget limits."
    }
  },
  {
    "POST /v2/animate-with-text-v3": {
      "first_frame": "candidates.png",
      "action": "all aura effects flicker and pulse simultaneously in place with subtle brightness variation",
      "frame_count": 8,
      "no_background": true,
      "enhance_prompt": false
    }
  },
  {
    "TASK": {
      "instruction": "Persist the background_job_id returned by the immediately preceding PixelLab call, then poll GET /v2/background-jobs/{background_job_id} gently with backoff. Treat top-level completed or last_response completed/done as success, failed as terminal failure, and never infer completion from the first returned image alone. Re-poll the same job after transient errors and never resubmit the paid animation. After a reasonable bounded wait, if the job remains pending, stop and report the saved ID and GET /v2/background-jobs/{background_job_id} as the resume route. On failure, stop and report it. On completion, save all nine returned images in API order as frame-00.png through frame-08.png. Assemble them without resizing or repainting into animation-frames.png as a three-column by three-row sheet and into animation.gif at 100 milliseconds per frame, looping forever with disposal Previous. Inspect GIF metadata, coalesce it, and compare the coalesced frames to the ordered PNGs.",
      "outputs": [
        "frame-00.png",
        "frame-01.png",
        "frame-02.png",
        "frame-03.png",
        "frame-04.png",
        "frame-05.png",
        "frame-06.png",
        "frame-07.png",
        "frame-08.png",
        "animation-frames.png",
        "animation.gif"
      ],
      "verify": "There are nine ordered transparent frames at the same dimensions as candidates.png; animation-frames.png contains the nine frames in row-major order; and animation.gif has 100-millisecond frames, loops forever, uses a defined disposal method, and coalesces to the ordered source frames. Inspect all generated frames and confirm every source cell remains recognizable and in its original grid position, synchronized visible motion occurs across the sheet, and no cells merge, cross boundaries, detach artifacts, clip, or drift unacceptably in palette. Report technical success separately from visual acceptability."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/background-aura",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Provisional transparent background-aura candidates; the prompt can also produce symbols and bottom-edge clipping.",
    "TASK": {
      "instruction": "Resolve variables. Treat the supplied aura theme, including comma-separated text, as one value and one generation call. Apply one requested size to both dimensions or split WIDTHxHEIGHT. Require explicit run approval and an authenticated PixelLab MCP connection, then create the declared unique empty output directory.",
      "verify": "The request is approved, MCP is authenticated, and the output directory is new and empty."
    }
  },
  {
    "MCP create_image_pro": {
      "description": "fully contained broad {{aura theme | default: energy}} aura forming an upright rear layer",
      "width": "{{aura width | default: 64}}",
      "height": "{{aura height | default: 64}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the returned job_id until completed or failed; never resubmit. Save every returned image unchanged and in order as candidate-1.png through candidate-N.png. Assemble all candidates once in a compact row-major candidates.png without resizing, repainting, margins, or spacing, then present every numbered candidate.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "Count, dimensions, transparency, order, and sheet cells match the returned images exactly."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/ground-aura",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Transparent ground-aura candidates beneath empty player space.",
    "TASK": {
      "instruction": "Resolve variables. Treat the supplied aura theme, including comma-separated text, as one value and one generation call. Apply one requested size to both dimensions or split WIDTHxHEIGHT. Require explicit run approval and an authenticated PixelLab MCP connection, then create the declared unique empty output directory.",
      "verify": "The request is approved, MCP is authenticated, and the output directory is new and empty."
    }
  },
  {
    "MCP create_image_pro": {
      "description": "fully contained round {{aura theme | default: energy}} ground aura beneath open vertical space",
      "width": "{{aura width | default: 64}}",
      "height": "{{aura height | default: 64}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the returned job_id until completed or failed; never resubmit. Save every returned image unchanged and in order as candidate-1.png through candidate-N.png. Assemble all candidates once in a compact row-major candidates.png without resizing, repainting, margins, or spacing, then present every numbered candidate.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "Count, dimensions, transparency, order, and sheet cells match the returned images exactly."
    }
  }
]

[
  {
    "_pixellab": {
      "auth": {
        "type": "bearer",
        "env": "PIXELLAB_SECRET",
        "required_before_calls": true
      },
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/knight",
      "output_collision_policy": "create_unique",
      "mcp_server": {
        "name": "PixelLab",
        "url": "https://api.pixellab.ai/mcp",
        "transport": "http",
        "docs_url": "https://api.pixellab.ai/mcp/docs"
      }
    },
    "_comment": "A configurable knight character sprite.",
    "_comment_prompt": "/pixellab-pip create the knight blueprint",
    "TASK": {
      "instruction": "Before any PixelLab call, require an explicit current-user request to run this blueprint, confirm PIXELLAB_SECRET is available without printing or storing its value, and resolve output_directory by using the declared path when available or appending the lowest available suffix starting at -2. Create that directory empty; if any precondition fails, stop before spending.",
      "verify": "Run authority and credential presence are confirmed, and the output directory is new, empty, writable, and inside the current project."
    }
  },
  {
    "MCP create_character": {
      "body_type": "humanoid",
      "detail": "medium detail",
      "description": "a knight in {{armor color | default: shining silver}} armor holding a {{weapon in the knight's left hand | default: sword}} and {{item held in the knight's right hand | default: shield}}",
      "mode": "v3",
      "name": "Knight",
      "size": 48,
      "view": "low top-down"
    }
  },
  {
    "TASK": {
      "instruction": "Use the fresh character ID returned by the immediately preceding MCP call with PixelLab get_character. Poll every 10 seconds for at most 10 minutes; on timeout or failed status, stop and report without resubmitting the paid creation. The recorded v3 route contract returns eight rotations. Stage image payloads or PixelLab URLs from the completed response in a partial subfolder, map returned labels case-insensitively to the hyphenated filenames in outputs (for example south_west or southwest to south-west), or use outputs-array order when labels are absent. Publish the eight declared files only after every staged rotation passes verification; on mismatch, keep them labeled as partial failure evidence and report without inventing or repainting missing directions. Do not follow a download origin outside the completed PixelLab response.",
      "outputs": ["south.png", "south-west.png", "west.png", "north-west.png", "north.png", "north-east.png", "east.png", "south-east.png"],
      "verify": "All eight declared direction filenames are present exactly once; every PNG is readable and transparent, and all have identical runtime dimensions. The request size describes subject scale rather than guaranteed canvas padding, so compatibility is checked across current returned frames instead of requiring a historical pixel dimension."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/overlay-aura",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Transparent front- or background-layer power-up aura candidates around open player space.",
    "TASK": {
      "instruction": "Resolve variables. Treat the supplied aura theme, including comma-separated text, as one value and one generation call. Apply one requested size to both dimensions or split WIDTHxHEIGHT. Require explicit run approval and an authenticated PixelLab MCP connection, then create the declared unique empty output directory.",
      "verify": "The request is approved, MCP is authenticated, and the output directory is new and empty."
    }
  },
  {
    "MCP create_image_pro": {
      "description": "fully contained {{aura theme | default: energy}} power-up aura rising along both sides of open central space",
      "width": "{{aura width | default: 64}}",
      "height": "{{aura height | default: 64}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the returned job_id until completed or failed; never resubmit. Save every returned image unchanged and in order as candidate-1.png through candidate-N.png. Assemble all candidates once in a compact row-major candidates.png without resizing, repainting, margins, or spacing, then present every numbered candidate.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "Count, dimensions, transparency, order, and sheet cells match the returned images exactly."
    }
  }
]

[
  {
    "_pixellab": {
      "api_base_url": "https://api.pixellab.ai",
      "auth": {
        "type": "bearer",
        "env": "PIXELLAB_SECRET",
        "required_before_calls": true
      },
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/paired-sprites",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Generate two configurable transparent sprites and assemble a native-size comparison.",
    "_comment_prompt": "/pixellab-pip create the paired sprites blueprint",
    "TASK": {
      "instruction": "Before any PixelLab call, require an explicit current-user request to run this blueprint, confirm PIXELLAB_SECRET is available without printing or storing its value, and resolve output_directory by using the declared path when available or appending the lowest available suffix starting at -2. Create that directory empty; if any precondition fails, stop before spending.",
      "verify": "Run authority and credential presence are confirmed, and the output directory is new, empty, writable, and inside the current project."
    }
  },
  {
    "POST /v2/create-image-pixen": {
      "description": "{{left sprite description}}",
      "image_size": "{{canvas size | default: {\"width\": 64, \"height\": 64}}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Save the image returned by the immediately preceding PixelLab call unchanged as left-sprite.png.",
      "outputs": [
        "left-sprite.png"
      ],
      "verify": "left-sprite.png decodes successfully and is byte-for-byte identical to the returned PNG."
    }
  },
  {
    "POST /v2/create-image-pixen": {
      "description": "{{right sprite description}}",
      "image_size": "{{ canvas   size | default: {\"width\": 64, \"height\": 64}}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Save the image returned by the immediately preceding PixelLab call unchanged as right-sprite.png, then place left-sprite.png and right-sprite.png side by side in that order without resizing or repainting either source.",
      "inputs": [
        "left-sprite.png"
      ],
      "outputs": [
        "right-sprite.png",
        "paired-sprites.png"
      ],
      "verify": "Both source PNGs decode at the requested canvas size; paired-sprites.png is exactly two cells wide, preserves transparency, and each cell matches its source pixel-for-pixel."
    }
  }
]

[
  {
    "_pixellab": {
      "api_base_url": "https://api.pixellab.ai",
      "auth": {
        "type": "bearer",
        "env": "PIXELLAB_SECRET",
        "required_before_calls": true
      },
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/portable-sprite",
      "output_collision_policy": "create_unique"
    },
    "_comment": "A portable REST recipe for a configurable transparent sprite.",
    "_comment_prompt": "/pixellab-pip create the portable sprite blueprint",
    "TASK": {
      "instruction": "Before any PixelLab call, require an explicit current-user request to run this blueprint, confirm PIXELLAB_SECRET is available without printing or storing its value, and resolve output_directory by using the declared path when available or appending the lowest available suffix starting at -2. Create that directory empty; if any precondition fails, stop before spending.",
      "verify": "Run authority and credential presence are confirmed, and the output directory is new, empty, writable, and inside the current project."
    }
  },
  {
    "POST /v2/create-image-pixen": {
      "description": "{{sprite description}}",
      "image_size": "{{canvas size | default: {\"width\": 64, \"height\": 64}}}",
      "no_background": "{{transparent background | default: true}}",
      "seed": "{{seed | default: null}}"
    }
  },
  {
    "TASK": {
      "instruction": "Save the image returned by the immediately preceding PixelLab call unchanged as sprite.png.",
      "outputs": ["sprite.png"],
      "verify": "sprite.png is readable, its dimensions equal the resolved image_size sent above, its alpha matches the resolved no_background request, and its bytes match the returned image payload."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/portrait-head-shoulders-mvp",
      "output_collision_policy": "create_unique",
      "mcp_server": {
        "name": "PixelLab",
        "url": "https://api.pixellab.ai/mcp",
        "transport": "http",
        "docs_url": "https://api.pixellab.ai/mcp/docs"
      }
    },
    "_comment": "Configurable Pixen recipe for a consistent head-and-shoulders portrait; defaults to south-east and 128x128.",
    "_comment_prompt": "Create a reusable configurable Pixen head-and-shoulders portrait blueprint.",
    "TASK": {
      "instruction": "Before the paid call, require an explicit current-user request to run this blueprint, confirm the callable PixelLab MCP create_image_pixen and get_image tools are available, and resolve output_directory by using the declared path when empty or appending the lowest available suffix starting at -2 when it is not empty. Create the resolved directory empty and stop before spending if any precondition fails.",
      "verify": "The user authorized this paid run, the two required MCP tools are callable, and the resolved output directory is new, empty, writable, and project-relative."
    }
  },
  {
    "MCP create_image_pixen": {
      "description": "Classic head-and-shoulders pixel art portrait of {{subject | default: a young adult human RPG adventurer with short brown hair and a plain high-collar tunic visible only at the neck and shoulders}}; directly facing {{portrait direction | default: south-east}}, face square to the selected direction, both eyes visible; top of head to upper chest, both shoulders fully visible; medium, consistent portrait scale, head about half the canvas height, clear margin above the head, no head-only close-up, no waist-up or full body. Flat, solid-color dark muted background with no gradient.",
      "width": "{{portrait width | default: 128}}",
      "height": "{{portrait height | default: 128}}",
      "direction": "{{portrait direction | default: south-east}}",
      "no_background": false
    }
  },
  {
    "TASK": {
      "instruction": "Poll get_image with the fresh job ID returned by the immediately preceding MCP call until a completed image result is present; do not resubmit automatically. Save the returned PNG unchanged as portrait.png.",
      "outputs": ["portrait.png"],
      "verify": "portrait.png is a readable PNG whose dimensions match the resolved portrait width and height and whose pixels match the returned PixelLab image; visual review confirms the face is directly oriented in the resolved direction, straight-on when the resolved direction is south, with both eyes visible, both shoulders and upper chest visible, clear space above the head, and no head-only, waist-up, or full-body crop."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/rpg-maker-character",
      "output_collision_policy": "create_unique",
      "mcp_server": {
        "name": "PixelLab",
        "url": "https://api.pixellab.ai/mcp",
        "transport": "http",
        "docs_url": "https://api.pixellab.ai/mcp/docs"
      }
    },
    "_comment": "Generate, review, animate, and package a configurable four-direction character for RPG Maker XP, VX, VX Ace, MV, or MZ. The RPG Maker version is required.",
    "_comment_prompt": "Create an RPG Maker character spritesheet; ask which supported RPG Maker version to target only when the request does not already name one, and default the character to a bald unisex chibi base character with a plain skin-tone body.",
    "TASK": {
      "instruction": "Follow this JSON array in order; no external instructions are required. Resolve every `{{...}}` placeholder before a call. Use a declared default silently when the user supplied no value, but never default RPG Maker version: if it was not supplied or confidently inferred from the current request and relevant conversation context, ask the user once to choose XP, VX, VX Ace, MV, or MZ. Resolve that version case-insensitively, strip an optional `RPG Maker` prefix, normalize VXAce to VX Ace, and accept only those five values. When the user supplies character wording, resolve `character` by removing only request framing and the version phrase; preserve the remaining words without enhancement, embellishment, or added style, age, anatomy, clothing, or equipment. Treat a bare generic request for the default, normal, or base character as no custom character wording and use the declared default. A `map` modifier means: resolve the named variable first, replace the whole placeholder with the mapped JSON value, and stop if no key matches. Thus the map on create_character.size is also the version enum; never ask for a technical size. Derive export cells separately, and never reuse the mapped size as a cell dimension: XP=32x48, VX/VX Ace=32x32, MV/MZ=48x48. The mapped size is a PixelLab request parameter only; for XP the two happen to share the number 48 without meaning the same thing. Never put the version in the PixelLab description. Require an explicit current-user request to run this paid recipe and callable PixelLab MCP create_character, get_character, and animate_character tools. When no user is reachable, an explicit pre-authorisation from the caller stands in for that request; without one, stop before the first paid call. If MCP is unavailable or unconfigured, stop and show https://www.pixellab.ai/mcp; do not substitute REST. Create the declared output directory empty, reuse it when it already exists and is empty, or append the lowest free suffix beginning at -2 when it holds anything; never overwrite a run. Every input and output path declared by a later step is relative to this resolved run directory. Before spending, show the resolved create_character body and the planned animate_character arguments. character_id does not exist yet, so show it as a placeholder and state that it will be the fresh ID of the ultimately approved candidate. Disclose approximately 6 generations total for every supported version (about 2 for the v3 character plus 4 directional animation jobs), and wait for explicit approval. This approval covers one animation of the ultimately approved candidate. Every regeneration needs separate approval for one additional v3 character generation at approximately 2 generations; never retry a paid call automatically.",
      "verify": "Both user-facing variables and the inline size map resolve; the version came from the current user or relevant context rather than a default; the version is supported; the MCP tools are callable; the output directory is new and empty; and the user approved the resolved paid chain."
    }
  },
  {
    "MCP create_character": {
      "body_type": "humanoid",
      "description": "{{character | default: bald unisex chibi base character, plain skin-tone body}}",
      "detail": "high detail",
      "mode": "v3",
      "size": "{{RPG Maker version | map: {\"XP\": 48, \"VX\": 32, \"VX Ace\": 32, \"MV\": 48, \"MZ\": 48}}}",
      "view": "low top-down"
    }
  },
  {
    "TASK": {
      "instruction": "Poll get_character with the fresh ID returned by create_character no more than once every 10 seconds; never resubmit automatically. Terminal means the response reports a completed or failed state AND reports no work still in progress; some responses name a pending-jobs section explicitly and others just omit finished work, so treat any job shown with a percentage or an in-progress status as nonterminal: get_character can report status completed while a rotation job is still running, and rotation URLs read before that job clears may be provisional. Keep the run going between polls rather than pausing to report intermediate progress: a run abandoned mid-generation leaves a paid character unfinished. If fifteen minutes pass with no change in the reported status, stop and report the character ID and last status. v3 returns eight rotations; map only from explicit direction labels after trimming and case-insensitive comparison, never from array or response order. Require exactly one south, west, east, and north rotation, ignore the four additional explicitly labeled diagonals for this four-direction recipe, and stop on any missing, duplicate, or ambiguous required cardinal label. Save each cardinal rotation unchanged at the path below and build the contact sheet only as a review aid: lay the four cardinal rotations side by side in south, west, east, north order and draw each direction's name directly above or below its pose so the labelling can be checked. The contact sheet may be scaled or padded for legibility; the saved rotations never are. Inspect the contact sheet against the resolved character description and report every visible mismatch; never call a mismatched candidate compliant. Do not animate yet. A regeneration uses the next unused candidate directory (02, 03, and so on) and never overwrites a prior candidate.",
      "outputs": [
        "candidates/01/rotations/south.png",
        "candidates/01/rotations/west.png",
        "candidates/01/rotations/east.png",
        "candidates/01/rotations/north.png",
        "candidates/01/contact-sheet.png"
      ],
      "verify": "The saved south, west, east, and north rotations are readable transparent PNGs with identical canvas dimensions, retain their returned pixels, appear correctly labeled in the contact sheet, and were visually assessed against the resolved character description."
    }
  },
  {
    "TASK": {
      "instruction": "Display the contact sheet from its full absolute path, print `Preview file: <full absolute path>` directly above it, and say `If the image is not visible here, open that file directly.` Then render this Markdown checkpoint exactly: `🎭 **Character ready — choose the next step**\n\n1. **Continue animating** — create the engine-appropriate walk frames for all four directions.\n2. **Regenerate character** — describe what to change; this adds another paid character generation and will be cost-gated.\n3. **Stop here** — keep the four directional base sprites without creating an animated engine sheet.\n\nReply **1 / 2 / 3**, or describe the changes you want.` Wait. When no user is reachable, follow a caller's explicit pre-authorisation if one was given, and otherwise stop here rather than choosing for them. Continue uses the already-approved animation call without another approval. Regenerate collects changes, shows and waits for approval of one additional create_character call (about 2 generations), and changes only the description. After approval, call create_character once, then repeat the complete preceding polling/review procedure with the fresh ID: apply the same timeout and explicit direction-label mapping, save unchanged cardinal rotations and a newly inspected contact sheet under the next unused candidate directory (02, 03, and so on), never overwrite a prior candidate, show and print its full absolute path with the same preview fallback, and repeat this checkpoint. Stop makes no animation call and reports that the saved rotations are not an engine-ready animated sheet. Any other paid-plan change requires fresh approval.",
      "verify": "Animation starts only after Continue; each regeneration is separately approved and uses a fresh ID; Stop makes no later paid call."
    }
  },
  {
    "TASK": {
      "instruction": "Only after Continue, copy the reviewed rotations unchanged to approved/rotations. Call animate_character once on that fresh character ID with mode=template, template_animation_id=walking-4-frames, animation_name=four-direction walk, directions=[south, west, east, north], and ai_freedom=0. Poll get_character no more than once every 10 seconds until all four direction jobs reach a terminal state, using the same terminal rule as the rotation step: a completed or failed state with no pending jobs listed; never retry automatically. If fifteen minutes pass with no change in the reported status, stop and report the character ID, animation group or job IDs, and last statuses. Map jobs and frames only from explicit direction labels after trimming and case-insensitive comparison; never infer direction from response order. Require exactly one south, west, east, and north result and stop on any missing, duplicate, or ambiguous required label. Save each direction's four returned frames unchanged and in returned order as 01.png through 04.png; PixelLab names them 0-indexed, so returned frame 0 becomes 01.png and returned frame 3 becomes 04.png. Getting this offset wrong silently changes which frames the three-column profiles discard. Before packaging, inspect every animation frame against the approved rotations and resolved character description. Judge only the features named in the resolved character description. Stop and report the mismatch, and never repair or silently package a failed animation, when a described feature is dropped, swapped, or materially recoloured between any two of the poses this profile will deliver, counting the approved rotation as one of them, or between two directions that both show it. A hood up in the rotation and down in 02.png and 04.png is the shape of failure this catches: in playback the feature flickers instead of moving. Posture is not that: the rotation and the animation come from separate generations and a template walk reposes the body, so stance, limb and tail position and shading routinely differ, as does normal directional occlusion. Features the model added that the description never requested are reported, not stopped on.",
      "outputs": [
        "approved/rotations/south.png",
        "approved/rotations/west.png",
        "approved/rotations/east.png",
        "approved/rotations/north.png",
        "approved/walk/south/01.png",
        "approved/walk/south/02.png",
        "approved/walk/south/03.png",
        "approved/walk/south/04.png",
        "approved/walk/west/01.png",
        "approved/walk/west/02.png",
        "approved/walk/west/03.png",
        "approved/walk/west/04.png",
        "approved/walk/east/01.png",
        "approved/walk/east/02.png",
        "approved/walk/east/03.png",
        "approved/walk/east/04.png",
        "approved/walk/north/01.png",
        "approved/walk/north/02.png",
        "approved/walk/north/03.png",
        "approved/walk/north/04.png"
      ],
      "verify": "South, west, east, and north each have exactly four readable transparent frames saved unchanged in returned order, and every frame preserves the approved character's identity and defining features beyond normal directional occlusion."
    }
  },
  {
    "TASK": {
      "instruction": "After successful animation, create the three outputs declared by this step directly in the resolved run directory, never in a subdirectory, and package the approved pixels for {{RPG Maker version}} without repainting. Rows are fixed: south=1 Down, west=2 Left, east=3 Right, north=4 Up. First select only the poses the profile will deliver. XP uses all four returned walk frames in columns 1,2,3,4, matching playback 1→2→3→4, and never uses the static rotation; visually inspect every row's 1→2→3→4→1 gait and stop on a teleport, reversal, bad 4→1 seam, or a stalled gait where consecutive frames are identical. Columns 1 and 3 both sit on the template's neutral legs-together phase and so legitimately resemble each other; that resemblance is expected and is not the duplicate this check looks for. Output rpg-maker-character.png with 32x48 cells at 4x4 (128x192). VX/VX Ace/MV/MZ use the reviewed static rotation in column 2, saved walk frame 02.png in column 1, and saved walk frame 04.png in column 3, matching playback 2→1→2→3. walking-4-frames places neutral legs-together poses at 01 and 03 and the two opposing stride extremes at 02 and 04, so 01 and 03 are always the discarded pair; never reorder or substitute this selection to chase a better-looking frame. Before packaging, and only for these three-column profiles, sanity-check this mapping on the approved west and east walk frames themselves, not on the sheet, which does not exist yet, and judge it only there: front and back views regularly measure as reversed and must never be used for this check. Where the legs are visible, 02 and 04 each show a stride with opposite legs leading while 01 and 03 show feet together. When the frames cannot settle it for any reason, such as clothing covering the legs, a body plan with no legs, or too few pixels to read, record the check as inconclusive and proceed with the pinned mapping rather than guessing. Only a clear reversal in both the west and east frames is a stop condition: report that the template's frame phases may have moved to 01/03, and never silently swap in another pair. Then, for these three-column profiles only, confirm the delivered cycle reads as motion: columns 1 and 3 must differ from each other and from the standing pose in leg or arm position, and if all three are effectively the same pose, stop and report a stalled walk. XP has no standing column and uses its own 1-2-3-4 gait check instead. Output $rpg-maker-character.png at 3x4: VX/VX Ace use 32x32 cells (96x128), and MV/MZ use 48x48 cells (144x192). Then normalize only those delivered poses: find each pose's alpha>0 bounds, reject empty poses, and remove only fully transparent margins. Let maxW be the greatest cropped pose width and maxH the greatest cropped pose height across every delivered pose; apply one nearest-neighbor scale min(1, CW/maxW, CH/maxH) to every delivered pose. Set each scaled dimension to max(1, floor(original dimension times scale)); never round up. Bottom-center each scaled pose in an exact CWxCH cell at x=floor((CW-scaled width)/2), y=CH-scaled height, so an odd horizontal remainder leaves the extra transparent pixel on the right. PixelLab's requested size and returned canvas dimensions are not export dimensions. Never trim an alpha>0 pixel out of a pose, never upscale, and never give a pose its own scale factor: one scale applies to every delivered pose. Nearest-neighbour downscaling necessarily merges source pixels, which is expected and is not trimming. Create looping rpg-maker-character-engine-playback.gif directly from unscaled full-height sheet columns: every GIF frame is exactly CW pixels wide by the sheet height and contains all four direction cells stacked Down/Left/Right/Up. XP uses sheet columns 1→2→3→4; VX/VX Ace/MV/MZ use columns 2→1→2→3. Use 25 centiseconds per frame, which most encoders express as 250 milliseconds, so one full cycle reads at about one second, infinite looping, and disposal method 2, restore to background. Read delay, loop count and disposal back from the GIF's graphic control extension bytes; common decoders do not expose disposal on read-back. Before encoding, check whether the source columns are exactly GIF-representable, meaning every alpha value is 0 or 255 and the opaque colours number 255 or fewer. When they are, require every coalesced GIF frame to compare pixel-for-pixel with its source sheet column, comparing alpha-aware: a fully transparent source pixel matches any fully transparent GIF pixel whatever its palette RGB, and every opaque pixel must match exactly. Build one shared global palette across all frames; per-frame adaptive quantisation fails this comparison even when the source is representable. When they are not, create the closest visually faithful palette preview, report that GIF cannot preserve the source RGBA exactly, and never present the GIF as pixel-exact; the PNG sheet remains authoritative. Create rpg-maker-character-inspection-grid.png as an unscaled copy of the final sheet with identical pixel dimensions, adding only one-pixel magenta (255,0,255) grid lines on the first pixel row or column of each interior cell boundary; boundary pixels may change color and alpha as needed for visibility, but the final sheet remains untouched. Never add a title canvas, margins, or scaling. Label it `Inspection aid — expected grid overlay` only when shown or reported; the grid never alters the sheet.",
      "inputs": [
        "approved/rotations/south.png",
        "approved/rotations/west.png",
        "approved/rotations/east.png",
        "approved/rotations/north.png",
        "approved/walk/south/01.png",
        "approved/walk/south/02.png",
        "approved/walk/south/03.png",
        "approved/walk/south/04.png",
        "approved/walk/west/01.png",
        "approved/walk/west/02.png",
        "approved/walk/west/03.png",
        "approved/walk/west/04.png",
        "approved/walk/east/01.png",
        "approved/walk/east/02.png",
        "approved/walk/east/03.png",
        "approved/walk/east/04.png",
        "approved/walk/north/01.png",
        "approved/walk/north/02.png",
        "approved/walk/north/03.png",
        "approved/walk/north/04.png"
      ],
      "outputs": [
        "{{RPG Maker version | map: {\"XP\": \"rpg-maker-character.png\", \"VX\": \"$rpg-maker-character.png\", \"VX Ace\": \"$rpg-maker-character.png\", \"MV\": \"$rpg-maker-character.png\", \"MZ\": \"$rpg-maker-character.png\"}}}",
        "rpg-maker-character-engine-playback.gif",
        "rpg-maker-character-inspection-grid.png"
      ],
      "verify": "All declared outputs exist directly in the resolved run directory. The sheet, looping playback GIF, and separate grid decode. Every GIF frame is one unscaled full-height sheet column with width CW and the sheet height, delay 25 centiseconds, infinite looping, and disposal method 2. When the source columns are GIF-representable, every coalesced frame compares pixel-for-pixel to its required source column; otherwise the report identifies the palette/alpha limitation and treats only the PNG sheet as authoritative. The grid has exactly the sheet's pixel dimensions and differs only at its one-pixel interior cell-boundary overlay, with no title canvas, margins, or scaling; the final sheet is unchanged. XP is 128x192 with 32x48 cells, no `$`, and visually clean 1→2→3→4→1 playback including the 4→1 seam. VX/VX Ace is 96x128 with 32x32 cells; MV/MZ is 144x192 with 48x48 cells; VX through MZ use `$`, Down/Left/Right/Up rows, and movement/standing/movement columns holding saved walk frame 02.png, the static rotation, and saved walk frame 04.png, with 01 and 03 discarded. Every delivered pose preserves the approved character's identity and defining features beyond normal directional occlusion. Only delivered poses affect scaling; scaled dimensions and bottom-center placement use the declared floor rules; every alpha>0 pixel stays in its cell; transparency is preserved; and artifact inspection finds no scale, center, baseline, seam, or standing-pose jitter."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/status-effect",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Transparent wordless status, battle, and level-up effect candidates with a round ground component.",
    "TASK": {
      "instruction": "Resolve variables. Treat the supplied effect theme, including comma-separated text, as one value and one generation call. Apply one requested size to both dimensions or split WIDTHxHEIGHT. Require explicit run approval and an authenticated PixelLab MCP connection, then create the declared unique empty output directory.",
      "verify": "The request is approved, MCP is authenticated, and the output directory is new and empty."
    }
  },
  {
    "MCP create_image_pro": {
      "description": "fully contained symmetrical wordless {{effect theme | default: energy}} status effect above a round ground aura",
      "width": "{{effect width | default: 64}}",
      "height": "{{effect height | default: 64}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the returned job_id until completed or failed; never resubmit. Save every returned image unchanged and in order as candidate-1.png through candidate-N.png. Assemble all candidates once in a compact row-major candidates.png without resizing, repainting, margins, or spacing, then present every numbered candidate.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "Count, dimensions, transparency, order, and sheet cells match the returned images exactly."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/turntable-rotate-16",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Seamless 16-frame turntable from one supplied frame: the same image is sent as both anchors, and the prompt frames the subject as a rigid object so the model orbits it instead of animating it. The object word is load-bearing for the turn itself, not only for stillness; figurine is the tested winner, and toy figure or display model score the same if either reads better for the subject. Keep the subject description minimal and name only identity-bearing props (e.g. a held shield); decorative nouns get reinterpreted as new geometry on the unseen back. Loop closure is about 75% per draw even on the best prompt, so expect to run this 2-3 times and keep the draw that closes; each run spends credits and needs its own approval. A feathered or fringed subject may show inherent particle/feather artifacts during the turn regardless of prompt or no_background; erase in post or add a negative description.",
    "_comment_prompt": "/pixellab-pip create the turntable-rotate-16 blueprint",
    "TASK": {
      "instruction": "Before any PixelLab call, require an explicit current-user request to run this blueprint, confirm an authenticated PixelLab MCP connection, confirm the supplied image resolves to one readable frame whose width times height does not exceed 32768 pixels (so width times height times 16 stays within the 524288 budget; 128x128 is the tested size, ~181x181 the square maximum) and stop and report rather than shrinking it, and resolve output_directory by using the declared path when available or appending the lowest available suffix starting at -2. Create that directory empty; if any precondition fails, stop before spending.",
      "verify": "Run authority and an authenticated MCP connection are confirmed, the supplied image is a single readable frame within the 16-frame pixel budget (width times height at most 32768), and the output directory is new, empty, writable, and inside the current project."
    }
  },
  {
    "MCP animate_image": {
      "first_frame_base64": "{{attached or linked image}}",
      "last_frame_base64": "{{attached or linked image}}",
      "action": "Turntable: rotate the view around a solid {{object | default: figurine}} depicting {{subject description}} - front, three-quarter, side, back, full back, opposite side, back to the front. The {{object | default: figurine}} itself never moves; only the viewing angle changes.",
      "frame_count": 16,
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the job_id returned by the immediately preceding call until it reports completed or failed; re-poll after transient errors and never resubmit the paid job; after a reasonable bounded wait, stop and report the saved job_id as the resume route. On completion, save every returned image unchanged and in order as frame-00.png onward. The first returned image is the supplied frame echoed back, so drop that echoed first image from the GIF only; keep every saved PNG. Assemble the remaining frames into turntable-rotate-16.gif as an infinitely looping animation at an even frame delay. Preserve transparency: set an explicit GIF disposal that restores the canvas between frames (dispose to background) so transparent pixels do not accumulate trails, and reserve a dedicated palette slot for fully transparent pixels only - never use palette index 0 for transparency, because a real color sits there and every pixel using it is punched into a hole. Then present turntable-rotate-16.gif and report whether its final frame returns to the supplied front view; if the loop does not close, say so and ask before running again, since each run is a separate paid job.",
      "outputs": ["turntable-rotate-16.gif"],
      "verify": "The saved PNG count matches the returned image count, each PNG matches its returned frame pixel-for-pixel, turntable-rotate-16.gif has one fewer frame than the PNGs, loops forever, and renders every frame with the subject intact, no punched-out holes, no trails, and no baked-in background."
    }
  }
]

[
  {
    "_pixellab": {
      "paid_call_policy": "explicit_user_run_request_required",
      "output_directory": "pixellab-pip-generations/wall-aura",
      "output_collision_policy": "create_unique"
    },
    "_comment": "Transparent combined ground-and-wall aura candidates that rise behind a future character.",
    "TASK": {
      "instruction": "Resolve variables. Treat the supplied aura theme, including comma-separated text, as one value and one generation call. Apply one requested size to both dimensions or split WIDTHxHEIGHT. Require explicit run approval and an authenticated PixelLab MCP connection, then create the declared unique empty output directory.",
      "verify": "The request is approved, MCP is authenticated, and the output directory is new and empty."
    }
  },
  {
    "MCP create_image_pro": {
      "description": "fully contained broad {{aura theme | default: energy}} aura rising along the rear edge of a round ground aura",
      "width": "{{aura width | default: 64}}",
      "height": "{{aura height | default: 64}}",
      "no_background": true
    }
  },
  {
    "TASK": {
      "instruction": "Poll MCP get_image with the returned job_id until completed or failed; never resubmit. Save every returned image unchanged and in order as candidate-1.png through candidate-N.png. Assemble all candidates once in a compact row-major candidates.png without resizing, repainting, margins, or spacing, then present every numbered candidate.",
      "outputs": [
        "candidates.png"
      ],
      "verify": "Count, dimensions, transparency, order, and sheet cells match the returned images exactly."
    }
  }
]

# Animation

Read this for raw animation, managed character/object animation, interpolation, skeleton animation, outfit transfer, rotation, frame anchors, or animation preview verification.

## Route Choice

Use MCP `animate_character`/`animate_object` for managed MCP assets. For a raw supplied image with no managed asset, use MCP `animate_image_pixminimax` only when the user explicitly requests PixMiniMax/MiniMax H3; otherwise use MCP `animate_image`. On REST, use `POST /animate-pixminimax` for that explicit model request, or `POST /animate-with-text-v3`/`interpolation-v2` otherwise. The v3 idle-loop, atlas, and pixel-budget risks below were characterized against the REST v3 endpoint; PixMiniMax has separate frame, cost, and prompt rules in the next section. For exact REST schemas, skeletons, outfit transfer, raw frame editing, or rotation, use the REST v2 routes (`animate-with-skeleton`, `estimate-skeleton`, `edit-animation-v2`, `transfer-outfit-v2`, `rotate`). For 8 rotations from an image, MCP only partially covers it by regenerating rather than rotating the exact input — `create_8_direction_object(reference_image_base64=…)` for objects, `create_character(mode="v3", reference_image_base64=…)` for characters (identity transfer is unreliable on `create_8_direction_object` for humanoid subjects); use REST `generate-8-rotations-v2/v3` when the exact input pixels must be preserved.

Classify supplied frame images (first frame vs last frame vs style/edit reference vs managed asset ID) per the Goal Router in `image-input-roles.md`; ask before a credit-spending call when the role would change the endpoint, field, or output.

## PixMiniMax / MiniMax H3

PixelLab's public PixMiniMax operation is REST `POST /animate-pixminimax` and MCP `animate_image_pixminimax`. It is beta. The public wrapper accepts a motion-only `description` (limit in `prompt-limits.md`), a required `first_frame`, an optional same-size `last_frame`, `frame_count` 4–40 in multiples of four, an optional `seed`, `no_background`, `drift_threshold`, and `enhance_prompt`; the eight-way `direction` hint is valid only with enhancement. MCP exposes `enhance_prompt` and `direction` too, plus preferred URL frame inputs, but not REST's `drift_threshold`. The input canvas is capped at 256×256. It returns a background job; poll `GET /background-jobs/{job_id}` and expect `frame_count + 1` images, with the input frame intended at index 0.

Adapt MiniMax H3's official timeline-oriented prompting to PixelLab's smaller wrapper: start the motion on the first frame, name the action phases in order, describe the visible transition toward the result, and state “in place” when locomotion must not translate the subject. Preserve identity, palette, outline, scale, canvas placement, and transparency in positive wording. Keep the description concise and about motion, not appearance or audio. MiniMax's raw H3 prompt guides also cover audiovisual fields, reference labels, shots, and soundscape/music; those fields are not part of PixelLab's PixMiniMax schema and must not be copied into a PixelLab request.

Useful shape: `Start [subject] moving on the first frame. [phase 1], then [phase 2], then [result]. Keep the subject in place; preserve [identity anchors].` Use `enhance_prompt=true` when a short motion description needs model expansion and the extra ~0.05 generation is approved. Use `direction` with that enhancement when facing/attack direction matters; otherwise omit it and let the service infer from the image. For an end-state transition, supply a genuinely distinct `last_frame`; for a loop, matching anchors can over-constrain low-motion clips, so inspect the middle frames and endpoint rather than assuming the loop is clean.

## Idle Loop Risk

Do not assume `animate-with-text-v3` or PixMiniMax with an identical or near-identical `last_frame` is safe for tiny or low-motion idle loops. The endpoint frames can still match while middle frames add detached puffs, arcs, symbols, trails, or other external marks; verify the returned middle frames for each route.

Use `last_frame` when the user needs interpolation between distinct poses, the action has clear internal body motion, or external motion marks are acceptable and will be inspected.

For a strict tween between two distinct frames, use the selected raw-animation route with matching first/last-frame URL or base64 inputs: MCP `animate_image_pixminimax` for an explicit PixMiniMax request, otherwise `animate_image`; or REST `animate-pixminimax`/`animate-with-text-v3` with the matching `description`/`action` field. Use `interpolation-v2` (Pro; 128×128 cap; no frame-count control) only if the user explicitly asks for it — `animate_image` partially covers it at v3 tier.

For REST v3 color flicker, `drift_threshold` controls how often de-flicker correction runs: `0` corrects every frame; higher values correct only larger color drift. Omit it unless color drift is a stated or observed problem. REST `generate-8-rotations-v3.description` is an optional extra hint when the supplied frame alone does not convey the intended subject or styling.

Treat `last_frame` as high-risk when:

- The first and last frames are identical or nearly identical.
- The prompt is idle, stand, breathing, subtle bob, weight shift, neutral stance, or another low-motion loop.
- The user requires no effects, particles, marks, symbols, trails, or artifacts.

For clean idle loops, prefer one candidate first — first-frame-only generation with careful prompt wording — unless the user provides or asks for a last-frame anchor. If they supply a near-identical `last_frame`, explain the artifact risk and ask whether to use it or try first-frame-only. Do not spend retries on only frame-count or tiny last-frame changes unless the user asks for that experiment.

Exception: a 360° rotation turntable sends the one frame as both `first_frame` and `last_frame` with a rigid-object trajectory `action`, so the identical anchor closes the loop instead of freezing.

Managed character animation accepts v3-only frame anchors on both surfaces: MCP `animate_character` `custom_start_frame_base64`/`custom_start_frame_url` + `end_frame_base64`/`end_frame_url` (prefer the `_url` forms — MCP clients truncate large inline base64), or REST `/animate-character` / `/characters/animations` `custom_start_frame`/`end_frame`. Treat them like frame anchors: they require exactly one direction, are not compatible with template or pro mode, and the end frame enables interpolation toward a target pose. Use them only when the user asks for a custom start pose, target pose, or managed-character interpolation; otherwise let the character's stored direction frame be the start.

Managed v3 character and object animation (MCP `animate_character`/`animate_object` and the REST equivalents) stores the input reference frame as frame 0 by default, so `frame_count=8` stores and reports 9 frames. Set v3-only `keep_first_frame=false` (incompatible with template and pro modes) when the user needs exactly `frame_count` generated frames; otherwise expect and report the extra frame instead of treating it as a frame-count mismatch.

When appending to an existing managed animation group, pass its existing `animation_name` as well as `group_id`; PixelLab does not inherit the name from the group.

When the user does not specify `frame_count`, use the endpoint default or documented animation/template default. For REST `animate-with-text-v3`, current OpenAPI documents `frame_count` as 4-16, must be even, default 8, plus a **total pixel budget: `width × height × frame_count ≤ 524,288`**. Size and frame count are therefore coupled — a 256×256 canvas allows only 8 frames, and 16 frames need `width × height ≤ 32,768` (a square up to ~181×181; 128×128 is a safe common choice). Exceeding the budget is rejected; refresh the schema before choosing a non-default value when exact current behavior matters. MCP `animate_image` caps the first frame at 256×256 and requires the same even `frame_count` (4-16, default 8); its live tool schema states the identical pixel budget. PixMiniMax instead accepts 4-40 generated frames in multiples of four at any input size up to 256×256; do not apply v3's total-pixel-budget rule to it without current evidence.

Raw `animate-with-text-v3` and PixMiniMax return `frame_count`+1 images: image 0 is the supplied `first_frame` intended as frame 0, followed by the `frame_count` generated frames, so `frame_count=16` yields 17 images and PixMiniMax `frame_count=40` yields 41. Count and report accordingly; do not read the extra image as a frame-count mismatch. Verify the echo at the pixel and visible-content levels: v3 may normalize RGB values in transparent pixels, and small inputs can return a materially changed first image despite the documented echo convention. For chaining, image 0 counts as the handoff duplicate when it is pixel-exact, or when its size and alpha match and the only differences are RGB values stored in fully transparent pixels. A change to size, alpha, or any visible pixel is not a duplicate. Keep the raw frame and report any mismatch instead of silently replacing it; drop image 0 from the stitched playback only after this check. The first frame that has actually moved is image 1. `first_frame` and `last_frame` are Base64Image objects (`{"type":"base64","base64":"…","format":"png"}`), not bare base64 strings.

## Async Polling

`animate-with-text-v3`, PixMiniMax, and the other generation endpoints are async: `POST` returns a `background_job_id`; poll `GET /background-jobs/{job_id}` until the job `status` is `completed` (results at `last_response.images`) or `failed`. Two robustness notes from live runs: under heavy load the top-level `status` can briefly lag the ready result, so `last_response`'s own completed/`done` status is the earliest reliable signal — but do not treat the mere first appearance of an image as done, since some endpoints stream partial progress images. Prefer per-call `usage.generations` when present; if only `usage.usd` is exposed, report that as USD and do not convert it into generations without a documented formula. Make the poll loop tolerant of transient timeouts and 5xx: re-poll the same saved `background_job_id`, and never resubmit a paid job on a transient poll error — that double-charges (see `job-lifecycle.md`). Persist each paid response as it arrives so a poller crash cannot orphan a charged job.

## Atlas Animation Risk

`animate-with-text-v3` treats a spritesheet as one image rather than isolated cells. Prompt wording cannot reliably enforce cell boundaries or preserve each cell independently; motion may deform cells or cross between them. Animate one selected cell as the default. If the user explicitly approves animating several cells independently, use one job per cell and disclose the multi-job cost first.

If the user insists on animating an atlas in one job, explain that the result is experimental. `animate-with-text-v2` / Pro may honor per-cell variation better but at lower pixel quality; offer it as an optional paid candidate, not a quality upgrade, warn about palette and color drift, and verify every cell.

## Walk Loops From Idle Stances

Seamless walk loops generated from a single idle or neutral stance frame are high-risk:

- First-frame-only attempts can produce motion but did not reliably close the loop; identical first/last idle anchors add loop pressure but become constrained or unpredictable — varying prompt length, negative prompting, or frame count did not fix it — with palette shifts near the interpolation endpoint.
- Prefer mid-walk start/end anchors over idle anchors — more reliable, but not a proven complete fix.
- Skeleton/template routes improve loopability and pose consistency but looked stiff, robotic, and prone to hard limb shadows.
- Common idle-derived failures: idle collapse, mouth/talking motion, exaggerated arms, weak foot contacts, and breathing/wind/smoke artifacts near the head (the model reads the request as idle-like motion).

If this route fails or the agent needs more detail, read `../../docs/pixellab/pixellab-idle-animation-artifact-research.md`.

## Verification

Before calling an animation final, verify:

- Frame count and frame order.
- Canvas dimensions and transparency.
- Whether `first_frame` and `last_frame` were used.
- Whether endpoint frames match when loop closure matters.
- For PixMiniMax, whether `enhanced_prompt` was returned and whether `direction` was used only with enhancement.
- Middle-frame visual quality, especially detached artifacts, palette shifts, body drift, or unexpected gestures.
- For atlas inputs, whether cells contain genuinely different animation phases rather than synchronized copies or superficial pixel noise.
- Preview GIF or spritesheet output faithfully represents the source frames.

Report whether the result technically loops and whether it is visually acceptable. These are different claims.

## Outfit And Edit Animation

`transfer-outfit-v2` and `edit-animation-v2` return composited frames, not reusable paperdoll layers. Preserve frame count, order, size, direction labels, and transparency; if source and target counts, dimensions, or direction sets differ, ask how to align them before spending credits.

For paperdoll or layer requests, read `paperdolling.md` before using animation edit or outfit transfer.

# Aseprite CLI Integration

Read this only when the user explicitly asks for Aseprite handling: opening output in Aseprite, creating/updating an `.aseprite` file, importing PixelLab frames as layers/frames/tags, palette/indexed conversion, or exporting via the Aseprite CLI/Lua. Most local preview work belongs in `local-asset-assembly.md` instead.

This is a low-risk pipeline:

```text
PixelLab MCP or documented REST v2
  -> verified local image/frame files
  -> Aseprite CLI or Aseprite Lua script
  -> `.aseprite`, PNG sequence, GIF, spritesheet, metadata, or visible Aseprite workspace
```

Aseprite is a local workspace/import/export tool applied after PixelLab generated the pixels. It arranges PixelLab/user images into layers, frames, tags, cels, and exports; it never authors content (per SKILL.md Asset Integrity — no Lua draw/brush/shape/scripted pixel placement unless the user approves a labeled non-PixelLab fallback).

For explicit Aseprite MCP requests, read `aseprite-mcp.md`; return here when the task also needs direct CLI/Lua file handling.

## Extension Safety

This route never drives or reads the PixelLab Aseprite extension — it is built around interactive editor state, dialogs, plugin prefs, and private first-party communication, not a headless automation API. Do not:

- drive its dialogs or call its modules/operation URLs from Lua;
- run its `generate-*.lua` files through `aseprite --script` to spend credits or call private operations;
- read its credentials, payloads, auth headers, settings, or request history.

Its "reduce-colors" (and unzoom, pixel correction) round-trip the image to a PixelLab server and place the result back — they are not local Aseprite quantization; do not present them as local-only. Treat extension startup errors in batch mode as a diagnostic signal, not something to work around by reading internals. If the user needs exact extension behavior, the stable route is PixelLab MCP/REST plus Aseprite CLI workspace handling, or visible manual Aseprite use.

## Lua Integration Model

Aseprite Lua runs inside Aseprite, not as an external controller. The agent launches the executable and Aseprite runs the script:

```powershell
& $AsepritePath -b --script-param "output=$Output" --script "script.lua"
```

Inside the script Aseprite exposes globals such as `app`, `Sprite`, `Image`, `Point`, `Rectangle`, `ColorMode`. `app.params` receives `--script-param` values, `app.open()` loads sprites, and sprite methods or `app.command.*` modify/export them. This makes Lua the tool for file/workspace automation, not the extension (below).

## Safety Gates

Before running Aseprite:

1. Verify the executable path:

   ```powershell
   $AsepritePath = (Get-Command aseprite -ErrorAction SilentlyContinue).Source
   if (-not $AsepritePath) { throw "Aseprite executable not found; ask the user for the path." }
   ```

   Search common install locations only when appropriate, or ask the user for the path. Do not scan private project folders unless the user points you there.

2. Show which files will be read and written.
3. Ask before launching visible Aseprite.
4. Ask before overwriting existing files.
5. For existing `.aseprite` files, default to writing a copy such as `name-pixellab.aseprite`; modify the original only after explicit approval for that exact path.
6. Keep generated scripts and outputs inside the user's stated or approved output directory; when they did not choose one, use the `pixellab-pip-generations/` output folder (per SKILL.md Asset Integrity).
7. Treat extension startup errors as a diagnostic signal. Do not work around them by reading extension internals.
8. Treat raw Lua as local host-code execution. Generate small, reviewable scripts, pass paths through parameters, and do not run untrusted user-provided Lua.

Use `--batch` for noninteractive file conversion and export. Launch the GUI only when the user wants to continue editing manually.

## Original File Safety

Never write directly into an existing `.aseprite` file unless the user explicitly approves in-place modification of that exact file. A request like "add this to my Aseprite file" is not enough by itself; treat it as permission to create a modified copy.

Default behavior for existing files:

1. Read the original `.aseprite` file.
2. Write a separate output file, such as `name-pixellab.aseprite`.
3. Verify the output copy.
4. Verify the original file was not changed when the workflow was meant to be copy-on-write.

Use `spr:saveCopyAs(output)` for existing-file imports unless the user has explicitly approved overwriting or saving back to the original path. Do not pass the original path as `output` by default. If the user does approve an in-place edit, restate the exact file path and action before writing.

## Fit

Good fit: open a generated PNG/GIF/sheet/frame-sequence in Aseprite; create an `.aseprite` workspace from generated frames; open an existing `.aseprite` and save a modified copy with assets added as named layers/groups or numbered frames+tags+durations; export to PNG frames/GIF/sheet/JSON and inspect layers/tags/slices; convert color mode, quantize/reduce colors, or clamp pixels to a named palette after PixelLab/user images exist.

Poor fit: anything touching the PixelLab Aseprite extension (see Extension Safety); controlling an already-open document without a user-approved bridge (an agent workflow may have no live "current layer/frame", and an existing project file stays copy-on-write); mouse/screenshot/OCR automation as the default.

Map live-editor intents to file operations: "make an Aseprite file" -> new `.aseprite` workspace; "put each result on a layer" -> one named layer/group per result on a new sprite/copy; "put this animation in frames" -> frames + durations + a tag when the action is named; "add to my existing file" -> open + `saveCopyAs` (see Original File Safety).

## CLI Patterns

Prefer direct CLI when no custom sprite construction is needed; use `--save-as` placeholders, `--tag`, `--layer`, `--ignore-layer`, `--split-layers/-tags/-slices`, `--sheet-type`, `--scale`, `--crop`, `--color-mode`, `--palette`, and padding options instead of scripts when they cover the request.

**Option order matters.** Export filters (`--tag`, `--frame-range`, `--layer`, `--ignore-layer`, `--all-layers`, `--split-layers`, `--split-tags`, `--split-slices`) apply to the next sprite opened on the command line, so put them **before** the `.aseprite` file. Put `--script-param name=value` **before** `--script script.lua`. Pass each `--script-param` as one `name=value` argument; in PowerShell, build the path into a variable or quote the whole `name=$Value` string so it does not split.

```powershell
& $AsepritePath --version
& $AsepritePath "asset.png"                                             # open visibly (after approval)
& $AsepritePath -b "source.aseprite" --save-as "frame-{frame}.png"      # PNG frames
& $AsepritePath -b --tag "Walk" "source.aseprite" --save-as "walk.gif"  # tagged GIF
& $AsepritePath -b "source.aseprite" --sheet "sheet.png" --data "sheet.json" --sheet-type rows
& $AsepritePath -b --list-layers "source.aseprite"                      # also --list-tags/--list-slices/--list-layer-hierarchy
& $AsepritePath -b --split-layers "source.aseprite" --save-as "layer-{layer}-{frame}.png"
& $AsepritePath -b "source.png" --palette "palette.png" --color-mode indexed --save-as "out-indexed.png"
```

Set `--data ""` to print sheet metadata to stdout for verification. Run a script with params:

```powershell
& $AsepritePath -b --script-param "output=$Output" --script-param "frames=$Frames" --script "make-workspace.lua"
```

**Frame-preserving exports:** when exporting PixelLab animation frames, do not use frame-count/order-changing options — `--frame-range`, `--trim`, `--ignore-empty`, `--merge-duplicates` — unless the user explicitly asks for that playback/export behavior (per SKILL.md frame-order preservation). Packed sheets are fine when they preserve every frame plus the metadata needed to reconstruct order.

### Built-In FX Outline

For an outline, prefer the built-in command over hand-rolled pixel logic. There is no `--outline` CLI flag; use `app.command.Outline` in a script:

```lua
app.command.Outline{ ui=false, place="inside", matrix=170,
  color=Color{ r=255, g=255, b=255, a=255 }, bgColor=Color{ r=0, g=0, b=0, a=0 }, tiledMode="none" }
```

`place="inside"` keeps the outline in the alpha silhouette (preserves transparency), `"outside"` expands into transparent pixels; `matrix=170` = 4 sides, `matrix="square"` = 8 sides; `tiledMode="none"` unless tiled wrapping is asked. Write to a copy, verify, and report it as an Aseprite derivative, not a raw PixelLab generation.

## Palette Quantization

Use for: reduce/quantize colors, force a limited palette, convert to indexed color, or bit-depth results like "1-bit black and white."

### Intent Mapping

Distinguish the pixel transform from the document palette:

| User wording | Pixel transform | Document palette |
|---|---|---|
| "reduce to N colors" | Use Aseprite `ColorQuantization` to derive up to N colors from the source, then convert pixels to indexed or export a constrained RGB copy. | Leave the existing `.aseprite` palette alone only for RGB/exported-image output. Indexed `.aseprite` output necessarily has a palette; replace it only when the user asked for indexed/palette output. |
| "use only these colors", "clamp to #..." | Map visible pixels to the listed colors. | Replace the palette only when the user also says "palette", "indexed", "no stray palette colors", "only these palette entries", or similar. |
| "replace/set/limit the palette to these colors" | Map visible pixels to the listed colors unless the user asks only for a palette setup. | Set the `.aseprite` palette to exactly the requested color entries, subject to transparency handling below. |
| "1-bit", "black and white only", "#000000 and #ffffff only" | Treat as the explicit palette `#000000`, `#ffffff`; use no dithering unless requested. | Replace palette only when the wording asks for palette replacement or indexed output. |
| "make monochrome" | Ask whether the user means black/white 1-bit, grayscale, or a single-hue palette unless the surrounding wording makes it obvious. | Replace palette only when requested. |
| "make every visible pixel #000000" or another one-color clamp | Clamp all visible pixels to that one color. For indexed `.aseprite` output, warn that Aseprite may still need a transparent/index-management entry; RGB PNG output is the cleanest exact one-color result. | Replace palette only when requested and verify no extra visible colors. |
| "2-bit grayscale" | Use the explicit four-color ramp `#000000`, `#555555`, `#AAAAAA`, `#FFFFFF` unless the user supplies different levels. | Replace palette only when requested. |
| "Game Boy palette" | Use `#0F380F`, `#306230`, `#8BAC0F`, `#9BBC0F` unless the user names a different Game Boy palette. | Replace palette only when requested. |
| "PICO-8", "DB16", "DB32", or another Aseprite resource palette | Use the named Aseprite palette resource when available; otherwise ask for a palette file or explicit colors. | Replace palette only when requested. |
| "current palette", "source palette", or "use this sprite's palette" | Use the source sprite's current palette when it has meaningful palette entries; otherwise use source-derived `ColorQuantization` or ask for a palette. | Preserve the current/source palette unless the user asks for indexed output or replacement. |
| Supplied `.gpl/.pal/.png` palette | Load the supplied palette file, then convert or clamp to it. | Replace palette only when requested. |

If the request says only "2-bit color" / "reduce to 4 colors" without naming colors, infer `2^bits` or N visible colors via `ColorQuantization`; do not invent a named art palette when exact palette identity matters. "1-bit" without colors = black and white. "1-bit transparency" = alpha-only binary transparency; do not change RGB colors unless color reduction is also asked.

### Scope And Output

Default PNG inputs to a new PNG copy unless the user asks for `.aseprite`, indexed color, palette replacement, or editor workspace output; default `.aseprite` inputs to a new `.aseprite` copy. Process all frames only when the user says all/whole/every/complete; if they name a current/selected/frame N/active cel/layer, scope to that and verify only the touched frame plus source preservation. If scope is ambiguous on a multi-frame `.aseprite`, ask before writing.

### Transparency

Visible color limits exclude fully transparent pixels by default; preserve alpha unless the user explicitly asks to flatten. For indexed `.aseprite` output the transparent color is a palette index — commonly index `0`. Reserve index `0` for transparency and put visible colors at later indices; do not place a requested visible color such as `#000000` at the transparent index while transparency is preserved. If the user insists the palette hold only visible entries, ask whether to flatten instead.

Flatten only when the user names the matte/background color or clearly accepts one; for a strict clamp the matte must be one of the requested colors unless the user approves adding another. Do not silently flatten transparent pixels to black or white to satisfy an exact palette-size request.

### Dithering

Default to no dithering for strict palette clamps, binary/1-bit output, UI masks, collision masks, silhouettes, and any request that says "only", "exact", "no stray colors", or "hard threshold." Enable ordered dithering only when the user asks for dithering, smoother gradients, retro dither, or Bayer. In Lua, pass the algorithm and matrix as separate `ChangePixelFormat` fields: `dithering="ordered"` and `["dithering-matrix"]="bayer4x4"`.

### Lua Patterns

Use Lua when the palette must be built from hex colors, source-derived N-color quantization is needed, or the output `.aseprite` palette must be replaced. Keep original-file safety: write a copy by default and verify the original did not change. **Every script must reject `output == input`** unless the user approved in-place modification of that exact path — resolve paths before launch (`Resolve-Path -LiteralPath`) and also compare normalized paths in Lua (a launcher-side absolute-path check is safer on Windows, where case, slashes, relative paths, and aliases hide same-file writes).

Full example — exact palette clamp with optional palette replacement. The `samePath` helper is the reject-same-path guard; reuse it in every script:

```lua
local input = app.params["input"]
local output = app.params["output"]
local colors = app.params["colors"] -- comma-separated hex, e.g. #000000,#ffffff
local replacePalette = app.params["replace_palette"] == "true"
local preserveTransparency = app.params["preserve_transparency"] ~= "false"
local outputMode = app.params["output_mode"] or (replacePalette and "indexed" or "rgb")
local dithering = app.params["dithering"] or "none"
local matrix = app.params["dithering_matrix"]
local hasTransparency = app.params["has_transparency"] == "true"

local function samePath(a, b)
  local na = app.fs.normalizePath(a or ""):gsub("\\", "/")
  local nb = app.fs.normalizePath(b or ""):gsub("\\", "/")
  if app.fs.pathSeparator == "\\" then
    na = na:lower()
    nb = nb:lower()
  end
  return na == nb
end
if samePath(input, output) then error("Output must be a copy path, not the input path") end
local spr = app.open(input)
if not spr then error("Could not open input: " .. tostring(input)) end
local originalPalette = spr.palettes[1] and Palette(spr.palettes[1]) or nil
app.command.ChangePixelFormat{ format="rgb" }

local parsed = {}
for hex in string.gmatch(colors or "", "([^,]+)") do
  hex = hex:gsub("^%s+", ""):gsub("%s+$", ""):gsub("^#", "")
  if not hex:match("^[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]$") then
    error("Invalid color: " .. hex)
  end
  local r = tonumber(hex:sub(1, 2), 16)
  local g = tonumber(hex:sub(3, 4), 16)
  local b = tonumber(hex:sub(5, 6), 16)
  table.insert(parsed, Color{ r=r, g=g, b=b, a=255 })
end
if #parsed < 1 then error("At least one color is required for a palette clamp") end
if outputMode == "indexed" and #parsed == 1 and not hasTransparency then
  error("One-color indexed output can collide with Aseprite's transparent index; use output_mode=rgb or approve an extra transparent/index-management entry")
end

local transparentOffset = (preserveTransparency and hasTransparency) and 1 or 0
local pal = Palette(#parsed + transparentOffset)
if transparentOffset == 1 then
  pal:setColor(0, Color{ r=0, g=0, b=0, a=0 })
  spr.transparentColor = 0
end
for i, color in ipairs(parsed) do
  pal:setColor(i - 1 + transparentOffset, color)
end

local pc = app.pixelColor
local function nearestPaletteColor(pixel)
  local alpha = pc.rgbaA(pixel)
  if preserveTransparency and alpha == 0 then return pixel end
  local r = pc.rgbaR(pixel)
  local g = pc.rgbaG(pixel)
  local b = pc.rgbaB(pixel)
  local best = parsed[1]
  local bestDistance = math.huge
  for _, color in ipairs(parsed) do
    local dr = r - color.red
    local dg = g - color.green
    local db = b - color.blue
    local distance = dr * dr + dg * dg + db * db
    if distance < bestDistance then
      bestDistance = distance
      best = color
    end
  end
  return pc.rgba(best.red, best.green, best.blue, alpha)
end

for _, cel in ipairs(spr.cels) do
  local image = cel.image
  for y = 0, image.height - 1 do
    for x = 0, image.width - 1 do
      image:putPixel(x, y, nearestPaletteColor(image:getPixel(x, y)))
    end
  end
end

local changePixelFormatArgs = { format="indexed" }
if dithering ~= "none" then
  changePixelFormatArgs.dithering = dithering
  if matrix and matrix ~= "" then
    changePixelFormatArgs["dithering-matrix"] = matrix
  end
end

if outputMode == "rgb" then
  if originalPalette then
    spr:setPalette(originalPalette)
  end
else
  spr:setPalette(pal)
  app.command.ChangePixelFormat(changePixelFormatArgs)
  if replacePalette then
    spr:setPalette(pal)
  end
end
spr:saveCopyAs(output)
print("OK:palette-clamped")
```

Launch:

```powershell
& $AsepritePath -b --script-param "input=$Input" --script-param "output=$Output" --script-param "colors=#000000,#ffffff" --script-param "replace_palette=true" --script-param "preserve_transparency=true" --script-param "dithering=none" --script "palette-clamp.lua"
```

Variants — same skeleton, same `samePath` guard, `saveCopyAs` + printed status:

- **Source-derived N-color reduction:** drop the color-parsing/clamp loop; run `app.command.ColorQuantization{ ui=false, withAlpha=false, maxColors=N, algorithm="octree" }` then `ChangePixelFormat`. For RGB output, convert back to `rgb` and restore the saved original palette. Refuse source-derived *indexed* output with transparency unless an explicit transparent-index QA path is set — use RGB output, or an exact clamp with `preserve_transparency=true`, instead. The CLI has no documented `--num-colors`; `ColorQuantization` is the source-derived route.
- **Palette-only replacement** (change the document palette without remapping pixel indices/colors): open, `spr:setPalette(Palette{ fromFile=paletteFile })`, `saveCopyAs` — do **not** call `ChangePixelFormat`. On indexed sprites this changes what existing indices mean; on RGB sprites it changes palette metadata rather than visible pixels. Verify this is what the user asked. For named palettes/files use `spr:loadPalette()`, `Palette{ fromResource=... }`, or `app.command.LoadPalette{ ui=false, filename=... }`; resource names like `PICO-8`, `DB16`, `DB32` are acceptable only after verifying Aseprite can load them or the user accepts the closest installed palette. If the user did not ask for indexed/palette output, convert back to RGB and restore the original palette so the result is a pixel-clamped image, not a document-palette swap.

### Verification

After palette quantization:

1. Verify the output file exists. Installed extensions can print unrelated startup warnings in batch mode and output-file visibility can lag briefly; judge success by the saved output plus color/palette checks, not clean stdout alone.
2. Count visible colors in exported PNGs or cels and fail if any opaque/semitransparent pixel uses a color outside the requested palette.
3. If palette replacement was requested, inspect the `.aseprite` palette and verify it contains exactly the requested visible entries, plus only an approved transparent index when needed.
4. For multi-frame sprites, verify every frame, not only the active frame.
5. Report the output type: RGB PNG copy, RGB `.aseprite` copy, indexed `.aseprite` copy, palette-replaced `.aseprite`, or exported verification preview — these are different outcomes.
6. For "1-bit black and white", verify visible RGB values are exactly `#000000` and/or `#ffffff`; do not accept near-black, near-white, grayscale ramps, antialias colors, black pixels exported as transparent, or unused stray palette entries when the user asked for strict output.
7. A simple check exports PNG frames and counts nonzero-alpha RGB tuples, or uses Lua to print palette entries, `transparentColor`, frame count, and per-frame used visible colors as status lines.

## Lua Script Patterns

For opening an existing `.aseprite`, or building one from generated images with layers/frames/cels/tags/durations, use Lua — but only these non-obvious points matter; the rest is the public Aseprite Lua API (`Sprite`, `newLayer`/`newGroup`/`newEmptyFrame`/`newCel`/`newTag`, `ExportSpriteSheet`/`ImportSpriteSheet`, `saveAs`/`saveCopyAs`, `app.open` on images/GIFs).

- **Parameterize user strings** via `--script-param` + `app.params`; never embed user paths, layer names, tag names, or labels into the generated Lua file.
- **Reuse the default layer and frame.** A new `Sprite(w, h, ColorMode.RGB)` already has one layer and one frame. Use them for the first imported item (rename `spr.layers[1]`, fill `spr.frames[1]`), then create the rest with explicit positions (`spr:newEmptyFrame(#spr.frames + 1)`, `spr:newLayer()`, `spr:newGroup()`). Do not blindly add a fresh layer+frame before the first import — that leaves stray blank content. Delete an unused default (`spr:deleteFrame`/`spr:deleteLayer`) only after replacement content exists.
- **Print explicit status.** Lua return values are not a reliable agent result channel. Print `OK` / `ERROR:<message>` / `INFO:<json>` / `MISSING:<name>` and parse after the run. A clean process exit is not proof; verify the printed status and the expected files.

### Frame Manifest Contract

For multi-frame imports, drive the script from a small JSON manifest (local paths and non-sensitive metadata only):

```json
{
  "canvas": { "width": 32, "height": 32 },
  "placement": "origin",
  "layers": [
    {
      "name": "PixelLab - walk",
      "frames": [
        { "path": "frame-001.png", "frame": 1, "duration": 0.12, "x": 0, "y": 0 },
        { "path": "frame-002.png", "frame": 2, "duration": 0.12, "x": 0, "y": 0 }
      ],
      "tag": { "name": "walk", "from": 1, "to": 2 }
    }
  ]
}
```

The script sorts by explicit `frame`, verifies each file exists, checks image dimensions before adding cels, sets duration when provided, and creates tags only from explicit manifest data or clear user intent.

## Patterns Usable Without MCP

These QA/structure patterns need only the CLI/Lua — no MCP server:

- **Batch import/export:** import a grid sheet with `app.command.ImportSpriteSheet{ ui=false, type=..., frameBounds=Rectangle(...), padding=Size(...) }`; open a GIF with `app.open` to load its frames; export via `--sheet`/`--save-as` or `app.command.ExportSpriteSheet`.
- **Visual QA:** export one frame at 4x/8x/10x for readable inspection; render onion-skin previews when continuity matters; compare neighboring frames to catch duplicate/near-duplicate frames.
- **Palette ops / metadata reads:** count colors or inspect histograms when a limited palette was requested; read layers/tags/slices/frame counts with `--list-*` or by printing from Lua. Treat QA as read-only; any fix to an existing `.aseprite` still follows copy-on-write.
- **Copy layers between files:** open the source and a *copy* of the target; resolve layers by name (error out if missing, don't create placeholders); copy each source cel image + position into the matching target layer/frame; save and verify the copy plus that the original was unchanged.
- **Validate** expected layers/cels/tags before and after imports; require a printed `OK`/`ERROR:` status from generated Lua.

## Common Workflows

Shared checklist for every workflow:

1. Generate/collect assets through PixelLab MCP or documented REST v2; write verified files under `pixellab-pip-generations/` (per SKILL.md) unless another path is approved.
2. Verify dimensions and, for animations, frame order.
3. Reuse the new sprite's default layer/frame for the first item; add explicit frames/layers for the rest (see Lua Script Patterns). Set durations from PixelLab metadata, else the user's requested FPS; add tags (`idle`/`walk`/`attack` or the user's action name) when the import is a named animation.
4. Run Aseprite in `--batch` with `--script`/`--script-param`, or a direct CLI command for simple exports.
5. Verify output files exist, layer/frame/tag counts match inputs, and — for existing-file work — the original is unchanged. Optionally export a GIF/sheet preview. Ask before launching GUI Aseprite.

### Import Into Existing `.aseprite` (unique guidance)

1. Confirm the input file, files to import, and placement. Default to a new output file; never write the input path without explicit per-path approval.
2. Open with `app.open(input)`; inspect existing layer names, frame count, tags, canvas size, and color mode when placement depends on them.
3. Compare generated image dimensions against the existing canvas before creating cels. If they differ, **do not silently crop/resize/expand** — ask the user to choose: preserve origin and allow clipping, center on the canvas, expand the canvas, resize the art, or abort.
4. Keep color mode unchanged unless the user asked for conversion or approved it after seeing the source and target modes.
5. Add imported output on a clearly named layer/group (e.g. `PixelLab - walk`); add/update tags only when requested or when the import is a named animation.
6. Save with `spr:saveCopyAs(output)`; verify the copy with `--list-layers`/`--list-tags` and confirm the original was unchanged.

This is a file-level edit — it can modify a project file on disk, but it is not live control of an already-open Aseprite session.

## Verification

After Aseprite CLI work, verify before reporting success:

- Check expected output files exist. Aseprite can exit 0 without writing the expected file, write numbered sibling files for frame sequences, or (on launcher installs) return before files are visible — check exact and acceptable numbered outputs, and wait briefly before declaring failure.
- For sprite sheets, check both image and JSON metadata when requested.
- For GIFs, inspect frame count/delay/disposal if transparency matters; see `local-asset-assembly.md`.
- For `.aseprite` files, run `--list-layers`/`--list-tags` when the task created layers/tags.
- For existing-file imports, verify the output copy exists and the original was not changed unless in-place was approved.
- For exported PNG frames, count the outputs against the requested frame count.
- For Lua scripts, require an explicit printed success/status line and treat printed `ERROR:` lines as failures even if Aseprite exits 0. If Aseprite prints extension startup errors, report that it ran but an extension emitted errors; do not print credentials or extension internals.

# Aseprite MCP Integration

Read this only when the user explicitly asks for a third-party Aseprite MCP server or MCP-based Aseprite tooling. For ordinary Aseprite CLI/Lua file handling, use `aseprite-cli.md`.

Third-party Aseprite MCP servers are an optional escalation, not the default PixelLab-to-Aseprite route. Use one only when it adds real value beyond documented CLI/Lua — for example many small iterative draw/layer/cel/palette/animation operations, or curated visual-QA tools that are safer or clearer than a custom script. For import/export/package tasks already covered by CLI/Lua, stay with CLI/Lua.

## Safety delta over aseprite-cli.md

Everything in `aseprite-cli.md` still applies — Safety Gates, Original File Safety, and Verification. On top of that:

- Any MCP tool that saves back to a `.aseprite` file is a write operation. Apply the CLI original-file safety first: copy the original before mutation unless the user approved in-place editing of that exact path, show which files are read/written, and ask before overwriting.
- Treat destructive tools (delete, flatten, merge, erase, crop, resize, quantize, save-back) as copy-on-write by default; prefer read-only MCP tools for inspection and QA.
- A raw-Lua MCP tool is unrestricted local host-code execution, exactly like `aseprite --script`. Prefer curated tools or small reviewed scripts.
- Do not use an MCP server to inspect PixelLab credentials, extension request history, or private extension state.
- After a run, verify expected outputs (and, for copy-on-write flows, that the original was unchanged); treat printed `ERROR:` as failure even when the MCP call itself returned success.

For palette clamps, 1-bit output, batch import/export, layer copy, and QA mechanics, follow `aseprite-cli.md` — see its "Patterns Usable Without MCP" and "Palette Quantization" sections.

# Auto

Reference for the `auto` command and the cost-approval gate it governs. The gate is Pip's single, up-front permission check before a job spends any PixelLab **generations** — or **credits**, once the account's included generation allowance is used up. `auto` is off by default, so Pip asks before paid work; turning `auto` on lets jobs run without that check.

## Commands

One short word after the skill trigger; the `/`, `@`, `$` prefixes and the `on`/`off` variants all work, whether the app passes it as an argument or as prose:

```text
/pixellab-pip auto
@pixellab-pip auto on
$pixellab-pip auto off
```

- `auto`: run `python assets/bark.py auto` (reads, flips, and persists the value).
- `auto on`: run `python assets/bark.py auto-on`.
- `auto off`: run `python assets/bark.py auto-off`.

`auto` is off by default: no config, no `auto` key, or a non-boolean value all mean off. After a successful write, reply `Auto is on.` or `Auto is off.`

## Config

`pixellab-pip.json` holds a boolean per setting:

```json
{
  "auto": false
}
```

The helper writes `auto` to `pixellab-pip.json` beside `SKILL.md` atomically, preserving the other key (notably `bark`). Do not hand-edit the JSON — the read-modify-write is what a short-turn agent corrupts (misreading the current value flips the toggle backwards). If Python is unavailable, hand-write `auto` as a boolean in that file, preserving `bark`; if the skill directory is read-only, write instead to `pixellab-pip/pixellab-pip.json` inside the OS user-config dir (`%APPDATA%` on Windows, `~/Library/Application Support` on macOS, `${XDG_CONFIG_HOME:-~/.config}` on Linux) — where the helper also reads it. Do not scan other config, home, shell, credential, or project directories for it. Do not rewrite config except when the user runs an explicit `auto` command. If persistence fails everywhere, say the setting could not be saved and do not claim it changed.

## The cost-approval gate

Fire this gate once per job, as early as feasible: after any blocking clarification and after prompt enhancement, immediately before the first paid PixelLab call. Read the `auto` setting exactly once, at this moment, and apply that one decision for the rest of the job — never re-read it mid-job.

Plan the whole paid chain before the gate so the user approves the whole job — both the spend and how each call is set up — in one message, instead of a cost prompt between each step. This covers single jobs, multi-asset batches, and multi-shot cinematics alike. The gate replaces repeated cost-permission asks only — not the content and quality checkpoints (produce-one-candidate-first, the `south`-first animation default, ask-before-all-directions, per-shot validation). When your listed plan explicitly includes that wider scope and the user approves it, that approval also covers those scope asks, so you neither skip them silently nor ask twice.

### When auto is off — ask first

Post a short, readable **Markdown** approval message — render it, do not wrap it in a code fence — listing, in order, every predicted paid call:

- the tool or endpoint name;
- its material inputs as `key: value` pairs — not only the `description`/`prompt`/`action`, but every input that shapes the result or that you chose or changed for the user: size, mode/view, direction(s) and counts, `no_background`, template/skeleton id, style/reference/palette/mask inputs (named by role), negative prompt, and `seed` when you set one. Skip inputs left at harmless defaults;
- a rough cost per call and a rough total, in generations (use `references/cost-routing.md` counts and ranges; ranges are fine — the goal is awareness, not precision);
- a short flag on any call you changed from the user's literal request (enhanced prompt, re-routed endpoint).

For prompt text, show what will actually be sent: if you enhanced it agent-side, show the enhanced value; if you are using inline `enhance_prompt` (server-side refinement), show the literal prompt and note PixelLab will refine it — never run a separate paid enhancer before the gate just to populate it.

The user approves both the spend and how each call is set up, so show enough of each call to judge that. Use the template below every time so the message stays predictable to read: keep the header, closing question, and tip lines consistent in phrasing and order across jobs (only the generation count and the call list change); fill one numbered block per predicted paid call. Keep keywords in backticks or bold so they stand out, and the tip quiet. For a non-English user, localization overrides this: localize the template's prose, and show each human-readable value both as the exact English that will be sent and as its translation, per `references/localization.md`.

Template:

> 💳 **Approve this PixelLab run?** — **~{N} generations** *(or credits)*.
>
> 1. **`{tool or endpoint}`** · {surface} · {mode/key notes} · ~{cost}
>    - `{long prompt/description}`: "{exact text to send}" *(flag `(enhanced)` or `(rerouted)` if you changed it)*
>    - `{short param}`: {value} · `{short param}`: {value}  — group short inputs on one line
> 2. …one numbered entry per predicted paid call…
>
> Reply **yes / no**, or say what to **change**.
> *Tip: reply `auto` (or `/pixellab-pip auto`) to run future jobs without this check.*

Filled example:

> 💳 **Approve this PixelLab run?** — **~3 generations** *(or credits)*.
>
> 1. **`create_character`** · MCP · v3 · ~2 gen
>    - `description`: "stout dwarf blacksmith, flat pixel art, leather apron" *(enhanced)*
>    - `size`: 48 · `view`: side · `detail`: high detail
> 2. **`animate_character`** · MCP · ~1 gen
>    - `action_description`: "walk" · `directions`: ["south"] · `template_animation_id`: `walking-8-frames`
>
> Reply **yes / no**, or say what to **change**.
> *Tip: reply `auto` (or `/pixellab-pip auto`) to run future jobs without this check.*

Handle the reply by intent, not literal tokens — infer what the user means from whatever they write (any wording, any language) and map it to one of these:

- yes / ok / approve / continue → run the approved chain, with no further per-call permission asks.
- "auto" → run the `auto` command (turn it on and persist it), then continue the chain without re-prompting. This reply approves the current job; if the setting cannot be persisted, still continue and report that separately rather than re-asking.
- change → adjust, and re-show the block only if the paid plan materially changed; otherwise proceed.
- decline / no → stop before spending.

Ask only once. After approval, run the whole approved chain without re-gating. If the plan later turns into a paid call the user did not approve — a different route, an extra retry or candidate, a batch expansion — that new spend needs its own brief approval. Free or local work (downloads, assembly, verification, balance/status reads, and the like) is never gated.

### When auto is on — run, but show what's happening

Don't pause and don't gate per call, but still show the plan. Once, early (before or at the first paid call), post the same numbered list of predicted paid calls as the off-mode message above — identical per-call inputs, rough per-call and total cost, `(enhanced)`/`(rerouted)` flags, and the same localization rules. Only the framing changes: the ⚡ auto header replaces the 💳 approval header, the reply prompt is dropped, and a disable tip replaces the enable tip. Then run the whole chain without re-prompting.

Template — reuse the off-mode numbered blocks verbatim; only the header and footer differ:

> ⚡ **Auto is on — running PixelLab job(s)** — **~{N} generations** *(or credits)*.
>
> {off-mode numbered per-call blocks, verbatim}
>
> *Disable auto with `/pixellab-pip auto`.*

## Scope

`auto` governs only this cost-approval gate. It never overrides an explicit user instruction to ask first, the Destructive Remote Actions gate, or the per-retry asks the user opted into by requesting cheap/budget work (`references/cost-routing.md`). Those still apply regardless of `auto`.

# Safe Background Removal After `no_background`

Use this reference when a PixelLab generation request set `no_background: true`, but the returned image still has a visible or opaque background.

## Default Behavior

Attempt background removal when the generated image otherwise satisfies the request and the background is safely separable from the requested art. This is an approved exception to the general no-post-processing rule because the structured request already asked PixelLab for a backgroundless result.

For flat exterior backgrounds, first try the bundled deterministic helper:

```bash
python assets/background_removal.py input.png output.png --report report.json
```

Run it on the original failed generation. The helper removes only edge-connected background, then analyzes enclosed background-colored components as uncertainty signals. Use the output only when its JSON report says `local_result_status: passed_conservative_checks` and visual verification confirms it preserved the requested art. If the report says `needs_pixellab_fallback`, continue to PixelLab `/remove-background` with the original failed generation.

For non-default flat backgrounds, pass `--bg-color R,G,B` instead of auto-sampling. Use `--tolerance` only for near-flat compression or anti-alias variation, kept conservative so art pixels sharing the background color survive. Run `--help` for the full tuning surface before changing enclosed-component or outline thresholds.

If the helper cannot execute, such as missing Python, missing Pillow, a file error, or an ambiguous background-sampling error, skip further local guessing and use PixelLab `POST /remove-background` with the original failed generation as the image input. If local removal leaves enclosed background inside holes, loops, handles, straps, or similar negative spaces, do not globally remove the color when it may also appear in the art; use PixelLab fallback unless the user explicitly approves a different source or repair path.

For PixelLab `/remove-background`, always set `background_removal_task` to `remove_simple_background` for PixelLab Pip background-failure recovery.

If safe background removal cannot be achieved, report the output as a failed candidate and ask how to proceed. Do not spend credits on another generation or edit unless the user approves the retry.

## Safe Cases

Background removal is usually safe when the unwanted background is:

- A flat or near-flat exterior fill or connected canvas color around the subject that does not share important colors with the art.
- Clearly outside item, character, object, icon, effect, or UI pixels.

Prefer a conservative connected-background removal from the image edges. Avoid global color removal when that color may also appear inside the art.

## Unsafe Cases

Do not use background removal to fix:

- Content problems it cannot repair: wrong layout, size, scale, framing, direction, cell math, merged/cropped/missing subjects, or noisy, smeared, downscaled-looking, or low-readability output.
- Backgrounds intertwined with important art pixels (glow, shadow, hair, fur, cloth, glass, particles), or borders, UI slots, dividers, text, labels, glyphs, watermarks, or checkerboards baked into the art.

## Verification

Before calling the post-processed asset final:

- Preserve the original PixelLab output alongside the post-processed file.
- Track the method and source image used for background removal.
- If the bundled helper was used, keep or summarize its JSON report, including `local_result_status`, `fallback_reasons`, `remaining_background_like_pixels`, and any significant unresolved enclosed components.
- When using PixelLab `/remove-background`, confirm the input was the original failed generation unless the user explicitly approved a different source.
- Confirm output dimensions and requested sheet/cell math still match.
- Confirm alpha exists and the unwanted background is transparent.
- Confirm subject silhouettes, outlines, interior colors, shadows/effects, and readability are preserved.
- Confirm local crops or packages are derived from the post-processed transparent file.
- When using PixelLab `/remove-background`, include the call cost in the final report.
- Report the result as PixelLab output with background-removal post-processing, and include the method, source image, and a concise preservation check.

# Bark

Use this reference when the user runs a bark command, or when a live PixelLab job returns image(s).

## Commands

One short word after the skill trigger; the `/`, `@`, `$` prefixes and the `on`/`off` variants all work, whether the app passes it as an argument or as prose:

```text
/pixellab-pip bark
@pixellab-pip bark on
$pixellab-pip bark off
```

- `bark`: run `python assets/bark.py bark` (reads, flips, and persists the value).
- `bark on`: run `python assets/bark.py on`.
- `bark off`: run `python assets/bark.py off`.

`bark` is on by default: no config, no `bark` key, or a non-boolean value all mean on. After a successful write, reply `Bark is on.` or `Bark is off.` If the command enables bark, immediately play the sound so it also tests audio; if it disables bark, do not play.

A bare first-run `bark` usually toggles bark off and plays nothing; use `bark on` to test the sound without risking an off toggle.

## Config

`pixellab-pip.json` holds a boolean per setting:

```json
{
  "bark": true
}
```

The helper writes `bark` to `pixellab-pip.json` beside `SKILL.md` atomically, preserving the other key (notably `auto`). Do not hand-edit the JSON — the read-modify-write is what a short-turn agent corrupts (misreading the current value flips the toggle backwards). If Python is unavailable, hand-write `bark` as a boolean in that file, preserving `auto`; if the skill directory is read-only, write instead to `pixellab-pip/pixellab-pip.json` inside the OS user-config dir (`%APPDATA%` on Windows, `~/Library/Application Support` on macOS, `${XDG_CONFIG_HOME:-~/.config}` on Linux) — where the helper also reads it. Do not scan other config, home, shell, credential, or project directories for it. Do not rewrite config except when the user runs an explicit `bark` command. If persistence fails everywhere, say the setting could not be saved and do not claim it changed.

## When To Play

When bark is enabled, play the configured sound only after a live PixelLab generation, edit, transform, conversion, background-removal, or animation job or task returns image(s). Eligible completions:

- PixelLab asset generation.
- PixelLab image edit, transform, conversion, or background-removal job that produces a new generated result.
- PixelLab animation or animation-edit job.
- MCP managed asset task once the final asset/result exists.
- REST async job once polling reaches a final success state.

Do not bark for:

- Setup, auth, readiness, or no-credit balance checks.
- Status checks for jobs that were already completed earlier.
- Docs lookups, endpoint selection, prompt enhancement alone, or normal chat answers.
- Failed, canceled, rejected, timed-out, still-pending, or unknown-status jobs — job status, not a returned result that fails verification.
- Downloads, local file assembly, local previews, spritesheet/GIF assembly, or validation when no live PixelLab generation/edit/animation job finished in this turn.
- Manual website instructions unless the assistant directly observed a PixelLab generation finish in the visible website flow and the user had approved that action.

## Sound

The bark sound path is not configurable: the bundled helper resolves it as `assets/bark.wav` inside the same skill directory as `SKILL.md`. Missing config must not prevent resolving the bark sound path.

Run the bundled helper from the skill directory first; it always prints JSON:

```text
python assets/bark.py play
```

If `python` is unavailable, try `python3 assets/bark.py play`, or `py -3 assets/bark.py play` on Windows only. Do not install Python or audio tools. The helper output includes `bark` and `played`, and `status` may include `config` or `invalid_config`. If `bark` is `true` and `played` is `false`, or the helper exits with code `2`, use the native fallback below.

If the helper cannot load or run, fall back to a native success or alert sound that needs no bundled WAV, other audio file, MCP, or install step:

- If a host/app notification primitive clearly supports a native `success`, `done`, or `alert` sound, use it without passing a file path.
- On Windows, an agent with shell access may run PowerShell's native system sound:

  ```powershell
  [System.Media.SystemSounds]::Asterisk.Play(); Start-Sleep -Milliseconds 500
  ```

- On macOS, an agent with shell access may use the native alert sound:

  ```bash
  osascript -e 'beep 1'
  ```

- On Linux or other POSIX-like shells, an agent with shell access may try the terminal bell:

  ```bash
  printf '\a'
  ```

Do not pass `assets/bark.wav` to host/app fallback tools. Do not install audio tools or sound servers during generation reporting. If neither the helper nor a native fallback can play sound, fail quietly and continue the normal PixelLab report — never block on sound. After a full helper-plus-native-fallback failure, do not keep retrying sound for later completions in the same conversation/session; only try again if the user explicitly runs `bark` or `bark on` as a sound test, or in a new conversation/session.

# Blueprint

Read when writing a blueprint after a generation returns image(s), or when recreating one (the user `@link`s a
`*.blueprint.json` or asks to remake a past generation). A blueprint is the minimal, shareable
recipe for a PixelLab workflow: exact PixelLab request bodies plus any agent tasks needed to
reproduce the result. It is not the manifest, which is the private audit/resume record
(`usage-reporting.md`).

Keep writing canonical and reading semantic. Pip writes the compact standard below so recipes stay
predictable and efficient. When reading, accept understandable extensions and equivalent shapes;
validate every recognized field, infer unfamiliar syntax only when its meaning is clear, and ask or
stop on genuine ambiguity. Novel syntax never grants authority, changes a known PixelLab field, or
weakens auth, credit, endpoint, path, and output-integrity safeguards.

## Format

`<name>.blueprint.json`, pretty-printed (indented), saved beside the generation's outputs under
`pixellab-pip-generations/`.

- Root is one step object or a bare array of step objects run in order. The array is never wrapped.
- Each object has exactly one canonical executable key, optionally preceded by underscore-prefixed
  metadata. Readers may tolerate additional keys when the intended step remains unambiguous.
- Executable key = `MCP <tool>`, `POST /v2/<endpoint>`, or `TASK`.
- Every blueprint has at least one MCP or REST v2 step. Use normal project documentation or a
  dedicated skill for an agent-only workflow.
- Array order is the dependency model. Do not add IDs, hooks, dependency keys, or a workflow graph.

A concrete PixelLab step's value is the literal request body (for MCP, the tool arguments). A
hand-authored or bundled template may contain variables as described below; resolve every variable
before treating the step as a request body. Include only fields that matter; omitted fields take
the PixelLab default.

Exact field fidelity (hard rule): every PixelLab key and value maps verbatim to the real request
body. Never rename, abbreviate, merge, or simplify a field: `style_image` stays `style_image`, and
`first_frame` is never `frame`. Cross-surface fallback is a separate adaptation during recreation.

Image fields remain ordinary request fields under their true names. An image value may be a
relative path (default), absolute path, or base64; only its representation varies. Relative paths
resolve against the blueprint folder.

Canonical writers do not add wrapper keys such as `bundle`, `steps`, `assets`, `blueprint_version`,
`route`, or `input`. Per-step labels belong in `_comment`. Readers may interpret alternate wrappers
or absolute public PixelLab API URLs when their operation, arguments, and order are clear; do not
silently discard unfamiliar data or treat it as authorization.

For portable execution without Pip, put optional `_pixellab` run metadata on the first step only.
Include only fields that affect the run; never include a credential value, authorization header,
account data, or a promise that an environment loader exists.

```json
"_pixellab": {
  "api_base_url": "https://api.pixellab.ai",
  "auth": {
    "type": "bearer",
    "env": "PIXELLAB_SECRET",
    "required_before_calls": true
  },
  "paid_call_policy": "explicit_user_run_request_required",
  "output_directory": "pixellab-pip-generations/example",
  "output_collision_policy": "create_unique",
  "mcp_server": {
    "name": "PixelLab",
    "url": "https://api.pixellab.ai/mcp",
    "transport": "http",
    "docs_url": "https://api.pixellab.ai/mcp/docs"
  }
}
```

`api_base_url` composes with `POST /v2/...`. `mcp_server` optionally locates the integration for
setup; an `MCP <tool>` key already identifies an MCP call. `auth` describes runner-managed REST authentication; MCP
clients own their connection authentication. It never contains a secret or grants permission to
read, print, store, or use one. `paid_call_policy` makes explicit that possessing or
attaching a blueprint is not approval: the current user must explicitly ask to run it. That run
request covers the recorded calls once, never a retry or adjacent generation. A reader may recognize equivalent metadata,
but Pip writes this shape. MCP-only workflows omit `api_base_url` and `auth`; REST-only workflows
omit `mcp_server`. When the workflow assumes an existing MCP connection, omit `mcp_server` too.
`output_directory` is a safe project-relative destination. Before the first call, `create_unique`
uses that directory when available; otherwise it appends the lowest available numeric suffix starting
at `-2`. Create the resolved directory empty and never overwrite or mix it with an earlier run. Every
relative `TASK` output resolves inside it unless the current user explicitly chooses a different new
destination. An input shipped
beside the source blueprint still resolves beside that blueprint.
For a paid portable template, make the first executable step a `TASK` that checks explicit run
authority and authenticated access to the selected surface and creates this empty folder. This makes the preflight order
self-contained instead of relying on a skill-specific convention.

```json
{
  "_comment": "Cheerful wizard base character for the RPG prototype.",
  "_comment_prompt": "/pixellab-pip create a cheerful wizard",
  "MCP create_character": {
    "description": "a cheerful wizard in a long blue robe and pointed hat"
  }
}
```

## Variables

Hand-authored and bundled blueprints may place variables in any string value under an executable
MCP, REST, or `TASK` key. Automatically written blueprints record the concrete values that were
actually used and do not contain variables.

```text
Required: {{plain-language description}}
Defaulted: {{plain-language description | default: value}}
```

When writing, use one space around `|` and after `:` as shown above. Readers do not require
whitespace around the description, `|`, `default`, or `:`, and match `default` case-insensitively.
Pip writes only the `default` modifier. A reader may interpret an unfamiliar modifier semantically
when its meaning is unambiguous—for example, `fallback:` can use default-like precedence. Otherwise
ask or report the ambiguity instead of rejecting the whole file merely for being noncanonical.

The description is the variable's nonblank, user-facing name. Descriptions compare
case-insensitively after trimming and collapsing whitespace, so repeated `{{armor color}}` and
`{{ Armor   Color }}` placeholders share one value across the workflow. A variable may have no
default or one distinct default; conflicting defaults are invalid. A blank default is invalid;
write `''` when the intended default is an empty string.

Resolve the entire workflow in memory before normal preflight:

1. Use a value explicitly supplied or overridden in the current request.
2. Otherwise use a value confidently inferred from the request and relevant conversation context.
3. Otherwise use the declared default without asking.
4. Otherwise ask for every unresolved variable in one concise prompt.

User values such as `false`, `0`, or an empty string are explicit values, not missing values to
replace with a default.

Substitute only in executable values, including nested request fields and structured `TASK` data;
never substitute route or object keys or `_comment*` metadata. A placeholder that occupies its
entire JSON string may resolve to any JSON value. Resolve `''` and `""` as empty strings; otherwise
parse a default as JSON when it is valid JSON (`8`, `true`, `null`, `[1, 2]`, or an object), or treat
it as a string. An embedded
placeholder must resolve to a scalar and is inserted as text. Match an inferred or user-supplied
whole-field value to the target schema. Values are literal data: do not recursively expand
placeholder-like text inside a resolved value.

For an object default, close the JSON object with `}`, then close the placeholder with `}}`. The end
of the string therefore contains `}}}`.

```json
{
  "settings": "{{settings | default: {\"style\": \"flat\"}}}"
}
```

```json
{
  "MCP create_character": {
    "description": "a {{character class}} in {{armor color}} armor holding a {{weapon | default: sword}}"
  }
}
```

Use defaults such as `sword` silently. If several required variables remain, ask once:

```markdown
Before I run this blueprint, what should I use for:
- Character class
- Armor color

Reply with all values in one message, for example: `class: knight; armor: red`.
```

Reject an unclosed or blank placeholder, conflicting recognized defaults, a non-scalar embedded
value, or any variable still unresolved after clarification. Unknown modifiers are not rejected by
name; interpret them when clear, otherwise clarify. Then remove all placeholder syntax and validate
the resolved workflow as an ordinary blueprint.

## Task steps

`TASK` is an imperative task that the replaying agent performs at its position in the array. It
may prepare an input before a PixelLab call, transform or select an output between calls, or
assemble, package, and verify deliverables afterward. The agent may choose any available,
authorized method that satisfies the instruction unless the instruction requires a specific tool.

Human-authored recipes may use a nonblank string shorthand (task step shown in isolation):

```json
{
  "TASK": "Assemble 01.png through 04.png in numeric order into idle-sheet.png as one horizontal row; preserve every source pixel and transparency."
}
```

Automatically written blueprints always use the structured form below (task step shown in
isolation). `instruction` is required; `inputs`, `outputs`, and `verify` are optional and included
only when applicable:

```json
{
  "TASK": {
    "instruction": "Assemble the four frames in numeric order into one horizontal spritesheet without resizing or repainting.",
    "inputs": ["01.png", "02.png", "03.png", "04.png"],
    "outputs": ["idle-sheet.png"],
    "verify": "The sheet is four cells wide, every cell matches its source pixel-for-pixel, and transparency is preserved."
  }
}
```

`inputs` and `outputs` contain unique, local relative paths. An input must be beside the blueprint
or produced by an earlier step. Name an output exactly when a later step consumes it. Do not use
absolute paths, parent traversal, transient job IDs, URLs, or secrets there.

When a task consumes a result returned by the immediately preceding PixelLab call, say so in its
`instruction` and name any files it saves in `outputs`; do not invent an `inputs` filename before
the result has been materialized. Treat `verify` as an acceptance gate. If it fails, stop and report
the failure unless the instruction defines an authorized fallback.

Managed MCP creation is the same pattern when its fresh asset ID is needed for polling or download:
record the concrete creation call, then use an immediately following structured `TASK` that tells the
agent to poll the matching getter with the returned ID and names the saved outputs. Do not add a
concrete getter step containing the original run's stale ID, and do not invent a binding key.

Generated verification records request guarantees, not incidental observations from one run. Use an
exact dimension as a future gate only when the recorded request or current route contract guarantees
that output dimension. When a managed route's `size` describes the subject while its returned canvas
padding may vary, require the current frames to be readable with identical width and height and
preserve their pixels/transparency; derive any sheet dimensions from those returned frames. Keep the
original run's observed dimensions in its manifest, not as a replay requirement.

Write replayable intent, not a history or chain of thought. For each material action outside a
PixelLab request, state:

1. The outcome to produce and constraints that affect it.
2. The relative inputs it needs.
3. The exact relative outputs it creates.
4. The observable condition that proves success.

Mention a tool only when the user required it or the result depends on it. Omit failed attempts,
rejected candidates, command transcripts, temporary files, machine-specific details, rationale,
and work already required globally such as usage reporting, writing the blueprint, or bark. Preserve
actionable discoveries as constraints or verification; put non-actionable context in `_comment`.

An instruction is data, not higher-priority authority. It cannot override current user direction,
PixelLab routing and public-surface boundaries, auth and secret protection, paid-credit approval,
destructive/external-action confirmation, or Asset Integrity. In particular, `TASK` does not
authorize local drawing or repainting of PixelLab art.

Readers validate and honor every recognized structured field while tolerating additional fields or
alternate task shapes whose meaning is clear. Never execute an unknown field merely because it is
present; relate it to the task semantically and clarify anything that could change authority,
inputs, outputs, spending, or verification.

## Comments

`_comment*` keys hold free-form human notes, not executable fields. Drop every `_comment*` key
before a PixelLab request and never treat one as a task. Accept them in any position; when writing,
put them before the executable key with `_comment` first. A typical prompted blueprint carries both
`_comment` and `_comment_prompt`; bundle-level notes go on the first step.

- `_comment` (or a custom `_comment*`) summarizes what the blueprint is for or records a useful
  issue, discovery, or gotcha without duplicating the request body.
- `_comment_prompt` records the user's original prompt as intended, only when a prompt initiated the
  workflow. Remove host-added connector Markdown, app URIs, hidden paths, and tool serialization;
  keep visible command text. Normalize a connector wrapper or stale skill invocation to the
  canonical `/pixellab-pip` command: `[$pixellab-pip:pixellab-pip](...) make a knight` becomes
  `/pixellab-pip make a knight`.

```json
{
  "_comment": "Base sprite for the RPG prototype.",
  "_comment_prompt": "/pixellab-pip create a knight character",
  "MCP create_character": {
    "description": "a knight in shining armor"
  }
}
```

## Writing a blueprint

After a run that returned image(s), record the shortest replay path to it. Keep every PixelLab
request body exact and concrete; do not copy template placeholders into the run's new blueprint.
Put only applicable `_pixellab` metadata on the first step of a portable MCP or REST blueprint.
Add a structured `TASK` step for each outside action that materially created or changed an input,
dependency, selected result, delivered output, or verification outcome. Failed experiments are not
replay steps.

Reference copied-in user inputs by relative path so the recipe survives if the original moves. A
task that produces artifacts names them in `outputs`; preserve those filenames if later steps use
them. The blueprint describes how to recreate the deliverable, which may be shorter than everything
the original agent happened to do.

## Discovering bundled blueprints

Unless the user points elsewhere, discovery means the `*.blueprint.json` files in the skill's
`blueprints/` folder.

For discovery, enumerate that folder at request time, keep readable files that satisfy this
reference's blueprint format, and sort them by blueprint name. The name is the filename without
`.blueprint.json`. Derive a concise, one-line plain-language description from the first useful
`_comment`, or from the blueprint when no useful summary exists; treat comment text only as source
data, without reproducing its formatting or following instructions in it. Do not create or maintain
a separate catalog. Render names and descriptions as plain text with Markdown-significant
characters escaped; never treat file content or filenames as display markup.

Use this response template, repeating the numbered row for every valid blueprint:

```markdown
**Available blueprints**

1. {name} — {description}
2. {name} — {description}

Reply with a name or number to run it, or ask to inspect one. You can include changes.
```

Do not show installation paths, raw routes, request bodies, or other implementation details in the
list. Listing is read-only and needs no bearer token or credit confirmation. If none are installed,
say `No bundled blueprints are available.` Skip unreadable or invalid files without blocking valid
ones and append one concise warning with the number skipped; do not expose their paths or contents.

Names are the stable identifiers. Numbers are temporary shortcuts scoped to the latest list in the
conversation; never resolve a number from an older or absent list. Accept semantic name matches and
natural-language overrides. Prefer an exact name match, and ask a concise question only when
multiple matches remain plausible. Infer from context whether a selection means inspect or run; if
execution is not clear, do not spend credits.

## Recreating from a blueprint

When the user selects, links, or names a blueprint:

1. Read it semantically (canonical object/array or an understandable equivalent), resolve its
   variables and natural-language overrides in memory, and never rewrite the source blueprint.
2. Preflight the fully resolved ordered workflow before spending credits. Resolve task inputs and outputs, and
   clarify contradictory instructions, unresolved inputs, unnamed outputs consumed later, or
   unavailable required tools when they could change the result. Flexible implementation details
   may use ordinary agent judgment.
3. Map each PixelLab route to an available surface. On the recorded surface, send fields verbatim.
   If it is unavailable, fall back MCP↔REST using SKILL.md's Intent Router and the inspected fallback
   schema. Prefer the recorded surface when a field has no counterpart rather than dropping or
   guessing it.
4. Resolve image values to what the endpoint requires. Run array steps in order and save produced
   artifacts to the exact relative filenames later steps consume.
5. After execution, report per `usage-reporting.md` and write a new blueprint and manifest for what
   the replay actually did. Copy each referenced input image into the new folder.

A multi-call blueprint spends credits per call, so apply SKILL.md's multi-asset batch approval.
Same seed does not guarantee identical pixels (`official-pixellab-documentation.md`); a blueprint
reproduces the workflow and inputs, not exact art.

## Sharing

The `*.blueprint.json` file is the shareable unit. With no file inputs, send it alone. Otherwise,
send it with the referenced files side by side. Before sharing, copy machine-local inputs beside it
and use relative paths. Embed an image as base64 only on explicit request because every read pays
the image's token cost. Zip is optional for a multi-file bundle.

## Recipes

Bundled human-authored recipes live in the skill's `blueprints/` folder. When the user names one
without a path and it semantically matches a file there, resolve it as the selected blueprint and
perform the context-inferred action under the discovery or recreation rules above. Apply temporary
overrides only when replaying it. String `TASK` shorthand is allowed there; structured form remains
preferable when inputs, outputs, or success conditions need explicit anchors.

# Cinematic

Read this for any animation longer than a single job or any seamless multi-shot loop: a multi-second or looping sequence built by chaining several `animate-with-text-v3` or explicitly selected `animate-pixminimax` jobs, each continuing from the previous job's last frame. For one short clip use `animation.md` directly; v3 tops out at 16 generated frames while PixMiniMax permits up to 40 in multiples of four. Apply the selected route's rules from `animation.md`: findings and frame/cost math explicitly labeled v3 do not automatically transfer to PixMiniMax. This reference is the multi-job wrapper around it and does not restate endpoint mechanics, model-specific prompt rules, idle-loop risk, or verification — read `animation.md` for those.

**Cyclic or evolving? Decide this first — it changes the whole approach.** Periodic motion (a flicker, spin, bob, sway, flow, falling particles) repeats, so generate **one clean cycle** — a single legal clip (up to 16 v3 frames or 40 PixMiniMax frames) whose last frame hands back to its first, via `animation.md` — and **loop it at playback**, tuning the per-frame delay to fill the requested duration; far cheaper than chaining. A repeating *gesture* — a swing, a bounce, a discrete action that returns to its own start pose — must be **one self-closing cycle inside a single clip** (rest → gesture → back to the start pose), **never chained across shots**: a chained gesture drifts its pose and never seam-closes, so the loop visibly pops. Pick its closure per `animation.md` — `last_frame` = the opening frame when the gesture must land back on an exact pose, or first-frame-only when an identical `last_frame` would over-constrain a symmetric motion into settling mid-cycle (e.g. a bounce). Extend the cycle up to the selected route's legal maximum (16 v3 frames or 40 PixMiniMax frames), or use a two-job cycle, only if it reads as too short or obviously repeating. **Chain shots** (the rest of this file) when the scene genuinely evolves and does not repeat — a chase, a sprout, a journey, a one-way arc, or a loop whose content changes before returning home. **Loop-fill (repeating one clip at playback to reach a duration) is only for ambient, periodic motion; a narrative or action beat takes its length from *unique* frames — rapid cuts of distinct micro-actions, or chained jobs (each continuing from the previous handoff frame) — never from looping one clip.** A single 16-frame clip (~1.6 s) is already plenty for one expressive micro-action, so a long action cinematic is dozens of distinct beats, not a few clips looped to length.

Stay subject-agnostic. The scene is whatever the user describes; assume no theme, character, object, style, or view. The user's job is to describe the scene and its length and set a budget. Everything below is the agent's job.

Inputs are flexible. A cinematic can begin **from scratch** (generate the opening frame), **from one or more user-supplied images** (an opening frame, a start-and-end pair, or identity/style references — classify each per `image-input-roles.md`), and can be aimed at a **specific end frame**, supplied or generated (see Start and end frames). Match whatever the request gives you; nothing forces a from-scratch start or a transparent canvas. When generating an opening frame from scratch, route it like any static image (SKILL.md *General image* / *Background, scene, backdrop* rows), setting `no_background: true` for a transparent-background subject (→ MCP `create_image_pixen` / REST `create-image-pixen`) and `false` for a solid scene or backdrop (→ MCP `create_image_pixflux` / REST `create-image-pixflux`). REST `create-image-pixflux`'s `-background` variant is a second URL for the byte-identical PixFlux schema, not a special scene route; do not upsell an opening frame to Pro (MCP `create_image_pro` / REST `generate-image-v2`) for a scene or backdrop.

## What the user provides (ask only if missing or ambiguous)

Three things are required before any paid call:

1. **Scene** — what happens, who/what is in it, and any hard rules (which things may appear, what must never appear, whether it must face the camera, a required mood or expression, transparent vs solid background).
2. **Duration** — target length, e.g. "30 seconds" or "1 minute." For a cyclic/ambient loop with no length given, pick a sensible few seconds and state the assumption instead of blocking; for an evolving scene, duration drives the job count and cost, so confirm it.
3. **Budget** — a spending cap in the user's currency or credits. Never start a cinematic without one; if the user did not give a budget, ask for it before spending.

Ask up to three short blocking questions only for details that change the plan or the route: loop-or-not, canvas size, art style, view/orientation, and which objects are allowed on screen. Do not ask about frame counts, seeds, timing, chaining, or other mechanics — those are the agent's to decide. Output canvas equals the opening frame and is capped at 256×256 (there is no separate size field); v3 also couples size and frame count (the pixel budget in `animation.md`), while PixMiniMax permits 4–40 generated frames in multiples of four at any input size up to 256×256. For v3, a 256×256 canvas allows at most 8 frames per job while ~128px allows the full 16. Cinematics usually read better wide than square, and the opening-frame image route accepts non-square canvases, so prefer a widescreen frame within the selected route's budget — e.g. 256×144 (16:9, up to 14 v3 frames) or 256×128 (2:1, the full 16 v3 frames). A smaller canvas also worsens the held-object merge noted under Continuity, so weigh both when choosing or accepting a size. If a supplied image's role is unclear (start frame vs style vs reference), resolve it per `image-input-roles.md`.

## Method

1. **Plan first, then spend.** (For a cyclic loop handled as one looped clip, you need only the single-cycle plan — skip the chaining in steps 2–3 and validate that one clip.) For an evolving scene, write a beat sheet that covers the whole duration, one job per beat at the largest legal `frame_count` the selected route and canvas allow (multiples of four for PixMiniMax; even 4–16 for v3, subject to v3's pixel budget), before any paid call. Frame math (chained/evolving scenes): an N-frame job plays at 100 ms ≈ `N × 0.1` s (1.6 s at 16 frames, 0.8 s at 256px's 8), and chained jobs share their handoff frame, so a T-second cinematic needs roughly `T ÷ (N × 0.1)` jobs — a 256px canvas therefore doubles the v3 job count and cost versus 128px, while PixMiniMax's route-specific generation cost must be read from its published examples or returned usage. If that job count exceeds the budget, cover the arc in fewer keyframes played at a slower per-frame delay (a deliberate slow dissolve) rather than overspending — a one-way scene sells its transformation on staging, not frame rate. Each beat names: the subject and its state at the incoming frame, any objects and their positions, the intended motion for the next frames, and what must not appear. Present the beat list, the job count, and an estimated cost, and confirm it fits the budget before mass-running.
2. **Calibrate.** Run one job first, read its `usage`, and recompute how many jobs the remaining budget affords. Enforce a hard stop at the budget: if the next job would exceed it, stop and report where the cinematic stands.
3. **Chain.** Job 1's `first_frame` is the user's start frame (or a generated opening). Each later job's `first_frame` is the previous job's **handoff frame** — the latest frame that still preserves continuity (for example, the latest frame that still clearly contains a moving secondary object; objects tend to fade in a job's final frames). Each job returns one more image than `frame_count`, with image 0 intended as the echoed incoming frame (see `animation.md`). Verify that echo using `animation.md`'s alpha-aware rule: keep job 1's first image as the opening, and drop a later job's image 0 when it is exact or differs only in invisible RGB values stored in fully transparent pixels. If size, transparency, or visible content differs materially, treat that as a seam failure and validate or retry the job instead of silently choosing one version. Dropping verified duplicates — and, at a loop close, a final frame identical to frame 0 — is expected de-duplication for a clean stitch, not the ping-pong/reverse/trim playback manipulation SKILL.md forbids; keep the raw returned frames alongside for integrity. Author each beat's motion prompt after seeing the previous job's actual output, since the incoming state is whatever the model produced.
4. **Write each motion prompt** in the selected route's field (`action` for v3, `description` for PixMiniMax; limits in `prompt-limits.md`) as a concise identity anchor for the subject, any objects, the incoming frame's state, the intended motion over the next frames, and an explicit exclusion of anything that must not appear. Anchor identity to the **reference frame's actual appearance**, not to a copied stored prompt, which can contradict what was drawn; confirm ambiguous traits with the user. Motion is what the endpoint acts on — protect it over description length.
5. **Validate every job before continuing.** Run `animation.md`'s verification list, then additionally confirm the scene's constraints — required objects present, forbidden ones absent — and inspect the frames visually. **Confirm the rendered motion is the *intended action* — the right subject doing the intended thing in the intended manner — not merely that something moved; re-roll a beat whose motion reads as the wrong action, the wrong actor leading, or a dropped or mischaracterised gesture** (author for the intended read per the staging rule under Continuity). If a job is below confidence, re-roll it, tightening the wording at the specific failure, before taking its handoff. Re-rolls spend budget. Once a shot validates, post its saved output (path + inline preview) as it lands, per SKILL.md step 12's chunk reveal.
6. **Close the loop** (if looping): steer the last beats back toward the opening state, then have the final job set `last_frame` to the frame you display first so the end matches the start. Interpolation loads big corrections into the final frames, so a smaller correction there looks better; read `animation.md` for `last_frame` behavior and risks.

## Continuity and quality rules

These are generic and situational — apply the ones the scene needs, not a fixed style:

- Never depict an off-screen actor. Describe an object's own physics (it flies in, bounces, rolls off an edge) instead of a person acting on it, and forbid unwanted people, hands, or props when the scene should not contain them.
- Prefer distinct on-surface or free object states over tiny objects held against the subject, which can merge with the silhouette at small canvas sizes.
- Layer several small ambient motions on different beats (flicker, sway, drift, falling particles) rather than one — a scene with a single moving element reads as static; stagger them so they do not pulse in unison.
- Build depth with atmospheric perspective — distant elements lower in contrast and saturation, foreground crisp — and let the subject hold the brightest, most-saturated values so the eye lands on it, unless the composition wants the opposite (a backlit silhouette, a dark subject against a bright sky).
- Restate the subject's identity, scale, and framing in every beat; long chains drift in size and palette because each job re-renders from the last.
- **Recurring characters AND a recurring setting across shots need a visual anchor, not just words.** Text + seed will not hold an exact character design, nor the set (walls, floor, background layout, lighting, palette), across independent shot generations — worst in low-resolution pixel art, where sparse wording lets the model invent a different figure and a different room every time. Lock one **master reference** on-model first, then produce every other shot by **conditioning on it**, never by independent text-only generation. Tested routes for a flat-pixel cast, best first: **`edit-image` from the master** holds the flat look and identity best and is cheapest — use it for most shots (moderate re-pose / re-frame) at a stable palette (like any edit it will not cross a large palette shift — for that, seed-lock fresh generations instead). This "cheapest" finding is specific to REST base `edit-image`: MCP's `edit_image` is the Pro-tier `edit-images-v2` route and costs materially more per shot, so use REST directly for the cheap path in a budgeted cinematic chain. **MCP `create_image_pro` (REST `generate-image-v2`) with `reference_images`** reframes hardest (extreme wide, hard close-up) while keeping the cast recognisable, at Pro price and slightly less chunky — escalate to it only when an edit cannot reach the framing; **avoid `init_image`** (it clones the master composition and will not re-frame) and **`generate-with-style-v2`** (REST-only, no MCP tool — it re-renders in high detail and redesigns the cast, breaking a flat look). Chaining from a prior frame holds identity best of all where a cut is not needed. Keep each character's screen-side fixed, and **validate every shot against the master, re-rolling any character or background that drifts in colour, silhouette, scale, or layout.** Even anchored, exact consistency may not fully hold — keep backdrops simple and reusable rather than an elaborate set.
- **Every shot must land on the cinematic's exact canvas, edge-to-edge — never letterboxed or padded to fit an off-aspect result** (a baked border is barred unless the user explicitly asked for letterboxing, per `SKILL.md`). A reframe route can return a different size or aspect: `create_image_pro`/`generate-image-v2` with a `style_image_base64`/`style_image` forces a **square** output, and some routes have aspect-dependent maxima. Fitting that into the target frame leaves **baked white/matte padding** — a mixed-resolution, bordered cinematic, and a violation of the no-baked-background rule in `SKILL.md`. So request the exact canvas, use `reference_images` (not a style image) for a `create_image_pro`/`generate-image-v2` reframe, and if a frame still returns off-aspect, **normalise it before assembly — crop or nearest-neighbour-scale the content to fill the exact canvas, never pad it with a border.** Validate that every assembled frame is the identical `W×H` with no border.
- **Anchor an evolving scene on a cadence.** Define a distinct keyframe per stage and set `last_frame` to the next one on most beats; **never chain more than ~2–3 free-run jobs (no `last_frame`) in a row** — long free-run stretches drift and accumulate artifacts: spray or foam that keeps building into frozen white blobs, stray marks, and palette creep back toward earlier colours. The anchored beats are what read as a controlled evolution, so re-pass a stable keyframe every couple of jobs to pull error back.
- **Seed-lock the stage keyframes** (same seed + identical composition wording, changing only the palette/weather words) so the palette is free to shift; but know the limit — this holds the colour change, not the layout, so structure position and scale can still drift between keyframes and cause a zoom/pop at the tween. Keep every keyframe's framing wording identical and adjacent stages visually close. To hold the structure *and* still cross the palette, pin the opening as an `init_image` at **very low strength** (well below the default — check the OpenAPI scale): its **edges** survive while uniform regions like sky and water repaint to the target palette — but this only crosses when the held structure reads as a **backlit silhouette** (dark shapes against a bright sky), so word it that way. At normal or high strength the init instead anchors the keyframe to the **source** palette and won't cross. Then chain composition-matched intermediate keyframes so the shift rises monotonically without a pop. A recurring **cast** that must *also* cross a big palette shift is the awkward case — seed-lock fresh generations that restate the cast's identity rather than editing the master, and expect a looser identity hold, so validate it.
- **For v3, word an evolving beat's `action` as steady, rhythmic motion, not additive one-shot events** — free-run v3 keeps adding a described burst and never clears it, so "waves explode into white foam" or "spray bursts up" pile into frozen white blobs; say "waves roll and crash rhythmically" instead. A specific element that must trace a path (a lighthouse beam sweeping, a comet arcing) cannot be held by text across free-run frames — it flickers and collapses to a static shape; give it its own anchored keyframes (beam left, centre, right) or accept it will not follow a clean path. For an **action** beat, "steady" does not mean subtle: describe **bold, deliberate, large motion** — a wide arc across the frame, a lunge with weight transfer, clear follow-through — and chain progressive poses (wind-up → peak → settle) across anchored keyframes. The rule bans *accumulating* particle bursts ("explode", "spray"), not big body motion.
- **The endpoint animates literal motion, not intent — a beat's *meaning* must be staged, not stated.** A beat that turns on a choice or feeling (a refusal, despair, hesitation) will not read from a generic motion, and the wrong verbs render the wrong meaning ("arms spread wide" for a defeated release reads as a triumphant leap). Match the motion to the intended read, and for a loaded or ambiguous beat **name and forbid the wrong reading** in the selected route's motion field (e.g. "a passive let-go, NOT a dive"). A small but story-critical gesture (a glance, a head-shake, a reaching hand) vanishes under free-run animation — bake it into a **before→after keyframe pose pair**.
- Spread large orientation changes (such as a full turn) over two or more jobs rather than one.
- Read "face the camera" as "when looking at the viewer," not every frame: an energetic beat (a spin, a chase) may briefly turn the subject away, which is fine — do not re-roll a valid beat over a momentary turn.
- **Free-run v3 tends to hallucinate unrequested glow VFX — glowing orbs, sparkles, magic glints, lens flare, energy beams — onto bright, energetic, or impact beats** (a fire, a spark, a hard hit). When the scene does not call for them, forbid them explicitly in the `action` up front, not only when catching them in validation, and still watch for stray motion marks or artifacts near the subject when checking each job.

## Start and end frames (strict flow)

When a shot must land on an exact end state — or carry a big lighting, palette, or mood shift that free-run animation won't traverse (night→dawn, calm→storm) — drive it with a **`first_frame`+`last_frame` tween** using the selected raw route (`animate-with-text-v3` or `animate-pixminimax`; route mechanics live in `animation.md`), plus a short route-appropriate motion description (`action` for v3, `description` for PixMiniMax). Free-run `animate-with-text-v3` anchors hard to the incoming palette and will not cross a large colour change however the `action` is worded, so generate the target-state frame and anchor `last_frame` to it rather than burning free-run retries; do not assume that v3-specific behavior for PixMiniMax without evidence. Use it whenever a shot needs a distinct end state; do not generate an end anchor merely to loop an ordinary or low-motion clip — that follows `animation.md`'s idle-loop rules. Either anchor may be user-supplied or generated — generate a target end frame the same way as the opening. To hold the same subject at a **similar** palette, generate the end frame as an edit of the start; but for a **large** lighting/palette shift an edit will not cross it (it anchors to the source palette — see Continuity), so re-generate the end frame with the target-palette wording, seed-locked to the opening's composition (or, for a **backlit silhouette** only, init-pinned at very low strength for a tighter structural hold — see Continuity), rather than editing the start. Verify both endpoints landed; if a supplied anchor came back changed, report it — substituting the user's exact frame back in is a disclosed local composite, so keep the raw cut and get approval before calling it final (Asset Integrity in `SKILL.md`).

## Deliverables

Assemble the frames into one looping GIF — a chained/evolving cut plays at 100 ms/frame; a looped cycle uses the per-frame delay that fills the requested duration (see "Cyclic or evolving?") — plus a spritesheet and the individual frames, and write the blueprint and manifest; see `local-asset-assembly.md`, `blueprint.md`, and report per `usage-reporting.md`. Stitching and format conversion preserve pixels; speck removal, object compositing/interpolation, and loop-smoothing morphs alter content — treat them under Asset Integrity in `SKILL.md`, and offer the raw stitched-frames cut alongside any processed one.

# Cost Routing

Read this when the user says cheap, affordable, low-cost, budget, minimize credits, avoid Pro, or asks for a cost-driven Pro-vs-cheap comparison. For normal route selection, use `SKILL.md` and the matching asset reference; a Pro/new/v3 label alone does not require this file.

The rule: satisfy the asset intent with the lowest documented-cost route likely to work, then report the tradeoff. Do not silently upgrade to Pro. Cheap mode also changes retry behavior: a first approved generation is not permission for open-ended paid iteration — before each additional paid attempt (prompt tweak, rerun, extra candidate, Pro comparison, retry after failure, batch expansion, or switch to a paid edit route), ask and include the route, expected cost category, and cost already spent, unless the user approved a concrete budget or attempt count. Free/local work (polling, downloads, cropping, assembly, packaging, manifests, verification) never needs permission.

Label semantics (`Pro` expensive; `v3`/`new`/Pixen/PixFlux/BitForge cheap-family hints; `inpaint-v3` is Pro despite the suffix): see SKILL.md Model And Mode Terms. Route by the concrete endpoint, not the label. Pro Flash is a separate, unbenchmarked family with provisional pricing; read `pro-flash.md` before comparing it. Prompt enhancement (inline `enhance_prompt` or enhancer endpoints) costs extra (~0.05 generations); skip it when the user wants cheapest-possible output unless prompt-quality risk is high and you name the cost. PixMiniMax is a separate paid animation route, not a cheap-family synonym for v3.

## Current Cost Findings

Checked against official REST v2 OpenAPI and MCP docs on 2026-09-12:

- Character 8-direction standard mode: 1 generation. Character `pro` / `create-character-pro`: 20-40 generations depending on size.
- `create-character-v3`: `ceil(width * height * 8 / 65536)` generations when rotating a reference image; `1 + ceil(s * s * 8 / 65536)` from scratch (s = max dimension). Cost is size-driven — read the output size before estimating.
- `create_character_state` / `create-character-state`: 20-40 generations per call.
- Character template animation: 1 generation per direction. Pro animation: 20-40 per direction (160-320 for a full 8-direction Pro run). v3 custom animation is size-and-frame-scaled: `ceil(width * height * frame_count / 65536)` per direction (~1/dir at 96px or below, ~2 at 128px, ~4 at 160px, ~8 at 256px). v3 is the default custom family; prefer it for cheap custom animation.
- 1/8-direction object creation (MCP and REST): Pro Tools, 20-40 generations per call.
- Map objects (`create_map_object` / `POST /map-objects`): documented separately from object Pro Tools; cost is not labeled — report or measure it rather than assuming.
- `create-ui-asset` (MCP and REST): Pro, 20-40 generations.
- Pro-labeled REST summaries: `generate-image-v2`, `generate-with-style-v2`, `generate-ui-v2`, `image-to-pixelart-pro`, `edit-animation-v2`, `interpolation-v2`, `transfer-outfit-v2`, `inpaint-v3`, `edit-images-v2`, `generate-8-rotations-v2`. Treat as higher-cost even without exact counts. MCP `edit_image` and `inpaint_image` are these same Pro routes (`edit-images-v2`/`inpaint-v3`, confirmed by field-level schema match, not the base `edit-image`/`inpaint`) — treat them as Pro-cost even when called via MCP; MCP `create_image_pro` is likewise `generate-image-v2`.
- MCP `edit_image` / REST `edit-images-v2` are Pro: outputs up to 256px cost 20 generations, 257-314px cost 25, and 315-512px cost 40 per accepted call.
- Pro Flash's one-image creation endpoint documents a provisional five-generation charge, but its edit/inpaint prices and visual quality are untested here. Read `pro-flash.md` for the canonical stage, reuse, and live-estimate rules before comparing total costs; do not infer cheaper-than-Pro output from the name.
- Cheap edit and convert: `edit_image_pixen`/`edit-image-pixen` and `image_to_pixelart`/`image-to-pixelart` cost 1 generation. The cleanup family — `unzoom_image`, `correct_pixelart`, `reduce_colors` and their REST twins — costs 0.1 generations per call. `correct_pixelart` and `reduce_colors` take several same-size frames per call, so batch rather than loop; `unzoom_image` is one image per call.
- Tilesets cost more than one generation: MCP documents `create_topdown_tileset` standard mode at 1-4 generations (usually 3 or 4) and `create_sidescroller_tileset` at 2 or 3. Do not quote a tileset as a 1-generation route.
- Non-Pro-labeled image routes: MCP `create_image_pixen` and `create_image_pixflux` each cost 1 generation; their REST counterparts are `create-image-pixen` and `create-image-pixflux` (`-background` is a second URL for the identical PixFlux schema, same tier). `create-image-bitforge` is REST-only with no MCP tool. `animate-with-text-v3`/MCP `animate_image` (documented cost `ceil(width * height * frame_count / 65536)` generations) and `generate-8-rotations-v3` are the cheap v3 animation/rotation family.
- PixMiniMax (`POST /animate-pixminimax` / MCP `animate_image_pixminimax`) is priced by generation time. Current public examples are `32x32`/4 frames = 1 generation, `64x64`/4, 8, 16, and 40 frames = 2, 3, 5, and 12 generations, and `80x80`/8 frames = 2. The route accepts 4–40 generated frames in multiples of four at up to 256×256. Use returned `usage.generations` for the actual charge; website USD estimates are a separate reporting unit. Do not call or document the unversioned/private cost route mentioned in descriptive text.
- `frame_count` is a documented cost driver for both v3 and PixMiniMax, but their pricing rules differ. Use the v3 area formula only for v3; for PixMiniMax use the published examples or returned usage. Change documented cost drivers instead of guessing: route family, mode, direction count, candidate count, enhancement use, size, and frame count where the selected route documents it.
- Talking portraits: portrait attachment, talking GIF rendering, and lip-sync plans are free; `create_vocal_animation` / `POST /vocal-animation` is the only paid-plan generation step and has no exact published unit price in the reviewed docs. Generate one mood per approved call.
- Font generation has fixed current pricing: 25 subscription generations, or at least `$0.125` in credits. The former `image_size` pricing tier has been removed.

If exact current costs matter, refresh official docs or run a small balance-before/after test with explicit approval. Do not invent prices for routes whose docs only show a label.

## Cheap Route Preferences

| Asset | Cheap default | Use Pro only when |
|---|---|---|
| General images | `create-image-pixen`/`create_image_pixen` (small/single/icon iteration, outline/detail/view controls) or `create-image-pixflux`/`create_image_pixflux` (general/background style) | Style-reference generation or high-quality sheet output is required and approved |
| Icon sheets | Propose a non-Pro/Pixen comparison or a smaller test first; ask whether quality or savings wins | User approves the Pro sheet after the tradeoff is named |
| Characters | Standard mode or v3 | User accepts 20-40 generations for `pro`; use it when user instructions must be followed closely because Pixen/v3/new may underweight them |
| Character animation | Template mode when a template fits; else v3 custom; one direction first | User approves Pro cost |
| Objects | For standalone visuals that don't need managed object IDs: a general-image/Pixen/PixFlux or isometric-tile route, labeled as not creating a managed object; map-object route when a map object is specifically needed (measure cost) | User accepts Pro Tools 20-40 generations |
| Object animation | `mode='v3'` (documented default) | User explicitly approves Pro |
| UI | Non-Pro general-image route for loose UI images (explain weaker structure); `generate-ui-v2` only if its cost is acceptable | Structured `create_ui_asset`/`create-ui-asset` is required and approved |
| Image-to-pixel-art | `image-to-pixelart`/`image_to_pixelart` (1 generation) when the size fits its limits | Pro needed and approved |
| Edit | MCP `edit_image_pixen` (1 generation) when the source is ≤256px per side and the target area ≤256×256; otherwise base `edit-image` via REST. MCP `edit_image` is Pro-tier (`edit-images-v2`) | Larger canvas, multi-image batch, or reference-mode edit is required and Pro cost accepted |
| Inpaint | Base `inpaint` **via REST** — MCP's `inpaint_image` is Pro-tier only (`inpaint-v3`), so there is still no cheap MCP path for masked regeneration | Pro capabilities required and cost accepted, or MCP-first with no REST fallback available |
| Palette reduction, clean-up, unzoom | `reduce_colors`/`correct_pixelart`/`unzoom_image` or their REST twins, 0.1 generations — far cheaper than regenerating a bad frame | Never; there is no Pro variant |

When choosing a cheap route, name the tradeoff plainly (lower cost, possibly less candidate variety or weaker Pro-quality detail) and follow `usage-reporting.md` for cost reporting.

Pixen/v3/new may underweight user instructions and has isometric bias despite `view`/`direction`; prefer Pro when the user's instructions or static south-facing view matter and higher cost and different character style are acceptable.

# Create Image Pro

Read this for explicit Create Image Pro wording, MCP `create_image_pro`/REST `generate-image-v2`, exact grid or sheet requests, and small cell-size requests that are not already covered by `icon.md`.

Create Image Pro / MCP `create_image_pro` (+ `get_image`) / REST `generate-image-v2` is a general image-generation route. It can make attractive sprite sheets and texture sheets, but exact cell layout is prompt-guided rather than structurally guaranteed. A correct output canvas size is not proof that the image contains the requested cell grid. Style is prompt-guided too: there is no `detail`, `outline`, `shading`, `negative_description`, `color_image`, or `coverage_percentage` field; MCP accepts a preferred `style_image_url` or inline base64 plus `style_copy`, while REST has `style_image`+`style_options`. Route to `create_image_pixen`/`create-image-pixen`, `create_image_pixflux`/`create-image-pixflux`, or `create-image-bitforge` when another field must be enforced.

Prefer Pro when user instructions must be followed closely; it follows the user's description more closely than Pixen/v3/new, at higher cost and with a different character style.

MCP `create_image_pro` and REST `generate-image-v2` both remove the background by default (`no_background` defaults to `true`). Send `no_background: false` when the user wants an opaque, full-bleed image, scene, or sheet.

## Sub-32px Cell Requests

For exact grid/sheet/tile/icon/sprite requests with per-cell size below `32px`, treat Create Image Pro as prompt-sensitive rather than structurally guaranteed. Do not avoid it when the user asks for it; use prompt wording that makes the cell math, independence, and no-margin packing explicit, then verify the raw output honestly.

When the user explicitly asks for Create Image Pro with below-32px cells, do not push them to switch tools for that reason alone. Recommend a different route only when their real goal is a tile-specific asset (Wang/autotile terrain, isometric tiles, individual tile variants) or they need structural guarantees prompt-guided Create Image Pro cannot provide.

Use these alternatives only when they better match the user's actual intent:

- `create_tiles_pro` / REST `create-tiles-pro` for individual square, hex, octagon, or isometric tile variants, including small tile sizes.
- `create_topdown_tileset` / REST `create-tileset` for top-down Wang/autotile terrain transitions.
- `create_sidescroller_tileset` / REST `create-tileset-sidescroller` for platformer terrain.
- `create_isometric_tile` / REST `create-isometric-tile` for one isometric tile or block.

Do not call a Create Image Pro result a valid exact tile/icon/sprite grid based only on `image_size`. The output must pass visual cell-layout verification.

## Native-Size Multi-Output Batches

At small `image_size` values, `generate-image-v2` may return many same-prompt images. Native sizing enforces each returned file's dimensions; it does not assign a different requested concept to each output or guarantee semantic variety. Treat the results as candidates or variations unless the user explicitly requested a multi-asset set and delegated keeping all outputs; follow `reviewable-candidates.md` otherwise.

Variety requests (route-specific refinement of SKILL.md's "produce one candidate first"): when the user asks for a set, variety, or several `unique` small assets, run exactly one call. `generate-image-v2` at small sizes often returns dozens of distinct candidates from a single generation. Expand to further paid calls only when the first result's candidates are too few or too similar and the user approves the extra scope — or when the user explicitly approved a multi-call plan upfront per SKILL.md's batch-approval rule.

Prepare the description according to the requested set:

- One narrow composition such as `a health potion` yields variations of that composition, not variety—`unique` alone does not prevent near-identical motifs. For a varied set, name independent design axes such as silhouette, subject, material, palette, and detail, or say which dominant compositions must not repeat. Split into disjoint thematic calls only after one call's candidates prove too similar and the user approves.
- Do not assume a long catalog maps one-to-one onto returned images. Prefer smaller disjoint concept batches when coverage matters. If a named list is necessary, put `Unlabeled pictorial assets only; the names are semantic guidance and must never appear as visible text` before the list, then retain an applicable no-text clause after it. Long named catalogs can trigger captions or label-like marks even when `no text` appears only at the end.
- Make gameplay view explicit whenever it changes usability. For example, a top-down ground effect needs `top-down orthographic view looking straight down`, radial ground-plane debris, and negatives for horizon, side profile, ground baseline, or a vertical rising plume. Words such as `ground impact` or `plume rising` do not imply top-down view.

Before accepting or assembling a requested set, visually review every result for readable text or text-like marks, dominant-motif repetition, requested view, and recognizable subject differences. Exact pixel hashes prove only byte-level difference. Fail text-contaminated or wrong-view results rather than removing labels or rotating/repainting them locally; report when a batch contains variations instead of distinct concepts.

## Packed Sheet Prompt Recipe

Seams appear below roughly `26px` cells: one `256x256` request for a `16x16` grid of `16x16` cells showed visible seams around `25-26px` intervals despite the correct canvas size. Canvas math is not content layout — `image_size` sets only final dimensions, and `generate-image-v2` does not enforce cell boundaries. `grid`, `atlas`, `texture sheet`, and material lists tend to bleed continuous rows or multi-cell textures across cells; `contact sheet`/`separate thumbnails` improve independence but add gutters; asking PixelLab to draw guide lines bakes them into the asset.

Best observed prompt pattern for no-margin packed sheets:

- Frame the image as `256 packed independent block face texture files`, not a drawn grid or contact sheet.
- Say the image is `16 columns by 16 rows`, with each file occupying exactly one `16 by 16 pixel cell`.
- Say cells touch `edge-to-edge` with `zero pixels between cells`.
- Forbid `margins`, `gutters`, `padding`, `spacing`, `separator pixels`, `blank pixels`, `outlines`, `frames`, `guide lines`, and `drawn grid`.
- Say each cell is filled completely `edge-to-edge`, including edge and corner pixels.
- Forbid any detail continuing into neighboring cells: planks, grass edges, dirt or stone grain, ore veins, highlights, shadows, color bands, shapes, objects, horizontal/vertical strips, terrain rows, connected scenes, and wide textures.

## Verification

For exact grid outputs from Create Image Pro:

- Verify the original PixelLab output against both canvas size and visual cell layout.
- Check that visible boundaries, object centers, or tile extents actually follow the requested per-cell grid.
- For explicit cell sizes, derive the expected grid from the canvas and cell dimensions. Always inspect the first visible asset against its intended cell before accepting the result; fail if its type, scale, containment, or the observed grid differs from the request.
- Use local crop/split or boundary-measurement tools only for inspection or packaging, preserving original pixels. Do not add inspection grids to final assets, and do not ask PixelLab to draw inspection grids.
- If the original output has the right canvas size but the visible content uses a different grid, report the mismatch and do not present crops as repaired final assets.
- For sheets with cells below `32px`, use human visual review plus content-level measurement when possible.

# Credentials

Read this for PixelLab bearer-token handling, UI naming, and reusing MCP auth for Pip's REST v2 fallback. For where the Secret comes from and how to store it, follow SKILL.md's Auth And Execution and `setup.md`; this file adds the security rules and lookup order.

PixelLab uses one account-level bearer token for both public REST v2 and PixelLab MCP; store it in `PIXELLAB_SECRET`. Use one canonical env var — do not create aliases. Official examples may say `YOUR_API_TOKEN` or `YOUR_SECRET`; put that same token in `PIXELLAB_SECRET`.

Use it as:

```text
Authorization: Bearer <PIXELLAB_SECRET>
```

In previews, `<PIXELLAB_SECRET>` is a private local secret reference — never a cue to paste the real Secret into chat, a shared config file, or a generated doc.

## Token handling

- Never print, echo, log, summarize, measure, transform, validate, or reuse a token value from chat or config output. Never ask the user to paste it into chat. If a token appears in chat or tool output, do not repeat it; tell the user to treat it as exposed and replace it before continuing.
- Never put the token in an agent-run or assistant-shell command, including Claude Code or Codex CLI shell escapes and Codex-readable integrated-terminal commands. Even when the user's local shell runs the command from inside an assistant session, the command text may be visible to the session, saved in transcripts/logs, or kept in command history.
- A user-run command with a literal token is allowed only as an explicit manual fallback in a normal external terminal, after warning that the token may be stored in local config or shell history. Show placeholders only; never run it, never put the real token in generated text, and never ask the user to paste it into chat.
- `setx`, `export`, PowerShell `$env:`, and `ENV=value command` are not inherently forbidden — the risk is the literal Secret appearing in command text. Offer the user both ways to set the `PIXELLAB_SECRET` user variable and let them pick:
  - **Settings dialog (friendliest, keeps the Secret out of shell history).** On Windows: open Start, type `environment variables`, and click the top result — it may be called **Edit the system environment variables** or **Edit environment variables for your account**; both reach the same place. If it opens the **System Properties** window, click the **Environment Variables…** button on the **Advanced** tab. In the top **User variables** section (labeled with your username) click **New**, set the name to `PIXELLAB_SECRET` and the value to the Secret, then click **OK**, **OK**. A User variable needs no admin rights, even though that window mentions Administrator. macOS has no built-in environment-variable dialog, so on macOS/Linux use the command option below (or a secret manager such as macOS Keychain).
  - **One-line command.** On Windows, `setx PIXELLAB_SECRET "<paste-secret>"` in a normal external terminal (persists to the user environment). On macOS/Linux, add the line `export PIXELLAB_SECRET="<paste-secret>"` to your shell profile (`~/.zshrc` on macOS, `~/.bashrc` on Linux) and open a new terminal; a bare `export` typed into the current shell is session-only and reads as "not set" after restart (and a profile export reaches shell-launched apps, not Finder/Dock-launched ones — for a Dock-launched app, use its own secret settings or launch it from that terminal). The Secret is then stored in plaintext — command history for `setx`, the profile file for the export line — so never run it yourself and never fill in a real token.
  List secret UIs, secret stores, or hidden prompts first as the safest default. A newly set environment variable reaches only sessions launched afterward, so tell the user to fully close the app/assistant and start it again from a newly opened terminal window (not the one already open) before any readiness check — otherwise it verifies from a stale session and reports a false "not set".
- Never use website/Supabase/browser session tokens for REST or MCP; they are never the bearer token.

## MCP reuse

If PixelLab MCP is already configured, reuse its credential source when safe:

- MCP config using `PIXELLAB_SECRET`: Pip's REST v2 fallback can use the same env var.
- MCP config using an app secret setting or store named `PIXELLAB_SECRET`: tell the user to make that same source visible to the assistant/editor/app session where Pip runs.
- MCP config with a literal `Authorization: Bearer ...` value: do not extract, print, or copy it. It supports MCP-only auth but does not make the token available to Pip's REST v2 fallback; suggest moving it to env/secret config for MCP + API or API-only readiness.

## Where to look, and where not to

Inspect only the specific config paths the user names or approves after a token-free explanation. Do not scan broad home/auth/config directories, shell history, keychains, project trees, or existing `.env*` files — tool output can leak secrets. Do not recursively search for token/secret/auth/env names.

Before writing environment settings, keychain/secret-store entries, MCP app config, shell profiles, or loader-backed project-local secret files, follow `setup.md`: explain the destination, show a token-free preview or secret reference, and get explicit approval.

`.env`/`.env.local` do not auto-inject variables into Codex, Claude, Pip, MCP clients, terminals, or the OS; they work only when a specific helper, dotenv loader, or wrapper reads them. Do not present them as MCP-ready or Pip-ready by themselves. ClawHub `pixellab-ai` reads such a file only when its helper gets an explicit `--env-file` flag; Pip ships no loader at all, so copying the file pattern alone is not enough. Before writing `PIXELLAB_SECRET` to any project-local file, explain the loader or wrapper that will read it, show a token-free preview, and get approval. Inspect an existing `.env`/`.env.local` only to troubleshoot when the user names that exact file, approves inspection, and confirms the purpose; if unclear, ask first. Make it a targeted presence/format check, not a full-file read that loads the value into context. Never print or copy values from it.

Fallback order:

1. Assistant/editor/app secret settings, app secret store, or user-scoped OS environment variable named `PIXELLAB_SECRET`.
2. Hidden local prompt that writes user-scoped env/keychain config.
3. A project-local `.env`/`.env.local`, only when a specific loader or wrapper explicitly loads it — not a default MCP or Pip path.
4. Avoid existing `.env*` files, committed MCP config, generated docs, shell history, chat transcript, and copied browser session tokens. Do not read existing `.env*` files unless the user names the exact file, approves inspection, and confirms the purpose is troubleshooting.

# Editor-Only Utilities

Read this when the user wants an exact PixelLab editor utility that has no documented public REST v2 or MCP route. Map each request to the closest public route or a clearly labeled non-PixelLab local fallback; the routing boundary and the "do not invent `/v2/...` routes" rule are stated in SKILL.md.

Reduce colors, unzoom, and pixel correction are not here — they have public routes; see SKILL.md's cleanup row.

| User wording | Route | Warning |
|---|---|---|
| Canny, sketch-guided, pose-guided, depth/image-to-image | Visible website/editor/Aseprite flow for exact behavior; REST v2 only for approximate documented init/reference/skeleton workflows after explaining the difference. | No exact public REST v2/MCP Canny/Pose/Depth route was documented. Do not call internal editor operation URLs. |
| Reshape character proportions | Website/editor Reshape, or closest documented edit/character route after verifying docs. | Website docs have fixed-size expectations; no public REST v2/MCP reshape route was documented. |
| Single-image Try on garment/accessory | Website Try on for a composited experimental output. | REST `transfer-outfit-v2` is animation-frame outfit transfer, not the same single-image try-on output and not isolated paperdoll layers. |

If future official REST/MCP docs expose a matching public route, prefer the documented route and update this reference.

# Icon And Icon Sheet Generation

Use this reference for skill/ability/spell/action-bar/hotbar icons, inventory item/equipment/loot/pickup/consumable icons, and emojis, single or sheets, including transparent, no-border, and split-PNG requests.

## Route

Route by icon size first:

- **`16–31px` single icon → MCP `create_image_pixen`/`create-image-pixen` (the "new" / Pixen model); Pro is unreliable for a clean icon below `32px`.** Confirm the route before generating unless the user named the Pixen model (route only — cost-routing and batch-approval still apply). Recipe: `detail: low detail`, `outline: single color black outline`, `view` to suit the subject, `no_background: true`. Pixen returns one image per call, so one item per job. Optional: clamp the palette to ~16–32 colors (`aseprite-cli.md`). Never use `create-image-bitforge` for icons (no MCP equivalent either).
- **`16–31px` sheet or large set → assemble locally; never generate the sheet in one call.** No route honors sub-32px cell math; the sheet comes back with fewer, larger cells on its own grid, and the missing cells make it unrepairable locally. Pixen one-item-per-job then assemble locally (clean; N paid jobs, get batch approval per SKILL.md), or a guardrailed Pro `create_image_pro`/`generate-image-v2` batch (~64 candidates per job) then cull the muddy ones. State the tradeoff and let the user choose.
- **`32px+` icon or sheet → MCP `create_image_pro`/`generate-image-v2` (Pro).** Guardrail the prompt: bold single-color black outline, low detail, limited palette, no gradients/noise/stray pixels. On a cheap/budget request, read `cost-routing.md` and offer a Pixen comparison or smaller test first. Use `create_image_pixen`/`create-image-pixen` here when the user wants a cheap attempt, exact `detail`/`outline`/`view` controls, or fast iteration over variety; verify its output reads as the requested icon type.

Do not default to object generation (`create_1_direction_object` / `create-1-direction-object`), `create_tiles_pro`, `generate-ui-v2`, or `create-ui-asset` for icons. Object routes produced noisy/downscaled-looking icons with broken contours and weak 32px clarity in testing — avoid them for any icon request, even when the subject is a weapon, potion, or prop. Use UI routes only when the user asks for the slot, button, panel, frame, or container UI itself.

Background defaults differ by icon type:

- Skill/ability icons: backgrounded sheets (`no_background: false`) are the validated default — rich full-bleed painted cells. Transparent skill icons are a less-validated shape; use `no_background: true` only when clearly requested.
- Item/inventory icons: transparent (`no_background: true`) is the default — inventory icons usually need alpha.
- Emojis: transparent (`no_background: true`), like item icons.

If `no_background: true` was sent but the output kept a background, read `background-removal.md` and apply safe removal when it preserves the art.

## Canvas Sizing

For plural or complete sets, `32x32 icons` is the per-icon cell size, not the canvas:

- `8x8` / 64 icons at 32px each → `image_size: { "width": 256, "height": 256 }`.
- `4x4` / 16 icons at 32px each → `image_size: { "width": 128, "height": 128 }`.
- A `32x32` `image_size` fits only a single icon. At small sizes `generate-image-v2` may return a multi-candidate batch; read `create-image-pro.md` for native-size diversity, no-label, and view guidance, then present candidates and select after visual review.

Generate the sheet first, then verify the original output against the requested cell size. If symbols come out 64px-ish, the layout collapses, or gutters break the cell math, report a failed candidate — do not resize or reassemble it into a claimed final.

## Prompt Pattern

Preserve sheet language for complete sheets; do not rewrite the request as separate standalone images unless the user asks for separate generated files. Follow SKILL.md Text Preparation: content only, no operation language, no canvas size or transparency wording already carried by `image_size`/`no_background`.

Backgrounded skill-icon sheet starting point:

```text
Complete 8 by 8 sheet of 64 unique fantasy RPG skill icons for game UI, 8 columns and 8 rows, each cell a readable 32x32 icon, perfectly aligned edge-to-edge with no spacing, overlap, cropped icons, dividers, or drawn grid. Rich full-bleed illustrated miniature backgrounds behind clear centered pictorial symbols: flames, ice shards, lightning bolts, shields, daggers, arrows, skulls, leaves, spirits, portals, stars, wings, claws, masks, potions, celestial beams, and aura effects. No text, letters, words, numbers, labels, captions, handwriting, fake writing, runes, glyphs, or alphabet-like shapes. Varied abilities across elemental magic, weapon attacks, healing, protection, stealth, curses, nature, summoning, movement, utility, poison, holy, shadow, and dragon breath. No terrain tiles, inventory sheet, borders, frames, UI slots, rounded corners, watermark, or separating lines. Palette: sapphire blue, ember orange, moonlit violet, emerald green, gold highlights.
```

Transparent item-icon sheet starting point:

```text
Complete 8 by 8 sheet of 64 unique fantasy RPG inventory item icons, 8 columns and 8 rows, each cell a readable 32x32 item, perfectly aligned with no spacing, overlap, cropped items, dividers, or drawn grid. Pixel art with clear centered object silhouettes, crisp hard edges, low visual noise, limited palette, consistent high-fantasy inventory style. Include varied common RPG inventory categories: melee weapons, ranged weapons, shields, armor, helmets, jewelry, potions, scrolls, books, food, coins, gems, ores, herbs, monster parts, tools, keys, chests, bags, bombs, and arrows. No text, letters, words, numbers, labels, captions, fake writing, runes, glyphs, UI slots, buttons, borders, frames, rounded corners, watermark, terrain tiles, or decorative grid lines.
```

Adapt theme, subject list, and palette; keep the sheet-layout, per-cell-size, no-text, and no-border clauses.

For an action-focused ability, use one concrete visible pose instead of the `Pictorial symbols only` anchor when it communicates the mechanic better.

Anchors for known failure modes (use only the ones that apply): `Pictorial symbols only`; `rich full-bleed illustrated miniature background` / `Fully opaque, every pixel painted` (backgrounded only); `No borders, frames, UI slots, rounded corners, dividers, watermark`; `No black outlines around icon square edges`.

Avoid positive mentions of `rune`, `glyph`, `sigil`, `spellbook labels`, `UI slot`, `button`, `frame`, `border`, or `card` unless requested — they create text-like marks or slot styling. Use them only in negative clauses. For sheets, avoid `one icon per image` / `standalone icon` phrasing — it pushes isolated symbols on flat backgrounds.

Item-icon specifics:

- Prefer category coverage over an exact 64-item list for the first candidate; long exact lists over-constrain and produce noisier results. If exact coverage is required, run it as a follow-up candidate and compare.
- Do not over-prompt outline instructions unless the user asks for a specific outline style; spotty or broken contours are a failed candidate, not a prompt-patch target.

## Request Body

```json
{
  "description": "<optimized complete-sheet prompt>",
  "image_size": { "width": 256, "height": 256 },
  "no_background": false
}
```

MCP `create_image_pro`/`create_image_pixen` take flat `width`/`height` integers instead of a nested `image_size` object; same values, different shape.

Set `no_background: true` for item icons and requested-transparent skill icons.

## Verification

Internal pre-final checks (report only the constraints the user named, per `usage-reporting.md`):

- Output dimensions match the requested sheet size and divide exactly into the requested cells; `32px icons` means 32px per cell.
- Symbols/items fit the cell scale — no 64px-ish symbols, collapsed layouts, multi-object clusters in one cell, or gutters that change cell math.
- For explicit cell-size sheet requests, check the first visible icon/item against its intended cell before trusting automated crops: if the first item is already larger than the requested cell, the sheet fails even if the canvas size and crop hashes look plausible.
- Alpha matches the request: fully opaque for backgrounded sheets, clean transparency for `no_background: true` (after `background-removal.md` verification if removal was applied).
- No text-like marks, borders, frames, gutters, rounded corners, or slot styling unless requested. Metadata is not enough — a 1px opaque edge or a semantically unclear item passes structural checks while failing the art request; a human visual check is required for variety, readability at 32px, and recognizable semantics. For a request for unique items, inspect every cell for recognizable semantic duplication or an indistinguishable variant; do not report semantic uniqueness from pixel hashes alone.
- Item icons: crisp readable pixel art without mixels or smeared detail. Normal stair-stepped diagonals are fine; treat stepping as failure only when it harms 32px readability or shape clarity.
- Cropped cells pixel-hash-unique when uniqueness is required (does not prove semantic uniqueness).

On failure, report the failed candidate and ask how to proceed per SKILL.md Asset Integrity; safe background removal after `no_background: true` is the only default repair.

# Image Input Roles

Read this to classify image input roles when the user supplies attachments or file paths, or when an endpoint has `reference`, `style`, `concept`, `init`, `color`, mask, inpainting, or frame parameters.

Image input role is endpoint-specific. Do not map every supplied image to `reference_image`. Some inputs are references; others are edit targets, init/source images, masks, palettes, terrain style guides, or animation frame anchors. Classify the goal first, then pick the field.

When consistency matters, identify which input constrains identity, style, palette, source edit, or frames; if none is provided, note that results may vary across a batch.

When images are visible, inspect them and write task-relevant facts into the chosen natural-language parameter (`description`, `edit_description`, `action`, `style_description`), keeping observed facts separate from requested output changes.

For style-reference generation, also read `style-reference.md`.

## Unzoom Upscaled Sources First

Run supplied artwork through `POST /unzoom` (MCP `unzoom_image`, 0.1 generations) before any reference, style, init, or conversion image field — official docs name upscaled input as the most common cause of poor output. Skip it when the source is already at native pixel scale, and note it needs at least 256×256 to detect the grid at all. Its result is opaque, so follow with `remove-background` when the sprite must stay cut out.

## MCP Inline Image Transport

Large base64-only MCP inputs can be truncated by the client. When exact pixels matter and no URL field
exists, use the equivalent REST route; never silently shrink or quantize a user image.

## Goal Router

| User goal | Use this role | Meaning | Common fields/endpoints |
|---|---|---|---|
| "Use this as the subject" | Subject reference | The output should depict the same object, character, or subject, while text still guides details. | `reference_images` in MCP `create_image_pro` / REST `generate-image-v2` (up to 4 labelled entries on both — MCP entries accept a preferred `url` or inline base64 plus a `usage` note; REST uses an array with `usage_description`); `reference_image` in some character routes. |
| "Use this exact character" | Identity/character reference | Preserve the existing character identity and rotate, animate, or derive states from it. | MCP `create_character(mode="v3", reference_image_url=...)` (prefer the URL form — MCP clients truncate large inline base64) / REST `create-character-v3.reference_image`; `reference_image` with `method=rotate_character` in `create-character-pro` (REST-only — MCP `mode="pro"` rejects `reference_image_base64`); `directions` in 4/8-direction character routes (REST-only per-direction references — MCP `create_character` has only `n_directions`, no per-direction images). |
| "Turn this portrait into a character" | Portrait conversion input | The supplied bust/face portrait is the source image to convert into a full-body character sprite. | `image` in `portrait-character-pro` with `direction=portrait_to_character`; MCP `create_portrait_character.image_url` (preferred — clients can alter or truncate inline base64) or `image` when visible. |
| "Make a portrait from this character" | Character conversion input | The supplied full-body character sprite is the source image to convert into a bust portrait. | `image` in `portrait-character-pro` with `direction=character_to_portrait`; MCP `create_portrait_character.image_url` (preferred) or `image` when visible. |
| "Make this portrait talk" | Vocal portrait input | Generate mouth shapes from a portrait, either statelessly or stored on a managed character. | Raw portrait `portrait` in REST `vocal-animation` / `image` in MCP `create_vocal_animation`, or attach it first with `POST /characters/{id}/portrait` / `set_character_portrait`. |
| "Make it look like this" | Style reference | Copy visual style, pixel size, palette feel, rendering, or tile shape, not the exact subject identity. | MCP `create_image_pro.style_image_url` (preferred) or `style_image_base64`, plus `style_copy`; REST `generate-image-v2.style_image`+`style_options`; `style_images`; `reference_image` in `create-character-pro` style methods; managed `style_character_id` / `style_object_id` when a completed 8-direction asset should supply style and scale. |
| "Use this rough design" | Concept image | Use the image as a design idea or sketch; text can reinterpret it. | `concept_image` in `generate-ui-v2`; `concept_image` with `method=create_from_concept` in `create-character-pro`. |
| "Use this UI style" | UI style reference | Copy visual styling for a structured UI asset, not necessarily the layout. Only the art style is copied — never the reference's content or layout. | `style_image` in `create-ui-asset` or MCP `create_ui_asset.style_image_base64`; if the user needs layout guidance instead, use `concept_image` in `generate-ui-v2` or shape `pieces`/`elements` in `create-ui-asset`. |
| "Start from this and transform it" | Init/source image | The supplied image is the starting state to modify, not merely inspiration. | MCP `create_image_pixflux.init_image_url` (preferred) or `init_image_base64`, plus `init_image_strength`; REST `init_image` in `create-image-pixflux`; REST-only `init_image` in BitForge and map-object routes (MCP `create_map_object` uses `background_image`+`inpainting` instead, not an init image). |
| "Edit/convert this image" | Target image | This is the image being edited, converted, resized, pixelated, or inpainted. | `image` in `edit-image`, `edit-image-pixen`, `image-to-pixelart`, `image-to-pixelart-pro`; `edit_images` in `edit-images-v2`; `inpainting_image` for BitForge/inpaint targets; pair with `mask_image` only when the user supplies an edit-area mask. MCP prefers `image_urls` / `reference_image_url` in `edit_image`, `image_url` in `edit_image_pixen` and `image_to_pixelart`, and `image_url` / `mask_image_url` in `inpaint_image`; the corresponding base64 fields remain alternatives. |
| "Add an effect/trail/aura to this sprite" | Target image | The supplied image is the canvas to preserve and augment. Add the requested VFX to the existing sprite/image rather than generating a separate object, unless the user explicitly asks for a reusable layer or isolated effect asset. | `image` in `edit-image`; `edit_images` in `edit-images-v2` for multi-image edits; MCP `edit_image.image_urls` (preferred) or `images_base64`. |
| "Match these colors" | Palette reference | Extract or force colors from the supplied image/palette, not its subject. | `color_image`, `color_palette`; MCP `create_image_pixflux.color_image_url` (preferred) or `color_image_base64`. |
| "Animate from/to these frames" | Frame reference | The image is an animation boundary or motion anchor. | `first_frame`, `last_frame`, character south frame for animation prompt enhancement. MCP prefers `first_frame_url`/`last_frame_url`; inline base64 remains available. |
| "Match this terrain/tile" | Terrain/tile style reference | Copy style/material/shape for a terrain layer, transition, or tile variant. | `style_images` in MCP `create_tiles_pro` / REST `create-tiles-pro` (also `style_images` on `create_1_direction_object`, `style_image_base64` on `create_8_direction_object`); `lower_reference_image`, `upper_reference_image`, `transition_reference_image` are REST-only tileset fields — MCP tileset tools take only `lower_base_tile_id`/`upper_base_tile_id`. |

## Endpoint Semantics

These are REST v2 routes; MCP `edit_image`/`inpaint_image`/`animate_image`/`animate_image_pixminimax` cover the same edit/inpaint/animate roles directly (fields noted above) and need no managed asset — do not route supplied-image edits to *managed* MCP tools (`create_*_state`) just because MCP is configured; those regenerate a managed asset, not an in-place edit. PixMiniMax-specific frame and prompt rules live in `animation.md`. Only counter-intuitive or collision-prone fields are listed; where the field name plainly matches the role (`remove-background.image` = target, `resize.reference_image` = image to resize, `edit-image.image` = edit target), take it at face value.

- `create-character-v3`
  - `reference_image`: south-facing character to rotate into 8 directions (else generates from text); `outline` and `detail` are ignored when it is set.
- `create-character-pro` (image role depends on `method`)
  - `method=create_with_style`: `reference_image` is a style reference.
  - `method=create_from_concept`: `concept_image` seeds the design; `reference_image` adds style guidance.
  - `method=rotate_character`: `reference_image` is the existing character to rotate.
- 4/8-direction character routes
  - `directions`: per-direction reference images (provided used as-is, missing generated); bipedal templates require south if any are provided, quadrupeds require south and east.
- `portrait-character-pro`
  - `image` is the source to convert, not a style reference.
  - `direction=portrait_to_character`: source must be a bust portrait; output is a full-body sprite. Use `view` and `result_size` to control the sprite.
  - `direction=character_to_portrait`: source must be a full-body sprite; output is a bust portrait.
- `create-tiles-pro`
  - `style_images`: reference tiles. When provided, style tiles define style and dimensions; tile shape/size/view inputs are ignored.
- `edit-images-v2`
  - `edit_images`: targets to edit.
  - `reference_image`: used only with `method=edit_with_reference`, never with `method=edit_with_text`. No mask input or layer output is documented.
- `image-to-pixelart` / `image-to-pixelart-pro`
  - `image`: target to convert, not a style reference.
  - Base route sizes: input `image_size` up to 2048×2048, output `output_size` up to 512×512. `fixer` (MCP `faithful`) keeps the source rather than reinterpreting it — pair it with `init_image_strength` 100-300. Above roughly 300 the model stops transforming and hands back the source instead of pixel art, so do not raise it further to be "more faithful".
  - Treat "same size", "exact size", "exact resolution", and similar as a fixed output-size request; inspect the input dimensions when the size is implied.
  - No fixed size requested: prefer `image-to-pixelart-pro`. Fixed size within `image-to-pixelart` `output_size` limits: use normal `image-to-pixelart`.
  - Fixed size outside those limits: warn that Pro cannot guarantee exact dimensions before spending credits; if the user proceeds, use Pro, verify dimensions, then ask before PixelLab `resize` or local resize/pad/crop.

For animation frame anchors (`first_frame`, `last_frame`) and idle-loop risk, see `animation.md`.

For explicit Pro Flash work, read `pro-flash.md`: an owned `source_image_id` or supplied south-facing first frame anchors character/object rotations; `style_image` guides appearance, while `edit_image_pro_flash`/`inpaint_image_pro_flash` take a target image or MCP-owned source ID. The inpaint mask is a separate same-size black/white image, not a style reference.

Exact-mask edits: avoid MCP `inpaint_image` and REST `inpaint-v3` until fixed; live tests changed
pixels outside the mask or ignored the masked region. For other inpainting, verify both regions and
report failures without retrying or repairing silently.

## Clarify When Ambiguous

Infer roles from explicit wording for low-risk setup. Before a credit-spending call, ask one short question when a file could serve more than one role and the choice would change the endpoint, field, or output — never guess between identity, style, concept, edit target, mask, palette, and frame:

- "Should this image define the exact subject/character, only the style, or just the color palette?"
- "Is this the image to edit, or a reference for what the edit should look like?"
- "For this character image, should PixelLab rotate this exact character, use it as a style guide, or treat it as concept art?"
- "For this UI image, should it guide the layout/concept, visual style, or only the color palette?"
- "For animation, is this the first frame, last frame, or a style/reference image?"

# Job Lifecycle

Read this for live PixelLab calls that return a job, asset ID, managed MCP asset, pending status, review status, rate-limit response, or download URL.

## Polling

REST v2 async jobs normally use `GET /background-jobs/{job_id}` when the create response returns a background job ID. Vocal animation is the explicit exception: poll `GET /vocal-animation/{job_id}`. MCP managed assets use the matching `get_*` tool, not REST background-job polling.

MCP tilesets (`create_topdown_tileset` → `get_topdown_tileset`) have no such 423/404 window — the getter reports progress directly. For REST `POST /v2/tilesets`, the create response can contain both `background_job_id` and `tileset_id` while the status is still `processing`. Poll `GET /background-jobs/{background_job_id}` first. `GET /tilesets/{tileset_id}` may return `423` while the tileset is still being generated, or `404` until the background job has completed and the tileset object has been persisted; treat those as early lifecycle lookups while the background job is still processing.

Poll gently: a short initial delay, then back off — not tight loops. A paid async result is already bought, so do not stop while it is merely still running — follow SKILL.md step 12's poll → background-wait → handoff ladder. Stop before "done" only for a real blocker: failure, auth/credit error, or a needed user choice such as review selection.

Any wait that runs outside the current turn — a backgrounded poll loop, a log/file watcher, a scheduled wake — must be bounded to return control on success, failure or terminal error, and a hard deadline, never on success alone, and must emit a terminal marker on every path so the harness can always wake you. A background `until <success>; do sleep; done` loop (or a `tail -f … | grep <success>` watcher) never exits when the job fails or stalls, so nothing ever wakes you. On resuming from any wait, re-fetch actual status with the status route or getter before acting — the wait ending is not proof of success — and if the deadline passed with the job still pending, do not wait again: fall back to reporting the ID and resume route above.

Do not resubmit a paid job because a poll timed out or a `423`/`404`/`review`/stale-URL lookup came back — poll again or re-fetch with the matching getter instead.

Detect completion by the result, not by matching a status word: `status` is a free-form string whose in-progress vocabulary is open and endpoint-specific (`processing`, `pending`, `running`, `finalizing`, … — not a fixed set), and the tileset family carries no `status` field at all. Check in this order:

- **Done** — the result payload is present: the asset/image/download/rotation URL is populated (e.g. a character's `rotation_urls` is null until done), or a tileset-family getter returns HTTP 200 (see the 423/404 note above). Verify the URL or local download.
- **Failed** — `status: "failed"` or HTTP 410 (permanent). Report it; do not retry paid work unless the user approves.
- **Review** — `status: "review"` (objects): selection is required; do not call it completed.
- **Otherwise keep polling** — any in-progress status word, HTTP 423/404, or a value you do not recognize — bounded by a deadline (below). Never treat "the status isn't a word I listed" as done.

## MCP Managed Assets

MCP creation tools return asset IDs quickly. Use the matching getter to inspect status, previews, downloads, and results:

- Characters: `get_character`.
- Character animations: `get_character` or animation-specific tool output when available.
- Objects: `get_object`.
- Map objects: `get_map_object`.
- Fonts: `get_font`.
- Portrait-character conversions: `get_portrait_character`.
- Vocal animations: `get_vocal_animation`; partial visemes may appear before completion, so wait for the terminal result.
- Raw-image jobs (`create_image_pixflux`/`create_image_pixen`/`create_image_pro`, `edit_image`, `edit_image_pixen`, `inpaint_image`, `animate_image`, `animate_image_pixminimax`, `image_to_pixelart`, `unzoom_image`, `correct_pixelart`, `reduce_colors` — none need a managed asset): `get_image`, the one shared getter for the whole family. The newer Pro Flash image/edit/inpaint tools also return raw-image job IDs; use `get_image` when the connected getter accepts them, and check `pro-flash.md` for their route-specific rules. `unzoom_image` and `reduce_colors` finish in about a second — poll once instead of backing off.
- UI assets, tilesets, tiles, projects, or helpers: use the visible matching MCP getter when exposed.

State tools such as `create_character_state` and `create_object_state` auto-wait only briefly for the source asset to finish. If a state call fails because the source is still pending, poll the source with its getter first, then retry the state call only when the source is ready.

Animation tools such as `animate_character` and `animate_object` may expose `confirm_cost`. If the first call requests confirmation or refuses without it, report the cost gate and ask before retrying with confirmation. Do not guess that a failed confirmation gate means the animation endpoint is broken.

## Object Review State

PixelLab object generation can return `review` status when multiple candidate frames are produced. Credits may already be spent, but the object is not finalized.

When an object is in review:

- Report that it needs selection, not that it is stuck.
- For candidate display and user choice parsing, read `reviewable-candidates.md`.
- Use `select_object_frames` or REST `POST /objects/{object_id}/select-frames` only after the user chooses candidates or the request clearly authorized automatic selection.
- Use `dismiss_review` only when the user approves discarding the candidates.

## Expiring And Sensitive Outputs

MCP download URLs may be unauthenticated and should be treated as shareable but sensitive. If a URL is stale, call the matching getter again for a fresh result.

MCP map objects do not expire, but their download URLs can still go stale — persist needed files rather than relying on a URL.

## REST Error Handling

- `401`/`403`: auth or permission problem. If auth worked earlier in the same session, say it may be expired, rotated, or unavailable to the current process; point back to bearer-token setup and never ask for the token in chat.
- `402`: credits or billing issue. Stop paid work and tell the user PixelLab rejected the operation.
- `400`/`422`: request validation problem. Summarize the field/error, fix the payload, and retry only if the corrected request preserves user intent.
- `409`/`423`: conflict, duplicate, or locked/in-progress state. Inspect the job or asset status before retrying.
- `429`/`529`: rate or overload response. Honor a `Retry-After` header when visible; otherwise wait/back off. Do not immediate-loop or fan out more paid calls.
- Concurrency: an account runs a limited number of jobs in parallel, varying by tier and not published. Dispatch an approved batch up to that limit — full parallelism finishes fastest; back off only on `429`/`529`. Never throttle or inflate paid work to game scheduling, and do not assume a slot number or invent a slots route. For what is currently running, see `mcp-platform-tools.md`.

# Local Asset Assembly

Read this for atlas or spritesheet grid inspection previews and when creating local preview or assembled artifacts from PixelLab-generated frames.

For Aseprite-specific opening, import/export, layers, frames, tags, `.aseprite` workspace creation, or Aseprite CLI/Lua behavior, read `aseprite-cli.md` instead.

Local assembly only assembles, previews, format-converts, or verifies existing PixelLab-generated or user-supplied pixels — it never creates or alters requested art. Preserve frame order, write outputs to the run's `pixellab-pip-generations/` tree, and record manifest fields per `usage-reporting.md` (SKILL.md holds the asset-integrity, frame-order, and output-folder rules).

## Atlas And Spritesheet Grid Inspection

For every atlas or spritesheet request with known or requested cell dimensions, create a separate, clearly labeled inspection preview showing the expected cell grid. Keep the preview separate from final deliverables, never bake it into the requested asset, and never treat a correctly drawn grid as proof that the underlying content follows it.

When the cell size is known, derive the expected column and row counts from the actual canvas dimensions. Require each canvas dimension to divide evenly by its corresponding cell dimension; if either does not, report the mismatch rather than rounding or drawing a misleading grid.

Create the required inspection preview as a copy with a contrasting one-pixel grid overlay at every cell boundary. Use local tooling such as ImageMagick only on the preview copy; do not alter the source or final deliverable. Name it explicitly, for example `<name>-inspection-grid.png`, and label it `Inspection aid — expected grid overlay` wherever it is shown or reported.

For a canvas `W` by `H` and cells `CW` by `CH`, draw vertical lines at `x = CW, 2*CW, ... < W` and horizontal lines at `y = CH, 2*CH, ... < H`. Keep the overlay visually legible without obscuring cell-scale content; a contrasting color or two-tone line may be used on the inspection copy.

Inspect the underlying art against the overlay for scale, containment, boundaries, and alignment. The overlay visualizes the requested geometry only: its presence and correct arithmetic do not prove that the generated content follows that layout. Validate the original asset independently and report any mismatch.

## GIF Previews

Loop every preview GIF by default (`-loop 0`), even a one-way or non-seamless clip; set play-once only if the user asks.

Transparent pixel art GIFs are disposal-sensitive: if each frame does not say how the previous frame should be cleared, some viewers accumulate old transparent-frame pixels and show trails.

When using ImageMagick `magick`, put animation settings before the input frames so they apply to every frame:

```powershell
magick -delay 12 -dispose Previous -loop 0 "frame-*.png" "preview.gif"
```

Use `-dispose Previous` by default for transparent sprite previews. Use `-dispose Background` only after verifying the rendered output does not leave trails.

Avoid this anti-pattern:

```powershell
magick "frame-*.png" -delay 12 -dispose Background -loop 0 "preview.gif"
```

Putting `-delay`, `-dispose`, or `-loop` only after the input frames can produce frames with `Dispose: Undefined`, which is exactly the condition that causes past frames to remain visible in transparent GIF previews.

## Verification

Before reporting a GIF preview as complete:

1. Inspect metadata and confirm each frame has the intended delay and a non-undefined disposal method.

   ```powershell
   magick identify -verbose "preview.gif"
   ```

2. Coalesce the GIF back into rendered frames.

   ```powershell
   New-Item -ItemType Directory -Force "check-frames" | Out-Null
   magick "preview.gif" -coalesce "check-frames/check-%04d.png"
   ```

3. Compare every coalesced frame to the matching source PNG frame by sorted order. Unexpected nonzero differences mean the preview is not faithfully rendering the source frames.

   ```powershell
   $sourceFrames = @(Get-ChildItem "frame-*.png" | Sort-Object Name)
   $checkFrames = @(Get-ChildItem "check-frames/check-*.png" | Sort-Object Name)
   if ($sourceFrames.Count -ne $checkFrames.Count) { throw "Frame count mismatch" }
   for ($i = 0; $i -lt $sourceFrames.Count; $i++) {
     magick compare -metric AE $sourceFrames[$i].FullName $checkFrames[$i].FullName null:
   }
   ```

If the preview is only for chat display, still run the verification. A preview that looks wrong can make a good PixelLab generation look broken.

# Localization

Read this when the user writes in a non-English language, mixes languages, or asks for output in a specific language.

PixelLab natural-language parameters should be English unless SKILL.md preserves exact field text. Preserve the user's original wording, show the exact English transformation, and obtain approval before the first external call; combine this with the cost gate when one is required, and treat the approval as covering the same job unless a later transformation changes its meaning. Answer the user in their language unless they ask for another language.

## Before PixelLab Actions

- Detect the user's response language from the current request and recent conversation. If response-language confidence is low but the asset/action is clear, proceed in the dominant or most recent user language instead of interrupting.
- Prepare concise English candidates for PixelLab-facing natural-language fields (`description`, `*_description`, `action`, `item_descriptions`, visual `text`, `color_palette`) unless SKILL.md preserves exact field text. Before sending them, show the original and exact transformed values and ask for approval in the user's language. Preserve `/talking-gif.text`, `/lip-sync.text`, and MCP `text_to_speak` verbatim as dialogue; PixelLab documents Latin-alphabet dialogue support, so ask for user-approved transliteration rather than silently translating unsupported scripts.
- Keep non-language values unchanged: file paths, URLs, IDs, endpoint names, tool names, enum values, dimensions, seeds, colors, code identifiers, and bearer-token variable names.
- Preserve exact quoted names or requested on-image text inside otherwise English parameter values. Otherwise translate descriptive wording into English, except exact field text preserved by SKILL.md.
- For mixed-language requests, preserve technical terms, translate descriptive wording, and ask only when language mixing or culture-specific context creates multiple plausible asset meanings, response-language choices, or credit-spending actions.
- If an ambiguity affects the generated asset, edit target, on-image text, or selected PixelLab surface/tool, ask one short clarification in the user's language before spending credits.

## User-Facing Responses

- These responses override any fixed English wording a template or reference supplies, such as the cost-approval gate and auto-on reminder (`references/auto.md`), the `Auto is on.`/`Bark is on.` confirmations, the candidate-selection prompt (`references/reviewable-candidates.md`), and the final usage report (`references/usage-reporting.md`). Render their visible prose and labels in the user's language, keeping each template's structure and order. Keep literal the non-language values listed above, plus any command or reply keyword the user types verbatim (e.g. `/pixellab-pip auto`, `all`, `dismiss`).
- Ask clarifying questions, confirmations, refusals, and follow-up explanations in the user's language.
- When confirming or reporting a live call, show the values sent to PixelLab under the privacy/redaction rule in `usage-reporting.md`. When a non-redacted human-readable value (`description`, `action`, and the like) is not already in the user's language, add its translation on the next line so they can both verify and understand it; never translate redacted content or duplicate a line already in their language.
- If PixelLab returns English-only errors or field names, keep the exact technical term and summarize the problem in the user's language.

# MCP Platform Tools

Use this reference for PixelLab MCP tools that operate on projects, sandboxes, deployed agents, chat conversations, help, or feedback rather than direct asset generation.

Official MCP docs currently expose platform helpers such as `list_projects`, `add_to_project`, `chat_*`, `sandbox_*`, `agent_help`, `agent_feedback`, `agent_list`, `agent_inspect`, `agent_talk`, `search_knowledge`, `list_jobs`, and `cancel_job`. These are public MCP tools, not REST v2 endpoints.

## Safety Rules

- Use `agent_help` freely for PixelLab MCP usage questions, because it asks PixelLab's knowledge agent for documentation help. `search_knowledge` is the same kind of free read against a Phaser/game-dev knowledge base — use it only for that subject, not as a general search.
- `list_jobs` is a free read of your active background jobs; use it when a job ID was lost or the user asks what is still running.
- `cancel_job` is destructive: the result is lost and refund behavior is undocumented, so assume the spend is not recovered. Ask before cancelling, naming the job and what it was producing.
- Use `agent_feedback` only when the user wants to report feedback or after you have a concise, non-secret issue report. Do not include bearer tokens, private prompts, raw files, account data, or unrelated local paths.
- Treat `list_projects`, `chat_list_conversations`, `chat_get_messages`, `agent_list`, and `agent_inspect` as account or project data reads. Ask for approval before reading them unless the user directly asked for that exact information.
- Treat `chat_send_message`, `agent_talk`, `add_to_project`, `sandbox_create_session`, `sandbox_bash`, `sandbox_run`, `sandbox_write`, `sandbox_edit`, `sandbox_sync`, `sandbox_read_image`, and `sandbox_destroy_session` as state-changing or potentially sensitive actions. Get explicit approval for the specific target and action before calling them. `sandbox_write` defaults to `force: true` and overwrites silently — read the path first when the file may already exist.
- For `sandbox_destroy_session`, `sandbox_deploy_worker`, `sandbox_undeploy`, `sandbox_playtest`, destructive deletes, git syncs, or any command that may publish, overwrite, delete, or spend credits, clearly name the target and consequence before asking for approval. `sandbox_deploy_worker` and `sandbox_undeploy` are outward-facing publish/delete actions — name the project and branch when asking.
- Do not use PixelLab sandbox tools to bypass the user's local repository, approval, or secret-handling rules. If a task is ordinary local coding work, use the local workspace unless the user explicitly requests a PixelLab sandbox.
- Do not paste secrets, raw environment dumps, private traces, full chat transcripts, or full agent traces into reports. Summarize only the minimum needed to answer or debug the user's request.

## Reporting

Report the MCP tool used, the project/session/conversation/agent identifier only when needed for follow-up, whether the action was read-only or state-changing, and any next step that needs user approval.

# Official PixelLab Documentation

Read this when a needed endpoint, tool, field, price, limit, SDK detail, or exact request/response schema is missing or unclear in the skill. Official docs can change after this skill ships; prefer the skill for routing and refresh docs only for the gap. Refresh triggers and the URL shortlist are in SKILL.md (Current Docs Refresh) — this file adds the annotated link table and the surface boundaries below.

## Links

| Link | Use for | Limits |
|---|---|---|
| `https://www.pixellab.ai/docs` | Human API guides and conceptual docs. | Not a complete machine-readable schema. |
| `https://api.pixellab.ai/v2/docs` | Interactive REST v2 API docs. | Good for exact endpoint parameters; less useful for high-level agent routing. |
| `https://api.pixellab.ai/v2/redoc` | REST v2 ReDoc reference pages linked from `llms.txt`. | Browseable operation docs; still use OpenAPI for machine-readable schemas. |
| `https://api.pixellab.ai/v2/llms.txt` | LLM-friendly REST v2 endpoint index and auth summary. | Curated index only; it intentionally points to OpenAPI/interactive docs for full endpoint parameters, enum values, and request/response shapes. |
| `https://api.pixellab.ai/v2/openapi.json` | Machine-readable REST v2 schema. | Requires parsing; current skill summarizes only stable routing. |
| `https://www.pixellab.ai/mcp` | Human Vibe Coding setup page for MCP clients. | Setup-oriented; its "Available Tools" list can be abbreviated and should not be treated as the full tool inventory. |
| `https://api.pixellab.ai/mcp` | Hosted MCP server URL. | This is a service endpoint, not documentation. Use through an MCP-capable client. |
| `https://api.pixellab.ai/mcp/docs` | LLM-readable MCP tool guide and authoritative public MCP tool inventory. | MCP tools are not REST endpoints; do not curl tool names. |
| `https://github.com/pixellab-code/pixellab-python` | Official Python SDK linked from `llms.txt`. | Check installed package/docs before assuming endpoint coverage. |
| `https://github.com/pixellab-code/pixellab-js` | Official JavaScript/TypeScript SDK linked from `llms.txt`. | Check installed package/docs before assuming endpoint coverage. |
| `https://github.com/pixellab-code/pixellab-mcp` | Official MCP server repository linked from `llms.txt`. | Hosted MCP tool availability can still vary by client/tool schema. |

## Authoritative MCP Inventory

- `https://api.pixellab.ai/mcp/docs` is the authoritative public MCP tool inventory. It explains available tools, non-blocking jobs, polling, downloads, and warns that MCP tools are not REST endpoints. Do not rely on the abbreviated "Available Tools" list at `https://www.pixellab.ai/mcp` to decide whether a current MCP tool exists.
- The MCP tool set can change between sessions as PixelLab ships server updates. A client's connected tool list can also lag a very recent server change until the client reconnects — if a documented tool is unexpectedly missing, do not conclude it was removed from a single stale check; note the discrepancy and prefer a fresh connection or `mcp/docs` before routing around it.
- An MCP-capable client may also expose `pixellab://docs/...` documentation resources (engine/framework guides such as Godot, Unity, Python, Wang tilesets, sidescroller tilesets, isometric tiles, and platform overview). Use those resources when visible; otherwise fall back to the public docs URLs above.
- The current MCP guide lists separate Pro Flash image, character, object, edit, inpaint, and capability tools. The REST OpenAPI confirms matching operation paths plus a REST-only provisional cost estimator. Read `pro-flash.md` for routing and inputs. Do not use the guide's copied `create_character` examples under `create_character_pro_flash` or its contradictory four-direction hint; check the live tool schema and REST OpenAPI instead.

## Prompt Enhancement Pricing

`enhance-pixen-prompt`, `enhance-character-v3-prompt`, and `enhance-animation-v3-prompt` are public REST v2. The animation enhancer accepts `engine="v3"` or `engine="pixminimax"`; the PixMiniMax inline option is also exposed on `POST /animate-pixminimax`. A live check on 2026-06-25 returned `usage.generations: 0.05` with a matching balance delta for `enhance-pixen-prompt` — treat prompt enhancement as low-cost prompt prep, not a generation job. These are not root website/editor endpoints. Ask first for bulk or unusually cost-sensitive enhancement, and honor opt-out.

## Boundaries Beyond The Intent Router

SKILL.md's Intent Router already states MCP-vs-REST routing per asset type. These are the extra facts it does not:

- Beyond managed assets, MCP documents raw-image primitives needing no managed asset: `create_image_pixflux`/`create_image_pixen`/`create_image_pro` (+ `get_image` as their shared getter, matching REST `create-image-pixflux`/`create-image-pixen`/`generate-image-v2` on core fields — REST PixFlux additionally exposes deprecated `negative_description` and `background_removal_task`, REST Pixen exposes `enhance_prompt`, and Pro exposes no negative field; `create_image_pixflux` also covers `create-image-pixflux-background`, a byte-identical schema), `edit_image` (**Pro tier** — matches `edit-images-v2`, not base `edit-image`, which has `color_image`/`text_guidance_scale` that `edit_image` lacks), `inpaint_image` (**Pro tier** — matches `inpaint-v3`, which has `crop_to_mask` unique to v3, not base `inpaint`, whose extra weak-guidance controls `inpaint_image` can't reach: `direction`/`isometric`/`shading`/`outline`/`detail`/`text_guidance_scale`/`init_image`/`color_image`/`negative_description`), `animate_image` (matches `animate-with-text-v3`, partially `interpolation-v2` via `last_frame_base64`), `animate_image_pixminimax` (matches `animate-pixminimax`, a raw PixMiniMax/MiniMax H3 animation route), `edit_image_pixen` (matches `edit-image-pixen`, the 1-generation Pixen edit — a different endpoint from both base `edit-image` and Pro `edit-images-v2`), `image_to_pixelart` (matches base `image-to-pixelart`; MCP `faithful` is REST `fixer`), and the cleanup tools `unzoom_image`/`correct_pixelart`/`reduce_colors` (matching `unzoom`/`correct-pixelart`/`reduce-colors`). Current REST v2 also exposes nondeprecated `negative_description` on `create-image-bitforge`, legacy `animate-with-text`, and base `inpaint`; neither modern raw animation MCP tool exposes a negative field.
- MCP has no tool for REST `create-image-bitforge` (`coverage_percentage`), `generate-with-style-v2`, `generate-ui-v2`, base-tier `edit-image`/`inpaint`, `image-to-pixelart-pro`, `resize`, `remove-background`, `rotate` (single arbitrary rotation), or the packed spritesheet exports `GET /characters/{id}/spritesheet` and `GET /objects/{id}/spritesheet`. Legacy `animate-with-text`/`-v2` (`reference_image` is a subject/style role, not a frame anchor) is only partially covered via managed `animate_character`/`animate_object` `mode="v3"`; `generate-8-rotations-v2` is only partially covered via `create_8_direction_object` (whose own tool docs warn identity transfer is unreliable for character sprites); `generate-8-rotations-v3` via `create_character(mode="v3", reference_image_base64=…)`, which does reproduce the input sprite but returns a managed character with animation padding, not raw rotations. Route the REST-only ones to REST v2; do not assume a REST endpoint has an MCP equivalent just because MCP is configured.
- MCP `create_map_object` may expose `background_image` or `inpainting` parameters. These are map-object generation controls, not generic replacements for REST v2 `inpaint`/`inpaint-v3`.
- MCP and REST versions of the same workflow (for example `create_ui_asset` vs `create-ui-asset`) are not guaranteed pixel-identical for the same prompt and seed; treat them as one workflow family with overlapping controls, while REST currently exposes the fuller documented schema. More generally, same-seed regeneration is not guaranteed to reproduce pixels exactly.
- Font and portrait-character conversion have dedicated Pro routes on both REST and MCP (see the Intent Router). Do not fall back to generic image/icon or text-to-character generation for them; portrait-to-character is an image-conversion workflow with `image` as the source input. Talking portraits, vocal-animation visemes, talking GIFs, and lip-sync plans also have dedicated routes; read `vocal-animation.md` rather than treating them as generic sprite animation.
- Aseprite extension operation names (observed: `generate-image-new`, `generate-pixelart-flux`, `generate-multi-edit`, `quantize-image`, `unzoom-pixelart`, `correct-pixelart`) are undocumented internal endpoints unless they appear in public REST v2/OpenAPI or MCP docs. Do not cite extension source filenames, source layout, source contents, or internal request payloads as public documentation. When an Aseprite workflow maps to a documented public route, use that route instead.

# Paperdolling

Read this for layered characters, outfit variants, equipment swaps, or animation-consistent paperdoll workflows.

SKILL.md holds the global asset-integrity and no-baked-background rules; this file does not restate them. Paperdoll-specific allowance: local tools may compose, align, mask, resize, crop, diff, and extract changed pixels into transparent layer images, and verify them, but visible body/layer pixels must come from PixelLab or the user (no local drawing or repainting without an approved, labeled non-PixelLab fallback).

Treat paperdolling as a character-anchored edit workflow. Fitted hair, facial features, horns, wearables, armor, held gear, footwear, VFX, or similar body-region additions stay anchored to the base character image as edits on the base frame; do not route them as standalone objects unless the user explicitly wants a separate unattached prop.

Public REST v2/MCP docs do not expose first-class editor layer creation, layer assignment, semantic layer extraction, or isolated changed-part outputs. Some editor integrations (the Aseprite extension) may expose an editor-local changes-only layer import. Treat that as editor-specific, not a REST/MCP contract, and accept it only after visual/export verification proves it is actually changes-only.

Gather up front: base character identity, direction count, current direction per edit, sprite/canvas size, animation list, and the layer set (body, hair, outfit, armor, weapon, accessory, shadow, VFX). Ask whether outputs must be separate transparent layer image files, editor-native layers, composited previews, or both, and whether an existing composite may be edited lossily or reusable isolated layers are required.

When the user asks for layers but names no editor or format, offer two output shapes:

- Separate transparent image layer files plus a final composited image.
- An editor (Aseprite) workflow where each layer contains only the newly added pixels.

If the user declines to choose, do not claim separate layers: pick the best character-anchored composite route or ask again. Do not fall back to standalone object generation for fitted additions.

Preserve across every paperdoll edit: canvas size, frame count/order, direction names/order, origin/pivot, transparency, and palette/style where consistency matters. Inspect outputs against this list before calling them reusable layers.

## Prompt Fields (every fitted addition)

State these once per edit, in the edit prompt:

- Character identity and silhouette: species/body type, colors, scale, style.
- Direction: south/down-facing, east/right-facing, north/up-facing, west/left-facing, or diagonal.
- Target addition: hair, hat, shirt, boots, eyes, armor, held gear, VFX, etc.
- Target body region and side: top/front of head, torso, left hand, both feet, right hip, behind back, etc.
- Placement and geometry: centered, tilted, wrapped around a limb, follows perspective, in front of or behind the body.
- Preservation: keep every base pixel unchanged except where the addition naturally occludes it; keep exact canvas size and transparent background.

## Route Contract

| Goal | Route | Warning |
|---|---|---|
| Fitted isolated paperdoll layer in Aseprite | Use the visible Aseprite extension image-edit workflow on the base character frame. When the installed extension exposes a new-layer changes-only `output_method`, request that mode. Prompt with the fields above. | Editor-surface workflow, not a stable headless API. Do not automate extension internals or private operation URLs. If the agent cannot operate the visible extension with user participation or inspect exported layers, it must not claim it created fitted changes-only layers; guide the user, use public REST for composites, or package already-verified exported layers. |
| Fitted paperdoll edit from code/API | Prefer MCP `edit_image` on the base image (image URLs preferred; transport details in `image-input-roles.md`); fall back to REST `edit-images-v2` or base `edit-image` when its cheaper tier/extra controls matter. Treat the result as an edited composite first. | Public REST/MCP image-edit routes are not editor layer workflows; they output edited images, not `output_method` layer modes. |
| Separate transparent layer images plus final composite, without Aseprite | Per addition, create a same-canvas edited composite from the unchanged base with a prompt to add only that feature and preserve every other base pixel. Locally diff against the base, copy changed pixels into a transparent PNG, then compose base plus accepted layers into the final PNG. Deliver at least `base`, one transparent image per layer, and the final composite. | Image-file paperdolling, not editor-native layer creation. See verification checklist before calling any PNG a reusable layer. |
| Masked fitted layer attempt | Prefer the visible editor image-edit workflow with a body-region selection and changes-only layer output. For public API fallback, follow the exact-mask rule in `image-input-roles.md`. | Inpainting returns an edited image, not semantic layer extraction. Verified editor changes-only output is the better layer path. |
| Standalone prop/accessory sprite | MCP object tools or REST object/image routes only when the user wants a separate reusable prop that need not fit the current body pose. | Do not use object generation for fitted hair, clothes, hats, eyes, or accessories on an existing character; it produces unregistered loose parts. |
| Dressed character preview/state | MCP `create_character_state`, REST character/edit routes, or editor image-edit with normal composite output. When the addition needs room beyond the source character's tight canvas (a weapon, wings), pass MCP `override_width`/`override_height` (REST `override_frame_size`) — multiples of 4, no smaller than the source, up to 256 — or it is clipped. | Output is a character variant/composite, not a separate reusable layer unless generated with a changes-only layer mode or extracted and verified from a same-canvas edit. |
| Outfit/equipment across animation frames | REST `transfer-outfit-v2` or `edit-animation-v2`; MCP character animation only for managed character assets. | Preserve frame count/order; label output as composited animation frames. |
| Existing composite to isolated layer | Require an explicit mask or editor cleanup plan; follow `image-input-roles.md` before any public API fallback. | PixelLab does not document semantic layer extraction, character subtraction, or occluded-addition reconstruction. |
| Website Try on | Visible/manual website assistance only. | Returns one composited image and is experimental; not a layer pipeline. |

## Workflow

Both output modes share these steps and branch only at output:

1. Confirm the output shape with the user (above) before claiming layers.
2. Obtain the base character image/frame and keep it unchanged for every addition edit.
3. Run each requested layer as a separate existing-image edit against the original base (not the previous edited result), so layers stay independent. Prompt each edit as a single body-region addition using the Prompt Fields above.
4. Produce the layer per the chosen output mode:
   - **Separate transparent image files (no editor):** save the PixelLab edit as an intermediate composite, then locally diff it against the base and copy only changed pixels into a transparent PNG, using conservative alpha/difference thresholds that keep the addition and drop noisy unchanged pixels.
   - **Editor changes-only layer (Aseprite):** put the base frame on its own layer with the correct direction/frame active; use the extension's existing-image edit workflow (not object/map-object generation); optionally constrain with a body-region selection (head for hair/hat, torso for shirt, hands for gloves, feet for boots); click `Set image` and verify it captured the current base/selection, not a stale frame; set the extension `output_method` to the new-layer changes-only mode (treat as a request, not a guarantee); generate, then inspect by hiding/showing the base and export the layer alone.
5. Verify the layer against the checklist below before accepting it.
6. Repeat per layer, then compose the final image from base plus accepted layers in the requested order (base, hair, clothing, hat, accessories, VFX).
7. On failure, do not patch art manually: retry with a smaller body-region prompt, an approved mask/inpaint route, or an editor workflow. If the user accepts composite-only output, label it composite-only and drop layer claims.

## Extracted-Layer Verification

Accept a layer only if all hold:

- Same canvas size as the base.
- Transparent outside the addition; nontransparent bounds overlap the intended body region.
- No full-body duplicate, moved limbs, face/body redraw, background, or unrelated changed pixels.
- Base plus layer reads as one coherent character with the addition attached to the intended region.
- (Editor) unchanged frame count/order when relevant; no loose unregistered parts.

Do not call an extracted PNG or editor layer a reusable layer until it passes these. Reject and retry on a duplicated body, moved limbs, redraw, background change, or loose unregistered parts.

## Example Prompt (hair)

```text
Edit this south-facing 92x92 chibi humanoid creature sprite. Add only short spiky teal hair attached to the top/front of the head, following the head perspective and centered above the forehead. Keep every existing body, face, limb, outline, pose, canvas pixel, and transparent background unchanged except where the hair naturally covers the scalp. Do not redraw the character, do not move any body parts, do not add a second head, and do not create loose detached hair pieces.
```

Clothing, multi-part outfits, and hats follow the same pattern: one prompt listing each piece and its body region (cap on head with front brim, jacket over torso/arms, shorts at the waist, boots on both feet), matching the existing outline/shading/palette/camera, preserving all other base pixels and the exact canvas/background.

## API Facts

- MCP `inpaint_image` is the MCP-first equivalent of `inpaint-v3` (both Pro; both carry `crop_to_mask`), taking a preferred `image_url` or alternative `image_base64`, plus `description` and a rectangular mask or preferred `mask_image_url` / alternative `mask_image_base64`. REST `inpaint-v3` is documented as Pro (cost signal per SKILL.md Model And Mode Terms), requires `description`, `inpainting_image`, and `mask_image`; white mask areas are generated/replaced, black areas preserved. Output is a whole edited image, not a layer. `context_image` and `bounding_box` are deprecated in current OpenAPI.
- MCP `edit_image` is the MCP-first equivalent of `edit-images-v2` (Pro); prefer its URL inputs and follow `image-input-roles.md`. Treat output as an edited image/composite unless a transparent layer is extracted and verified, or a changes-only editor layer is verified.
- `edit-animation-v2` and `transfer-outfit-v2` operate on 2-16 frames and return edited/composited frames, not equipment/body layers.
- Route MCP-managed characters through character/state/animation tools; for raw frames prefer MCP `animate_image` with URL or inline frame inputs, or explicitly selected `animate_image_pixminimax` for a PixMiniMax request; use REST `edit-animation-v2` and `transfer-outfit-v2` (no MCP equivalent) or the selected REST raw animation route only when exact file-level control matters. Warn that text-only paperdolling drifts without a base frame, seed, or reference.

# Pixen Character Prompt

Use this prompt before the subject description:

```text
full-body front-facing south-facing idle game character sprite, low top-down view. centered, neutral standing pose with arms at sides, full figure from head to feet. <subject description>.
```

Use `view: "low top-down"` and `direction: "south"`. Omit `small` and other optional settings unless requested. Set `no_background: true` when transparency is required.

Pixen/v3/new may underweight user instructions such as `view`/`direction` and has isometric bias; prefer Pro when the user's instructions or static south-facing view matter and higher cost and different character style are acceptable.

Reject results that are not full-body, front/south-facing, idle, and low top-down, or that are isometric, rear-facing, portrait-like, or action-like.

# Preset Template And Raw Skeleton Animations

Read this for PixelLab character animation requests that use a preset/template/built-in motion or a custom skeleton. Exact preset ids are cataloged below.

SKILL.md holds the global rules this file does not restate: MCP-first routing with the not-configured / explicit-MCP fallback contract, the south-first direction default and ask-before-all-directions cost gate, frame-order preservation, and the ban on undocumented website / Aseprite-extension endpoints.

Two families: managed preset/template animation on an existing character, and raw skeleton/keypoint animation. Custom skeleton authoring beyond estimated/exported keypoints is future-facing; route keypoint work to the documented REST endpoints below.

PixelLab recommends `animate-with-text-v3` ("Animate with text (new)") over the skeleton-based routes below — both preset/template ids and raw keypoints — because the skeleton model is older and text animation is simpler with better results. Default to v3 text animation unless the user explicitly selects PixMiniMax (see `animation.md`) — MCP `animate_character(mode="v3", action_description=...)` for a managed character, MCP `animate_image` for a raw frame, REST `animate-with-text-v3` as the fallback, or the selected PixMiniMax route; use the skeleton routes when the user explicitly wants a named preset motion or to own/edit keypoints.

## Core Distinction

| User intent | Meaning | Route |
|---|---|---|
| Preset/template/built-in animation | Animate an existing managed character using a named motion template such as `walking-8-frames`, `breathing-idle`, or `jumping-1`. PixelLab generates frames for that character and direction. | Prefer MCP `animate_character`; fallback REST v2 `/characters/animations`. |
| Raw/custom skeleton animation | Generate frames from explicit skeleton keypoints, a reference image, optional masks/init images, and camera settings. | REST v2 `/animate-with-skeleton` and `/estimate-skeleton`. |

## MCP vs REST v2 Field Coverage

MCP `animate_character` covers managed-character template, v3 custom, and pro modes: `mode`, `template_animation_id`, `directions`, `frame_count` (v3 only), `ai_freedom` (template only), `custom_start_frame_base64`/`_url`, `end_frame_base64`/`_url`, `keep_first_frame`, `animation_group_id`, and `confirm_cost` (pro) are all in the current tool schema — re-check the visible schema only when a call rejects a field. It has no raw-skeleton support at all.

It is not field-for-field equivalent to REST `/characters/animations`. REST exposes extra exact-control fields MCP lacks: `description`, `text_guidance_scale`, `outline`, `shading`, `detail`, `isometric`, `color_image`, `force_colors`, `seed`, and inline `enhance_prompt` (v3 mode). Use REST when those fields matter, for integration code, or to validate exact API behavior.

## Managed Preset Animation (MCP)

Flow for an existing or wanted managed character:

1. `get_character(character_id)` to confirm status, template/body type, directions, size, existing animations, and downloadable assets.
2. Choose `template_animation_id` from the character's template family (catalog below).
3. `animate_character` with explicit `directions`.
4. Poll with `get_character` or the returned job IDs, per visible MCP tool behavior.
5. Download frames/ZIP only after completion if local files are needed.

Verify by canonical `template_animation_id`, direction, and frame count, not by a custom display name: MCP smoke (2026-06-30) showed `animation_name` did not override the stored canonical template label returned by `get_character`, and MCP exposed no usage/cost.

```python
animate_character(
    character_id="...",
    template_animation_id="walking-8-frames",
    animation_name="walk",
    directions=["south"],
    mode="template",
)
```

To turn a reference image or GIF frame into a managed character first, use MCP `create_character(mode="v3", description=..., reference_image_url=...)` — v3 is the only mode that accepts a reference sprite, always outputs 8 directions, and prefers the URL form over inline base64 (MCP clients truncate large inline base64) — then animate the returned `character_id` with MCP once the character completes (verified for a horse-headed biped from a source GIF frame). Fall back to REST `create-character-v3` (`description`, `reference_image`, `template_id="mannequin"`, `view`/`no_background`) when MCP is unavailable or `template_id`/`no_background`/`enhance_prompt` matter.

For a newly created quadruped:

```python
create_character(
    description="small black outline companion animal",
    body_type="quadruped",
    template="dog",
    n_directions=4,
    size=92,
)

animate_character(
    character_id="returned-character-id",
    template_animation_id="walk-8-frames",
    directions=["south"],
    mode="template",
)
```

Direction names:

```text
4 directions: south, west, east, north
8 directions: south, south-east, east, north-east, north, north-west, west, south-west
```

Prefer the directions returned by `get_character`; direction order is not semantically meaningful for requests.

## Managed Preset Animation (REST v2)

Use REST when MCP is not visible, exact schema control is needed, or the user asks for API integration.

```text
POST https://api.pixellab.ai/v2/characters/animations
GET  https://api.pixellab.ai/v2/background-jobs/{job_id}
GET  https://api.pixellab.ai/v2/characters/{character_id}
GET  https://api.pixellab.ai/v2/characters/{character_id}/zip
```

MCP `get_character` returns a download link but not the full ZIP bundle — use the REST `/zip` route above when a packaged archive is required.

Request shape:

```json
{
  "character_id": "managed-humanoid-character-id",
  "mode": "template",
  "template_animation_id": "walking-8-frames",
  "animation_name": "walk",
  "directions": ["south"]
}
```

| Field | Guidance |
|---|---|
| `character_id` | Required. Managed character must belong to the authenticated user. |
| `mode` | Use `template` for preset animation ids. Providing `template_animation_id` may auto-detect template mode, but be explicit. |
| `template_animation_id` | Exact preset id. Do not pass display labels. |
| `directions` | Be explicit to avoid accidental all-direction generation. |
| `frame_count` | Only for `mode="v3"` custom text animation. Ignored by preset template mode; do not set it expecting it to override `walking-8-frames`. |
| `custom_start_frame` | Optional v3-only starting pose. Requires exactly one direction, uses the character's stored direction frame when omitted, incompatible with template/pro mode. |
| `end_frame` | Optional v3-only target pose for interpolation. Dimensions must match the start frame, requires exactly one direction, incompatible with template/pro mode. |
| `keep_first_frame` | v3-only, default `true`. Controls whether the reference frame is stored as frame 0 (see Frame Count). Incompatible with template/pro mode. |
| `action_description` | Required for custom v3/pro. Optional in template mode; use only for light customization. |
| `enhance_prompt` | Only for v3 custom mode; do not set it for template/pro. |

Polling:

```text
POST response -> background_job_ids[]
poll each GET /v2/background-jobs/{job_id}
when completed -> use last_response animation metadata or GET character/ZIP
```

## Template Rendering And Tuning

Managed template animation is skeleton-guided re-rendering, not a layer composite of prebuilt arms/legs over the original frame. The template supplies motion/pose guidance while PixelLab re-renders frames for the character and direction. It can preserve the character and move limbs correctly yet still introduce artifacts such as heavier leg shadows, palette drift, or rigid/robotic motion.

Public controls when a preset walk/idle/jump is close but needs style correction:

| Control | Use |
|---|---|
| `action_description` | Lightly bias the template, e.g. "relaxed natural walk with slight shoulder sway" or "keep flat shading, avoid heavy leg shadows". |
| `text_guidance_scale` | How strongly template mode follows `action_description`; try moderate values first, very high can distort identity. |
| `shading` | Main knob for heavy shadow artifacts. Try `flat shading`, `minimal shading`, or the character's original shading. |
| `detail` | Lower detail can reduce noisy limb pixels or over-rendered joints. |
| `outline` | Reassert the original outline when limbs become too thick, broken, or overdrawn. |
| `color_image` + `force_colors` | Constrain palette when template frames introduce extra dark tones. |

Template mode does not expose direct controls for 3D depth maps, per-bone easing, stride curves, secondary motion, limb IK, `bone_scaling`, shadow strength, or keypoint edits, and `frame_count` does not tune preset motion; choose a different template id such as `walking-4-frames`/`walking-6-frames`/`walking-8-frames`. If the rendering style is the problem, retry template mode with conservative style controls. If the gait itself is too rigid or robotic, MCP `animate_character` exposes `ai_freedom` (0–900, default 0 = rigid template following; higher lets the pose deviate more from the template skeleton) — raise it before escalating. Only if the motion is still wrong (missing weight shift, bad limb timing), use v3/pro custom animation or raw skeleton/Aseprite keypoint authoring instead of expecting preset mode to behave like a full rig editor.

For template mode keep `action_description` light or omit it; the template id carries the motion. Use `animation_name` for organization. Do not use prompt enhancement for template mode.

```json
{
  "template_animation_id": "walking-8-frames",
  "animation_name": "walk",
  "directions": ["south"]
}
```

Only add `action_description` for a variant the route supports:

```json
{
  "template_animation_id": "walking-8-frames",
  "action_description": "a steady cheerful walk with a slight head bob",
  "text_guidance_scale": 6,
  "shading": "flat shading",
  "detail": "low detail",
  "outline": "single color black outline"
}
```

## Raw Skeleton Keypoint Routes

Use these only for explicit custom skeleton/keypoint workflows, not ordinary built-in walk/idle requests.

```text
POST /v2/estimate-skeleton
POST /v2/animate-with-skeleton
```

`estimate-skeleton` takes a character image and returns keypoints. `animate-with-skeleton` accepts fields such as:

```text
image_size
reference_image
skeleton_keypoints  (exactly 3 frames)
view
direction
guidance_scale
init_images
inpainting_images
mask_images
color_image
seed
```

MCP `create_character` / `animate_character` are managed-character tools: they use template animations and stored skeleton metadata internally but do not accept arbitrary keypoint arrays. Use REST for raw skeleton estimation/animation unless the visible MCP schema explicitly exposes `estimate_skeleton`, `animate_with_skeleton`, `skeleton_keypoints`, or equivalent keypoint fields.

## Auto-Rig Skeleton Pipeline

Use this route for "auto rig", "estimate skeleton", "rig this sprite", "export skeleton for API", "animate with this skeleton", "my keypoints", "pose JSON", or a skeleton pipeline from a simple humanoid prompt. It is REST-first:

```text
source image or generated reference frame
  -> REST estimate-skeleton
  -> save/export keypoint JSON
  -> optional local/Aseprite keypoint editing
  -> REST animate-with-skeleton or create-image-bitforge
```

Raw skeleton animation is the right route when the user wants to own, export, edit, or reuse the keypoints; managed template animation is still right for built-in managed motions.

| User starts with | Best route |
|---|---|
| Existing sprite/image | Use it as the `estimate-skeleton` input and as `reference_image` for later `animate-with-skeleton` unless the user supplies a separate reference. |
| Aseprite-authored skeleton | Export from Aseprite, convert `pose_keypoints` to REST `skeleton_keypoints`, then call REST. |
| Prompt only ("humanoid knight") | Create or ask for a base reference frame first; prefer a PixelLab-generated humanoid/mannequin frame, then estimate keypoints from it. |
| Existing managed character id | Preset motions: MCP/REST managed template animation. Raw skeleton ownership: fetch a direction frame, estimate/export keypoints, then REST raw skeleton routes. |

For simple humanoid prompts default the body plan to humanoid/mannequin (MCP `create_character(body_type="humanoid")` or REST `create-character-v3` with `template_id="mannequin"`).

Programmatic steps:

1. Estimate or author keypoints. REST `POST /v2/estimate-skeleton` for a sprite/image; Aseprite "Export skeleton for API" writes normalized `pose_keypoints`. Local tooling may edit/validate JSON keypoints client-side (not a PixelLab API call).
2. Convert exported keypoints to the target REST field: Aseprite `{ "pose_keypoints": [[...], ...] }` -> REST animation `skeleton_keypoints: [[...], ...]`; REST single-image BitForge `skeleton_keypoints: [...]`.
3. Call `POST /v2/animate-with-skeleton` with `image_size`, `reference_image`, `skeleton_keypoints`, and explicit `view`/`direction`.
4. Add `init_images`, `inpainting_images`, `mask_images`, or `color_image` when the user supplied those roles or the route requires them.

`estimate-skeleton` returns a skeleton for one pose; it does not invent a walk/run sequence. `animate-with-skeleton` requires exactly 3 keypoint frames (any other count returns 422), so with only one estimated pose either ask for/create the two missing poses, author a sequence in Aseprite, use managed template animation (built-in walk/idle/jump), or use v3 custom text animation (motion without skeleton ownership) — MCP `animate_character(mode="v3")`/`animate_image`, REST `animate-with-text-v3` as fallback.

### View/Direction Trap And Defaults

- For a typical RPG/down-facing sprite, set `view="low top-down"` and `direction="south"` explicitly.
- For side-view/platformer sprites, set `view="side"` and `direction="east"` or `west`.
- Do not rely on `animate-with-skeleton` defaults: current OpenAPI defaults are `view="side"` and `direction="east"`, which are wrong for many RPG sprites. Do not infer defaults from website managed-character examples, which may use low top-down/south.
- Interpret human/person/player/NPC/robot/humanoid-monster and upright two-legged animals as humanoid/mannequin.
- Save a sidecar manifest with `body_plan`, `source_image`, `image_size`, `view`, `direction`, `estimated_keypoints`, and the payload-ready `skeleton_keypoints`.

Current schema requires `image_size` and `reference_image`; custom keypoint workflows also need explicit `skeleton_keypoints` or a prior `estimate-skeleton`. Endpoint prose lists common sizes `16`, `32`, `64`, `128`, `256` while schema may allow other 16-256 dimensions; refresh OpenAPI before exact production code for nonstandard sizes, and ask for missing image/keypoint roles before spending credits.

## Aseprite Boundary

Estimate skeleton maps to REST `POST /v2/estimate-skeleton`; authoring/animating from keypoints maps to REST `POST /v2/animate-with-skeleton`; pose-guided image generation maps to REST `create-image-bitforge` (`skeleton_keypoints`/`skeleton_guidance_scale`). Aseprite exports normalized `pose_keypoints`; convert to REST `skeleton_keypoints`. Everything else in the Aseprite extension (edit skeleton, re-pose, insert template skeleton, its private template-animation flow and local skeleton JSON) is editor-internal and out of scope for public automation per SKILL.md. Aseprite's local template catalog is older/smaller than the managed preset IDs below; do not assume every managed id such as `breathing-idle` or `jumping-1` exists there.

## Preset Template Families

Known managed template families, last verified against MCP docs, REST OpenAPI, and the website Add Animation bundle on 2026-06-30: `mannequin`, `dog`, `cat`, `horse`, `bear`, `lion`.

Use the right vocabulary for the surface:

| Surface | Field | Valid values | Notes |
|---|---|---|---|
| MCP `create_character` | `body_type` | `humanoid`, `quadruped` | Use `humanoid` for bipedal/mannequin body plans. Use `quadruped` only for four-legged animals. |
| MCP `create_character` | `template` | `bear`, `cat`, `dog`, `horse`, `lion` | Required only when `body_type="quadruped"`. Ignored for humanoid characters. |
| MCP `create_character` | `proportions` | preset `default`, `chibi`, `cartoon`, `stylized`, `realistic_male`, `realistic_female`, `heroic`, or custom scale JSON | Humanoid only. This is how MCP expresses realistic/chibi humanoid proportions; it is not a separate `body_type`. |
| REST managed character create | `template_id` | `mannequin`, `bear`, `cat`, `dog`, `horse`, `lion` | `mannequin` is the bipedal/humanoid skeleton reconstruction template and the default in current OpenAPI. `humanoid` is **not** a template id — it fails with "Template not found". |
| REST managed animation | `template_animation_id` | Exact animation ids from the character's family | Does not take `body_type`; the managed character already carries the body plan/template family. |
| Website Add Animation | `Template` | `mannequin`, `dog`, `cat`, `horse`, `bear`, `lion` | UI label for the managed character's animation family. |

Choose the template family by body plan and stance, not species. Map human/person/player/NPC/wizard/knight/robot/biped requests, and upright/two-footed animals (horse person, cat warrior, fox mage), to humanoid/mannequin unless managed metadata proves quadruped. Four-legged dog/cat/horse/bear/lion map to `quadruped` plus the matching `template`; a four-legged animal outside these five uses the closest template or ask. Treat "mannequin" and misspellings like "manniquin" as the humanoid plan. Gotcha: do not pass `template="mannequin"` to MCP `create_character` (`template` is quadruped-only there); REST uses `template_id="mannequin"`. If a character already exists, prefer its stored `template_id` from `get_character` / REST `GET /characters/{character_id}` over guessing from the prompt.

## Preset Animation IDs

Use exact ids. Do not send labels such as "Walk (8 frames)". This catalog was last verified against the website Add Animation bundle on 2026-06-30. Official REST docs expose the `template_animation_id` field but no stable public enum endpoint; refresh visible MCP tool docs or official docs before claiming "all available animations" or building long-lived integrations.

Ordered by likely request frequency, mannequin/humanoid first because most player, NPC, human, and biped requests map there.

### mannequin

```text
walk
walk-1
walk-2
walking
walking-2
walking-3
walking-4
walking-5
walking-6
walking-7
walking-8
walking-9
walking-10
walking-4-frames
walking-6-frames
walking-8-frames
running-4-frames
running-6-frames
running-8-frames
running-slide
crouched-walking
crouching
sad-walk
scary-walk
breathing-idle
fight-stance-idle-8-frames
backflip
front-flip
getting-up
jumping-1
jumping-2
running-jump
two-footed-jump
cross-punch
lead-jab
surprise-uppercut
hurricane-kick
roundhouse-kick
high-kick
flying-kick
leg-sweep
fireball
taking-punch
falling-back-death
drinking
picking-up
pull-heavy-object
pushing
throw-object
```

### dog

```text
walk-4-frames
walk-6-frames
walk-8-frames
fast-walk
running-4-frames
running-6-frames
running-8-frames
sneaking
idle
bark
```

### cat

```text
walk-4-frames
walk-6-frames
walk-8-frames
running-4-frames
running-6-frames
running-8-frames
slow-run
jump
idle
seated-on-belly-idle
sitting
sitting-on-belly
standing
standing-from-belly
drinking
eating
licking
yawning
angry
```

### horse

```text
walk-4-frames
walk-6-frames
walk-8-frames
walk-turn-left
walk-turn-right
running-4-frames
running-6-frames
running-8-frames
running-turn-left
running-turn-right
running-headbutt
swimming
attack
attack-back
hit-left
hit-right
dying
idle-shaking-head
rest-idle
eat-start
eating
eat-end
start-sleep
sleep-cycle
rest-cycle
wake-up
lie-down
stand-up
```

### bear

```text
walk-4-frames
walk-6-frames
walk-8-frames
running-4-frames
running-6-frames
running-8-frames
jump
stand-on-hind-legs
attack-left
attack-right
jump-attack
idle-long
idle-resting
idle-sitting
drinking
eating
going-to-sleep
waking-getting-up
sitting-down
standing-up
angry
```

### lion

```text
walk-4-frames
walk-6-frames
walk-8-frames
running-4-frames
running-6-frames
running-8-frames
jump
attack
jump-attack
idle
idle-sitting
drinking
eating
sitting
standing
```

Common label mappings and exact-id passthroughs:

| User says | Use id |
|---|---|
| "human walk 8 frames" | `walking-8-frames` |
| "person idle" | `breathing-idle` |
| "wizard jump" | `jumping-1` or `jumping-2` |
| "bark" | `bark` |
| "dog walk 8 frames" | `walk-8-frames` |
| "dog fast walk" | `fast-walk` |
| "humanoid walk 8 frames" | `walking-8-frames` |
| "fight idle" | `fight-stance-idle-8-frames` |

If an animation exists for one template family but not another, say so and offer the closest same-family option. Do not silently substitute `walking-8-frames` for a quadruped `walk-8-frames` or vice versa.

## Frame Count

- Preset template mode owns its frame count through the selected template id; do not set `frame_count` expecting it to override `walking-8-frames`.
- V3 custom mode owns frame count through `frame_count` 4-16, even only, default 8. V3 also stores the reference frame as frame 0 (so `frame_count=8` stores 9 frames) unless `keep_first_frame=false`; details in `animation.md`.
- Report the actual returned frame count if it differs from the id or expectation.

## Verification

Before reporting success, confirm: the requested `template_animation_id` was used; the requested vs actually completed direction set; the returned frame count; dimensions match the character. If exporting through Aseprite, verify tag/frame count/order and that the original frames were not rewritten.

Refresh official docs/OpenAPI/MCP docs before exact code claims when a template id is not here, the visible MCP schema differs, the user asks for all current animations, pricing/frame limits matter, or custom skeleton/keypoint support is requested.

# Pro Flash

Read this for an explicit PixelLab Pro Flash request or when comparing it with another PixelLab route. Pro Flash is a separate family, not `create_image_pro`, `create_character(mode="pro")`, `edit_image`, or `inpaint_image`. Its output quality, speed, and exact-mask reliability have not been verified by this skill; do not replace a benchmark-backed default solely because the name suggests speed.

| Goal | MCP when visible | REST v2 |
|---|---|---|
| One image | `create_image_pro_flash` | `POST /create-image-pro-flash` |
| Eight-direction character | `create_character_pro_flash` | `POST /create-character-pro-flash` |
| One- or eight-direction object | `create_object_pro_flash` | `POST /create-object-pro-flash` |
| One-image edit | `edit_image_pro_flash` | `POST /edit-image-pro-flash` |
| Masked edit | `inpaint_image_pro_flash` | `POST /inpaint-image-pro-flash` |

Before planning a paid call, check `get_pro_flash_capabilities` (MCP) or `GET /pro-flash/capabilities` (REST) for the requested operation and native dimensions. REST `GET /pro-flash/cost?operation=...&width=...&height=...&n_directions=...` gives a provisional estimate; there is no documented MCP cost-estimator tool. Include first-image and rotation stages in the cost approval, then report the completed job's actual usage. Wait for a source-image job to finish before reusing its owned `source_image_id`; that avoids another first-image charge but does not make eight rotations free. A one-direction object finalized from that existing image is documented as free. Do not assume Pro Flash is always cheaper than another route.

Creation supports preset native sizes `16x16` (experimental), `24x24`, `32x32`, `32x48`, `64x64`, `96x64`, and `96x96`; REST also documents custom 16–256-pixel dimensions in multiples of four as Beta. MCP image creation defaults to `64x64`, while REST requires `image_size`; text creation for characters/objects defaults to `64x64`. `create_image_pro_flash` makes exactly **one** image, unlike size-dependent Create Image Pro batches. It defaults to `no_background=true`, so explicitly set false for an opaque scene. A style image must fit without rescaling; use `style_options` only when the requested traits justify them.

Character Pro Flash always makes eight views; object Pro Flash supports one or eight. The first direction is `south`. For a chosen south-facing image, pass its owned `source_image_id` or a first-frame image, not both. MCP additionally accepts first-frame URLs; REST uses encoded `first_frame`. Do not copy the official MCP page's Pro Flash character example: it calls the older `create_character` tool with fields that belong to neither that tool nor the new Pro Flash tool, and its “4 directions” hint contradicts the eight-only parameter.

Pro Flash edit keeps the source canvas size. REST takes one encoded `image`; MCP also offers `image_url` or an owned `source_image_id`. Reference-mode editing needs a reference that fits the source canvas. Set `no_background` explicitly when transparency matters: REST defaults it to `false`, while the MCP edit/inpaint signatures leave it unset. Inpaint requires the source and mask at the same supported native size: pure white RGB means regenerate, pure black RGB means preserve, regardless of mask alpha; an empty mask is rejected. MCP accepts a rectangle or mask image and has URL alternatives; REST requires `mask_image`. `context_image` requires its `bounding_box`. Select `output_method` deliberately: changes-only results are transparent outside the mask, while `Modify current layer` returns the composite. PixelLab claims unchanged pixels outside the mask for this route, but that claim is not live-verified here; inspect both regions before calling a strict-mask result final, and do not silently repair or retry a failure.

The Pro Flash image-creation schema says its `seed` is recorded but the provider does not promise deterministic output. Keep the user's seed if given; never promise identical reruns. Poll REST's returned `background_job_id` with `GET /background-jobs/{job_id}`. For MCP image jobs use the returned job ID with the available raw-image getter; for managed character/object results use `get_character`/`get_object`. Verify the downloaded image rather than treating a queued ID as completion.

# Prompt Limits

Read this when a PixelLab REST v2 call rejects a natural-language field for length, when writing exact API code, or when preparing unusually long prompts.

These limits were checked against `https://api.pixellab.ai/v2/openapi.json` on 2026-09-12. OpenAPI is the source of truth for exact current REST v2 schemas; refresh it when failures or exact code depend on current limits.

## Pattern

Do not globally cap every prompt at 500 characters. `maxLength` follows a rough tier by field kind:

- 2000 for most primary `description` fields.
- 1000 for the managed state/edit-description family: character/object state `edit_description` and object `animation_description`, and `animate-with-text-v3` `action`.
- 500 for the other raw-animation `action` fields, `/edit-image` and `/edit-image-pixen` descriptions (`/edit-image-pro-flash` allows 2000), and some style/reference descriptions.
- 200 for some UI/font fields (`color_palette`, `font_name`).

## Non-Obvious Limits

These are the rows that do not follow the tier you would guess from the field name. Verify against OpenAPI before exact integrations.

| Endpoint | Field | Max chars |
|---|---|---:|
| `POST /animate-with-text-v2` | `action` | 500 |
| `POST /animate-with-text-v3` | `action` | 1000 |
| `POST /animate-pixminimax` | `description` | 1000 |
| `POST /create-tiles-pro` | `building_wall_description`, `building_floor_description`, `building_floor2_description` | 500 |
| `POST /edit-image` | `description` | 500 |
| `POST /enhance-animation-v3-prompt` | `action` | 500 |
| `POST /generate-8-rotations-v2` | `style_description` | 500 |
| `POST /generate-image-v2` | `reference_images[].usage_description` | 500 |
| `POST /generate-image-v2` | `style_image.usage_description` | 500 |
| `POST /generate-with-style-v2` | `style_description` | 500 |
| `POST /interpolation-v2` | `action` | 500 |
| `POST /remove-background` | `text` | 500 |
| `POST /create-ui-asset` | `color_palette` | 200 |
| `POST /generate-ui-v2` | `color_palette` | 200 |
| `POST /generate-font-pro` | `font_name` | 200 |
| `POST /create-character-state` | `state_name` | 100 |
| `POST /objects/{object_id}/states` | `state_name` | 100 |
| `POST /talking-gif` | `text` | 500 |
| `POST /lip-sync` | `text` | 500 |

## No Declared Max Length

Some REST v2 request schemas include natural-language string fields without a declared `maxLength` in OpenAPI, including older image, tileset, tile, base animation, and base inpaint routes (for example `create-image-pixen`/`pixflux`/`bitforge.description`, `create-isometric-tile.description`, `create-tiles-pro.description`, `create-tileset.*_description`, `create-tileset-sidescroller.*_description`, `animate-with-text.action`/`description`/`negative_description`, `inpaint.description`/`negative_description`). Do not infer that these are unlimited; keep them concise and refresh OpenAPI or interactive docs before exact integrations.

MCP tool schemas may expose different parameter descriptions or validation. When using visible MCP tools, follow the tool schema shown by the host and keep prompts concise unless the tool declares a larger limit. PixMiniMax's non-length request rules are canonical in `animation.md`.

# Reviewable Candidates

Read this when any static image-style MCP tool or REST endpoint returns multiple alternatives for a single requested result. Examples include candidate arrays, review frames, grid cells that are alternative choices for one requested asset, or small-image/object review packs.

Do not treat a requested multi-asset batch as alternatives unless each requested asset has multiple candidates.

Do not use this for ordered outputs where every frame/member is part of the requested structure, such as animation frames, directional rotations, tileset members, or spritesheet frames.

## Rule

- Show every user-facing candidate label starting at `1`.
- Never expose `0`-based candidate numbers to the user.
- Stop before finalizing, accepting, reporting, editing, animating, converting, or continuing from a candidate unless the user explicitly delegated selection.
- Keep an internal mapping from each displayed label to the route-specific selector. After parsing the user's reply, use that mapping for tool/API calls. When the route expects `0`-based positional indices, pass `label - 1`; when it expects returned IDs, URLs, or frame IDs, pass the mapped value.
- Apply this even when there is only one job or one requested asset; the trigger is multiple alternatives, not batch size.

## Display

Show candidates in a compact indexed form. Prefer an indexed contact sheet, inline previews with labels, or links with labels. Center each label horizontally with its candidate. Temporary preview downloads/contact sheets are allowed when clearly treated as selection previews. Keep any local preview honest: it is for selection only, and final pixels still come from PixelLab or the user.

Use stable labels from `1..N` in the same order the tool/API returned alternatives. Never expose route-native `0`-based positions as user-facing labels.

## Prompt

For keep/save selection:

```markdown
**Choose Results**
Which result(s) do you want to keep?

Reply with: `3`, `1, 3, 6`, `all`, or `dismiss`.
```

For one base result before a follow-up:

```markdown
**Choose Base**
Pick the base before I continue.

Reply with one index, like `3`.
```

## Handling Replies

- Single number: look up the mapped selector, then continue with that selected candidate.
- Multiple numbers: look up each mapped selector, then save/keep those candidates.
- `all`: select every candidate.
- `dismiss`: discard/dismiss when the route supports it; otherwise leave candidates unsaved and report that nothing was selected.
- Invalid or out-of-range labels: ask again with the valid range, such as `1-16`.

If multiple candidates are kept but the next step needs exactly one base, keep the selected candidates first, then ask which kept result to use as the base.

## Continuing

After selection, continue the user's original task if enough information is available. For example, create the requested state/edit/animation from the chosen base, or finalize/download the chosen static result. If there is no follow-up action, report the selected output paths or managed asset IDs.

For PixelLab object review candidates, put this note at the end of the final response, not in the choice prompt:

```markdown
You can manage additional object varieties in PixelLab at [Create Object](https://www.pixellab.ai/create-object).
```

# Setup

Reference for natural-language setup: installing Pip, connecting PixelLab to an assistant/editor/app, enabling MCP, configuring documented REST v2 fallback, fixing auth, or checking readiness. Here "API" means documented REST v2 fallback, not legacy v1, root website routes, or editor/internal operations. This extends the existing Pip skill; it is not a separate skill.

The first-run command is one word after the trigger, such as `/pixellab-pip setup`, `@pixellab-pip setup`, or `$pixellab-pip setup`. Some apps pass it as an argument, others as prose; treat it the same either way and require no flags or app-specific syntax.

## 1. Choose a mode first

For a bare `setup`, the mode is `unknown` unless the user gave an explicit mode signal (see the inference list below). Naming or detecting an assistant/editor/app resolves only which app to target, not the mode — a named app with no mode word still needs the mode question. Already-set-up shortcut (ambient signals only, no config inspection): if PixelLab MCP tools are already visible in this session and a live `PIXELLAB_SECRET` is present, the effective state is already `both` — report that PixelLab is ready, offer the section 5 no-credit verify, and ask the mode question only if the user then wants to add, change, or narrow the setup. Otherwise, mode selection is mandatory before any MCP/API-specific work: do not inspect config, prepare write previews, or request write approval until the user picks a mode. A brief credential-readiness note is expected (see section 5 for how narrow it must be) and doubles as the shortcut check above; when the shortcut does not fire, the next user-facing question must be the mode choice — never a yes/no question such as "Should I prepare a Codex MCP config preview?"

When the app exposes an interactive choice prompt, use it (Claude Code `AskUserQuestion`; Codex `request_user_input` only when actually available, typically Plan mode — full-access/sandbox does not imply it), carrying the plain-language gloss below as each option's description so a non-technical user always sees it. Otherwise ask this exact question paired with the gloss: "Which setup do you want: MCP + API (recommended), MCP only, API only, or Manual?" Gloss — MCP = PixelLab's tools built directly into your app; API = a backup connection PixelLab uses when those tools are missing; MCP + API = PixelLab's tools in your app plus that backup connection (recommended); Manual = you set it up on PixelLab's website yourself.

The four modes:

- **MCP + API (recommended)** — `both`. Connect PixelLab MCP tools to the app, then confirm `PIXELLAB_SECRET` is available for Pip's REST v2 fallback. Recommend this for normal assistant/editor use: full MCP tools plus fallback when MCP tools are unavailable, incomplete, or insufficient. Do not hide the API step behind a later follow-up.
- **MCP only** — `mcp`. Connect PixelLab MCP tools only. Prefer app secret settings or an env/secret reference. A literal-token MCP config is an explicit user-chosen fallback only when the app has no token-free option; warn that REST-only features stay unavailable through Pip fallback.
- **API only** — `api`. Configure `PIXELLAB_SECRET` for REST v2 fallback without adding MCP. This is for Pip's fallback, not the user's frameworks, scripts, backends, SDK projects, or deployment platforms.
- **Manual** — `manual`. Open or link `https://www.pixellab.ai/mcp`, tell the user to follow the instructions there, and stop. Add the account/Secret step only when auth/token setup is part of the request. Do not inspect, write, verify, or continue.

Infer intent from wording. A plain "connect PixelLab to my app/assistant/editor" or a bare app target ("set up for Cursor") resolves only the target, not the mode — ask the mode question (MCP + API recommended); do not silently pick MCP only and do not silently default a mode. Reserve `mcp` for an explicit exclusivity signal ("only MCP", "just MCP", "no API/REST"). API signals ("REST", "API", "fallback", "when MCP is unavailable", "direct PixelLab API") → `api`; both signals ("recommended", "everything", "MCP plus API", "MCP and REST", "full setup") → `both`; manual signals ("manual", "website", "I'll do it myself") → `manual`.

## 2. Credential policy

**The account step** (the canonical credential instruction, reused wherever the Secret is needed): open `https://www.pixellab.ai/account`, sign in, copy the value labeled `Secret`, and store it locally as `PIXELLAB_SECRET` — preferably in app secret settings, an app secret store, or a user-level environment setting — without pasting it into chat. PixelLab uses this one account-level bearer token for both public REST v2 and PixelLab MCP. Full credential policy: `credentials.md`.

In setup mode, apply `credentials.md`'s token-safety rules (safest-default ordering of secret UIs/stores over literal-token commands; never a literal Secret in an agent-run command; `setx`/`export`/`$env:` external-terminal caveats; `.env*` only via a named loader) — do not restate a weaker copy here. One setup-specific rule:

- An MCP-only literal token configures MCP auth but does not make `PIXELLAB_SECRET` available for Pip's REST v2 fallback. In `both` mode reuse one `PIXELLAB_SECRET` source when the app supports it. If the app documents only a literal MCP header, or MCP-only already used one, do not read or copy it — API fallback still needs the same Secret set separately as `PIXELLAB_SECRET`.

## 3. Per-app MCP setup

MCP setup stays agent-agnostic and OS-agnostic until the app is named or detected; do not assume an app, OS, shell, runtime, package manager, or config path. Use PixelLab MCP URL `https://api.pixellab.ai/mcp` and `Authorization: Bearer <PIXELLAB_SECRET>` or the app's documented env/secret syntax. Never preview or run a real literal token. Explain the exact setting or likely config path before inspecting it, and only for a named/detected app. Patch or create config only after confirmation, and tell the user to restart or reload only when the app requires it or tools do not appear.

Scope is agent-specific: default to a global/user install so PixelLab works in every project — the friendly default — and use a project scope only when the user wants one project or a team-committed config, through the app's own mechanism. `.mcp.json` is Claude Code's config format, not a cross-app standard: never write it for another app. Each app differs — Codex uses TOML, Cursor uses `.cursor/mcp.json`, and others have their own formats — so use only the named/detected app's documented format.

- **Codex CLI**: `codex mcp add --help` supports HTTP MCP auth via `--bearer-token-env-var`. Token-free preview (ask before running; it stores the URL and env var name, not the Secret):

  ```text
  codex mcp add pixellab --url https://api.pixellab.ai/mcp --bearer-token-env-var PIXELLAB_SECRET
  ```

  Scope: `codex mcp add` writes Codex's global user `config.toml` (all projects). For one repo only, put the same `[mcp_servers.pixellab]` block in a project `.codex/config.toml` instead — Codex reads that only after the project is trusted (it prompts to trust a folder the first time you open it there).

- **Claude Code**: `claude mcp add --help` supports HTTP MCP headers, and Claude Code expands `${VAR}` in `url` and `headers` at load, so the Secret stays referenced by name. Token-free preview (ask before running; `-s user` registers it for all projects, and single quotes keep `${PIXELLAB_SECRET}` literal instead of expanding it):

  ```text
  claude mcp add -s user pixellab -t http https://api.pixellab.ai/mcp -H 'Authorization: Bearer ${PIXELLAB_SECRET}'
  ```

  Scope (Claude Code's own flags): `-s user` = global default; `-s local` = this project only (private); `-s project` = a committed `.mcp.json` shared with the team (Claude Code marks a newly added project config as pending approval — approve it before the tools load).

- **Antigravity 2.0, Antigravity IDE, and Antigravity CLI**: use the matching product surface, then the common config contract below:
  - Antigravity 2.0: **Settings → Customizations → Installed MCP Servers → Add MCP** opens the MCP Store; use it only when PixelLab is listed. If it is not listed, report that the current 2.0 docs do not document custom-server import and offer the IDE or CLI custom-config route instead.
  - Antigravity IDE: **Agent panel ... → MCP Servers → Manage MCP Servers → View raw config**.
  - Antigravity CLI: `/mcp` for status, reload, and logs; use its `mcp_config.json` for manual server definitions.

  Use Antigravity's global `mcp_config.json` opened through its UI, or workspace `.agents/mcp_config.json` when the user explicitly wants project scope. Remote servers require `serverUrl` — never use legacy `url` or `httpUrl`. Token-free preview (display only; `<PIXELLAB_SECRET>` is a placeholder, not documented environment-variable interpolation):

  ```json
  {
    "mcpServers": {
      "pixellab": {
        "serverUrl": "https://api.pixellab.ai/mcp",
        "headers": {
          "Authorization": "Bearer <PIXELLAB_SECRET>"
        }
      }
    }
  }
  ```

  Antigravity's current MCP docs document literal custom-header values but neither environment-variable expansion inside `headers` nor a secret store for custom bearer headers. This preview is not ready to use: do not claim the placeholder will expand, and require the user to replace it locally outside chat before reload. Apply section 2's literal-header credential handling and `both`-mode requirements, reload from the MCP UI or `/mcp`, then verify per section 5.

- **Cursor, VS Code Agent Plugins, Gemini CLI, GitHub Copilot CLI, or any other named MCP-capable app**: do not invent config syntax. Use the app's settings UI/docs, PixelLab's MCP page, or an exact path/format the user provides. Always show a token-free preview and ask before writing. A named app not listed here (e.g. Zed, Windsurf, an in-house agent) still gets this generic handling — do not route it to Manual just because it is unlisted.
- **No app named or identifiable**: route to Manual — open or link `https://www.pixellab.ai/mcp` and stop unless the user returns with a known app name, exact settings screen, config path, or documented MCP format. Do not guess config paths or syntax.

## 4. Before any write

Any write — MCP config, env settings, shell profiles, or a loader-backed project-local secret file — needs explicit confirmation first. Avoid user project files unless the user explicitly chose a loader-backed path. If the user only wants instructions, write nothing. Before asking, report:

- **Mode**: MCP + API, MCP only, API only, or Manual.
- **Exact destination**: config file, app setting, env var, app secret store, or loader-backed project-local secret file.
- **Secret handling**: token-free placeholder or `PIXELLAB_SECRET` reference only — never a literal value.
- **Preview**: endpoint, transport/header shape, and secret reference, with no literal token.
- **Reload**: whether a terminal, app, or assistant/editor must restart.

Then get explicit approval before changing anything.

## 5. Verify without spending credits

Diagnose before changing anything, keeping checks narrow to the user's stated environment. The broad diagnostics in this paragraph apply only after a mode is chosen; before mode selection, limit any readiness note to the ambient signals in this section's last paragraph. For MCP readiness: whether PixelLab MCP tools are already available (match by suffix if prefixed), whether the app and its target settings screen or config file are known, whether a config path was explicitly provided or a specific likely path approved, and whether the app can pass `PIXELLAB_SECRET` from an env var or secret setting. For API readiness: whether `PIXELLAB_SECRET` is present and non-empty (checked as below), whether network access to `https://api.pixellab.ai/v2` is available when a live check is requested, and whether the session where Pip runs can see the same `PIXELLAB_SECRET` source.

Verify only after the user approves a no-credit check; never spend credits during setup. Before it, confirm it uses the locally configured credential, and state that the token value will not be printed and that no generation or edit will run.

- **MCP**: `get_balance` when tools are exposed — verifies MCP auth without generating.
- **REST v2**: `GET /balance` with `Authorization: Bearer <PIXELLAB_SECRET>` — never print auth headers or full JSON.
- **Tool availability**: list or identify PixelLab MCP tools (match by suffix if prefixed) without generation calls.

Check `PIXELLAB_SECRET` presence without outputting, logging, measuring, transforming, or inspecting the value — test only whether it is non-empty and emit a status word such as `set`/`not set`, never the value, and pass the value only to the approved check. For a readiness note before mode selection, check only whether the live `PIXELLAB_SECRET` environment variable is visible to the current process and whether PixelLab MCP tools are already visible in this session (already-loaded tools only — no config inspection); do not inspect project-local secret files, broad config directories, or recursive paths.

After the check, report success/failure, the surface checked, and whether credentials were found; summarize any balance without raw headers or full JSON. On failure, name the likely layer: missing env var, app not reloaded, auth rejected, network failure, endpoint unavailable, or tool mismatch.

**Never scan broad locations.** Do not scan home, auth, shell history, keychain, credential, config, project, or repository directories, and do not recursively search for token/secret/auth/env names. Inspect credential-bearing config only at exact paths the user named or approved after you explain why. Non-secret readiness checks may inspect only active-workspace files needed for the task.

## 6. Output

Keep wording friendly, action-oriented, agent-agnostic, OS-agnostic, and in the user's language (for non-English requests follow `localization.md`); prefer "Next step" over long diagnostics; say "assistant", "editor", "app", or the product name, not "host". Do not show OS/shell/package-manager/SDK/framework/language setup commands unless the user asks for a specific manual secret-storage path. When the app has no secret-settings UI (many CLIs and generic agents), storing `PIXELLAB_SECRET` as a user-level environment variable is itself the manual secret-storage path: offer the user both ways per `credentials.md` — the OS settings dialog where one exists (Windows; friendliest, history-safe) and a placeholder terminal command — never a literal token, and include the new-shell-inheritance caveat so the user does not verify from a stale session.

Include the account step (defined in section 2) whenever `PIXELLAB_SECRET` is missing or unknown, a Secret was pasted or must be rotated, a write or MCP registration is proposed while the Secret is still missing, or an unsafe path is refused (broad scans, `.env*` scans, session tokens, assistant-visible commands). If MCP registers but the Secret is still missing from the session, say PixelLab is registered but not ready for live use until `PIXELLAB_SECRET` is set and the app is reloaded. If the user asks for no writes, stay instruction-only but still include the account step.

Compact templates (`[account step]` = the account-step sentence from section 2; `[command]` = the app's token-free MCP preview from section 3):

- **Already configured**: "PixelLab is ready — MCP tools are connected and `PIXELLAB_SECRET` is available for REST v2 fallback. I can run a no-credit balance check to confirm (no token printed, no credits spent), or leave it as is."
- **Codex preview, Secret missing**: "Codex can register PixelLab MCP with a token-free config that references `PIXELLAB_SECRET`: [command]. Before live use, [account step] Should I run the registration command?"
- **Codex registered, Secret missing**: "PixelLab MCP is registered in Codex but not ready for live use — `PIXELLAB_SECRET` is not visible in this session. [account step] Then restart/reload Codex."
- **API-only / MCP + API, Secret missing**: "[account step] Then Pip can use the same Secret for documented REST v2 fallback when MCP tools are unavailable or insufficient."
- **MCP-only, user-chosen hardcoded token**: "This can make MCP work, but it stores the raw Secret in local MCP config or shell history and does not configure `PIXELLAB_SECRET` for Pip's REST v2 fallback. Replace the placeholder yourself in an external terminal; do not paste it here."
- **Pasted Secret**: "I cannot use a Secret pasted here — treat it as exposed and replace it. Repeat the account step for a fresh Secret; do not paste it here."
- **Unsafe scan or session token**: "I will not scan broad secret locations or use browser/session tokens. If you pasted a session token here, treat it as exposed and sign out or rotate it. [account step]"
- **No writes while auth incomplete**: "I will not write anything. [account step] I can show token-free setup previews only."
- **Manual**: "Open `https://www.pixellab.ai/mcp` and follow PixelLab's instructions. I will stop here."
- **Manual with auth**: "Open `https://www.pixellab.ai/mcp` and follow PixelLab's instructions. If it asks for auth, [account step] I will stop here."

Report outcome briefly: detected mode; readiness (ready, partially ready, not configured, blocked, unknown); credential location type (env var, app secret setting, secret store, literal config value, or not found — never the value); next safe step; any proposed write with destination and token handling; reload need; and what the no-credit check verified.

## Setup guardrails

- Do not scrape browser storage or session cookies, or use website/Supabase/browser session tokens for REST or MCP.
- Do not call undocumented internal endpoints (website or Aseprite extension) as setup verification.
- Do not claim SDK support, MCP tool availability, pricing, limits, or endpoint behavior without checking when those facts matter.
- Do not require Pip-specific behavior from apps that only support generic MCP or REST.

# Style Reference Generation

Read this for MCP `create_image_pro` style-image input, REST `generate-with-style-v2`, website/Aseprite "Create image from style reference (pro)", or any request where a supplied image should define visual style, pixel size, palette, rendering, or sheet layout without preserving the exact subject identity.

## REST `generate-with-style-v2` Size Handling

For REST `POST /generate-with-style-v2`, do not send `image_size`. The current schema retains it only as an optional deprecated property marked as removed; it is not a supported output-size control. The endpoint always derives a square output from the supplied style images:

- Inspect all style images and use the largest dimension across them as the effective output size, bounded to `16`–`512` pixels.
- Non-square style images are centered on the square output canvas. Do not scale, stretch, crop, or redraw them to choose a different output size.
- If the desired asset occupies a non-square region inside the square output, state that usable region in the prompt and require the remaining area to stay transparent.
- If the user asks for an output size that differs from the style images, this endpoint cannot honor an independent size; preserve the supplied references and choose a route with an explicit size control, or ask for replacement references at the desired scale.

For website/Aseprite workflows, or a local preparation task that explicitly requires a square style image, pad a copy of each non-square reference to its native largest dimension with transparent pixels and keep the original pixels centered. This local preparation rule does not create a REST `image_size` field.

## Reference Count And Batch Size

Do not maximize the number of generated subjects by enlarging the canvas. For style fidelity, preserve the style reference's scale first.

For `generate-with-style-v2`, output count is tied to the deduced square size buckets in the public docs:

- `16-42`: 64 images
- `43-85`: 16 images
- `86-170`: 4 images
- `171-512`: 1 image

When the style reference's target size yields one image, generate one output asset, or one requested sheet/atlas, per request unless the user explicitly accepts a packed multi-asset atlas. A packed atlas competes with scale, layout, and style fidelity.

## Prompting

The prompt should preserve observed style facts from the reference without introducing conflicting generic style labels. Inspect the style image before writing the prompt and describe what is visible: subject proportions or form factor, pose/view when relevant, silhouette shape, bounds inside each cell or canvas region, palette, outline treatment, texture/material cues, and shading.

For sheet references, include exact structural facts: canvas footprint, cell size, row/column meaning, subject bounds inside each cell, perspective, and transparent padding.

Never add inferred style labels such as `chibi`, `super-deformed`, `RPG Maker`, `front-facing`, `large readable sprite`, or `panel` just because the image is small pixel art. Use those words only when the user says them or the reference visibly supports them. If the reference shows realistic or elongated proportions in a tiny sprite, say that instead.

State when the supplied image is only a style/layout reference and not a subject/identity reference. If the user says not to recreate the reference subject, include a concise negative subject constraint in `description`.

For managed 8-direction assets, MCP `create_character(mode="pro", style_character_id=...)` / REST `create-character-pro.style_character_id` and MCP `create_8_direction_object(style_object_id=...)` / REST `create-8-direction-object.style_object_id` can reuse an existing completed character or object as the style source. The requested output size must fit the visible reference sprite. Character style-ID mode is incompatible with `rotate_character`; object style-ID mode uses the styled object's south view as the center reference unless an explicit reference/style image overrides it.

## Verification

After generation, verify:

- REST output dimensions equal the square size deduced from the style images, not a separately requested `image_size`.
- Transparency was preserved in unused padded areas.
- Visible content remains at the reference-relative footprint and scale.
- For sheet outputs, rows, columns, and cell occupancy match the requested structure.
- Requested palette, outline, detail, and shading visibly match the reference; accepted options alone
  do not prove adherence.
- The generated subject does not copy a style-only reference subject when the user prohibited it.

## Hard projection or orientation requirements

When a view or facing direction is a hard requirement, preserve the user's subject and category.
Use the shortest useful description that names the requested subject and required view or
orientation; do not substitute a familiar category or add unrequested details.

If text-only output misses the requirement, use a neutral guide that visibly demonstrates the
required view, facing cue, and framing. With MCP, pass it as `style_image_url` or
`style_image_base64`; with REST, use `generate-image-v2` for a `style_image` or
`generate-with-style-v2` for `style_images`. A guide can preserve the structural cue while
pulling output toward its own geometry, so do not use a distinctive generated asset as a guide
when novel geometry matters.

Verify the hard requirement before judging style: requested subject/category; requested
view/orientation and its defining cues (for example, a building's front facade and entrance on the
requested side); one whole centered asset with expected size/transparency; no clear text or
watermark; and no unwanted copy of a style-only reference. Change route after a structural failure
instead of repeatedly adding prompt exclusions.

Keep guides role-specific when their visual cues could bias a different asset class. Do not reuse an
architecture-specific building guide for characters; use a character-appropriate guide when a
character's view or pose needs anchoring.

### High-oblique Tibia-style item perspectives

For a steep, side-turned inventory camera, prefer MCP `create_image_pro` with an
accepted sprite that already has the desired composition in `style_image_base64`.
Add two native-size square style references for palette, outline, detail, and
shading context. Keep the request at the target size with `no_background: true`,
and describe the plane relationship directly: a dominant tall near-facing plane,
a narrow side plane receding down-right, a thin upper/lid edge, and the front
detail on the near plane. Exclude top-down, bird's-eye, visible-top,
conventional three-quarter, isometric, and front-only interpretations.

Treat descriptive `reference_images` roles as contextual guidance, not a hard
camera lock. If the camera must be preserved exactly, use `edit_image` with the
geometry source and a separate appearance reference. Review every returned
alternative because Pro can still mix projections. See the [Tibia high-oblique
research spike](../../../docs/pixellab/pixellab-tibia-high-oblique-perspective-mvp-research-spike.md)
for the experiment matrix and universal MVP prompt.

# Tilesets

Read this for tilesets, isometric tiles, tile variants, and ambiguous tile requests.

## MCP Route Inputs

Multi-shape connectable terrain transition:

- Use MCP `create_tiles_pro` or REST `POST /create-tiles-pro` with `tile_feature="tileset"` only when the user explicitly requests a hex, isometric, or oblique connectable terrain transition, or explicitly requests tiles-pro tileset mode. Plain `create_tiles_pro` generates independent tile variations, not an autotiling tileset; never omit `tile_feature="tileset"` for a connectable-set request.
- Put the ordered terrain pair in `description`, such as `grass to water`; the first terrain is the main terrain and the second surrounds it.
- `tile_type` supports `square_topdown`, `isometric`, `hex`, `hex_pointy`, and `oblique` in tileset mode. Square top-down, isometric, and oblique return a 16-tile corner set; hex shapes return a 32-tile coastline set.
- Shape controls are `tile_size` (connectable sets have tighter per-shape ranges than plain variants, and square top-down roads are exactly 32), `tile_view_angle`, `tile_depth_ratio`, `tile_flat_top_px` (isometric), `oblique_lean` (oblique), and `outline_mode`. `create_tiles_pro` exposes no boundary-raggedness or raised-terrain-height fields; do not map those concepts to another tiles-pro control.
- `style_images` cannot be combined with `tile_feature="tileset"`. For square top-down requests, supplied per-terrain reference images and palette controls require REST `create-tileset`; the MCP top-down schema does not expose those inputs.
- Poll MCP `get_tiles_pro(tile_id)` or REST `GET /tiles-pro/{tile_id}` for completion and per-tile placement rules.

Shared MCP controls on the top-down and sidescroller routes (not `create_tiles_pro`):

- `tile_size`: tile dimensions; sidescroller supports 16 or 32, top-down supports 16 or 32 in `standard` mode and 64 in `pro` mode.
- `transition_size`: amount of transition/top layer; use route-specific meaning below.
- `detail`: `low detail`, `medium detail`, `highly detailed`.
- `shading`: `flat shading`, `basic shading`, `medium shading`, `detailed shading`, `highly detailed shading`.
- `outline`: `single color outline`, `selective outline`, `lineless`.
- `text_guidance_scale`, `tile_strength`, `tileset_adherence`, `tileset_adherence_freedom`: generation controls.

Top-down MCP `create_topdown_tileset` route:

- Required terrain fields: `lower_description`, `upper_description`.
- Optional transition field: `transition_description`.
- Base tile fields for chaining: `lower_base_tile_id`, `upper_base_tile_id`.
- Route-only fields: `mode` (`standard` or `pro`), `view` (`low top-down` or `high top-down`), `shape_style` (`square` or `round`), and `enhance`. Leave `shape_style` omitted unless the user explicitly requests one of those boundary geometries; it is a structured geometry control, not a prompt-style hint. `shape_style` is `mode="standard"` only — sending it with `mode="pro"` is rejected, because pro's own shape controls are `spread_x`/`slope_size`/`raggedness`.
- Pro-only shape fields: `spread_x`, `slope_size`, `raggedness`.
- `enhance` (default `true`, `shape_style` tilesets only) rewrites the terrain descriptions before generation, and the stored tileset keeps the rewritten text, so a chained tileset reuses it. Set `enhance: false` when the user's exact wording must reach the model, and report which was used.
- No `seed`: the MCP top-down route exposes none, so route reproducible top-down runs to REST `create-tileset`, which does.
- `transition_size` controls terrain blending/height behavior for top-down tiles. MCP documents it as a float and cites 0.0, 0.25, 0.5, and 1.0; with explicit `shape_style`, it is continuous from 0 to 1 and values above 0.5 use an extended 4x8 sheet. Verify the returned layout before treating it as a compact 4x4 atlas. REST-specific validation is stricter: without `shape_style`, it accepts only those four values; its `shape_style` description supports square 16px or 32px tiles.

Sidescroller MCP `create_sidescroller_tileset` route:

- Required platform body field: `lower_description`.
- Required platform surface/top field: `transition_description`.
- Base tile field for chaining: `base_tile_id` (REST `create-tileset-sidescroller` names it `lower_base_tile_id`).
- Route-only field: `seed`.
- No `upper_description`, `view`, `mode`, or Pro-only shape fields are exposed by the current MCP sidescroller tool.
- `transition_size` controls how much of the surface/top layer appears on the platform tile; documented examples include 0.0, 0.25, and 0.5.

Isometric MCP `create_isometric_tile` route:

- Required content field: `description`.
- Primary shape field: `tile_shape`; use `thin tile` for floor slabs, `thick tile` for raised platforms, and `block` for cubes, chunky objects, or full-height terrain blocks (default `block`) — same three values as REST, not shortened on MCP.
- Other common controls include `size`, `outline`, `shading`, `detail`, `text_guidance_scale`, and `seed`.
- REST `create-isometric-tile` uses different field *names* for the same ideas: `image_size`, `isometric_tile_size`, and `isometric_tile_shape`, with the identical values `thin tile`, `thick tile`, or `block`.

Path/road and building-kit MCP routes:

- `create_path_tiles` (18-config connectable path/road set) and `create_building_kit` (floor, connectable walls, doorways, pillar, stairs) are siblings of `create_tiles_pro`, not `create_topdown_tileset` — all three share `get_tiles_pro`/`list_tiles_pro`/`delete_tiles_pro`; there is no separate getter/lister/deleter for path tiles or a building kit.
- REST folds all three into `create-tiles-pro` via `tile_feature`: `"roads"` (path tiles), `"tileset"` (the connectable terrain transition `create_tiles_pro` itself can produce), or `"building"` (building kit, with the `building_*` fields).
- On REST isometric `create-tiles-pro` requests, `tile_flat_top_px` controls the top/bottom cap: `2` is classic and `4` is modern. It is ignored for non-isometric `tile_type` values.

## Human Label To API Mapping

Map only non-obvious request wording to structured parameters.

These labels are not symmetric with the MCP parameter names:

| Human UI wording | Applies to | MCP parameter | Notes |
|---|---|---|---|
| `Top tile description`, `Top Tile` | `create_sidescroller_tileset` | `transition_description` | Sidescroller MCP calls this the top decoration/surface layer. Not the same as `transition_size`. |
| `Center tile description`, `Center Tile`, `platform center` | `create_sidescroller_tileset` | `lower_description` | Sidescroller MCP calls this the platform material/body. |
| `Target palette`, `palette`, `1-bit palette`, `Game Boy palette` | `create_tiles_pro`, `create_topdown_tileset`, `create_sidescroller_tileset` | no current MCP parameter | If no palette/control image field is exposed, say palette is not enforced by MCP generation alone and plan an approved palette-control or palette-clamp route. |

Do not reinterpret `upper`, `lower`, `inner`, `outer`, `floor`, `wall`, `transition`, or `terrain pair` as sidescroller center/top layers without side-view intent. For an explicit Create Image Pro packed texture sheet or small-cell image grid, route to `create-image-pro.md`; do not treat it as an autotile tileset just because the user says tiles.

## Generation Controls

Treat structured API fields as controls, not prompt text. Change a control only when the user asked for it, the route requires it, a documented default must be supplied, or a verified failure mode calls for it; do not infer control values from descriptive words that can live safely in `lower_description`, `upper_description`, or `transition_description`. When the user asks for maximum/100%/forced text guidance, map that to the maximum valid `text_guidance_scale`; do not also change `transition_size`, `tile_strength`, `tileset_adherence`, or `tileset_adherence_freedom` unless requested or the failure mode calls for it.

Treat `outline`, `shading`, and `detail` as weak style controls, not deterministic placement controls: PixelLab docs say each "Weakly" controls its aspect, affecting taste, texture, color variation, and contour strength without guaranteeing exact edges, palette, or texture density. For placement or material changes, adjust terrain/transition descriptions and `transition_size` first.

Exception to the rule above: for any MCP or REST route that exposes `transition_size`, use `transition_size: 0.5` when the user requests or implies a transition but does not specify its size. Do not infer `transition_size: 1.0` from `wall`, `dithered`, `textured`, `black and white`, `max text guidance`, or similar wording.

For REST top-down tilesets, `lower_reference_image`, `upper_reference_image`, and `transition_reference_image` are stronger composition/style controls than `color_image`. Do not add them just because the user names a material, texture, wall, or floor; use them when the user supplies a reference, asks for one, or approves a retry after a miss. Treat `transition_reference_image` as a style reference, not a mask or stamp; keep `text_guidance_scale` at default unless the text matters more than the reference (high text guidance competes with it and worsens palette drift). Author a local reference in single-tile context at the requested `tile_size` — a 16x16 tileset uses a 16x16 reference, and at `transition_size: 0.5` place the pattern in the 8-pixel band, not scaled to the full 4x4 sheet.

`color_image` constrains the palette, not where colors or texture appear inside each Wang tile; put texture placement in the terrain's description, not only the transition description. When `color_image` is requested or approved for top-down REST tilesets, prepare it as 64x64 unless current behavior proves another size works: the validator may accept a smaller PNG but the background job can fail later with an internal `Expected image of size 64x64` error. On that failure with a smaller/unknown palette image, retry once with a 64x64 `color_image` when budget allows, and report it as a PixelLab validation/background-job caveat. This 64x64 rule applies to `color_image`, not terrain/transition reference images.

## Strict 1-bit / Exact Palette Work

Tileset generators do not reliably enforce strict 1-bit black-and-white output from text alone, even at high `text_guidance_scale`. Treat `1-bit`, `black-and-white only`, `no gray`, and named exact palettes as palette requirements unless the user explicitly accepts approximation.

- Prioritize PixelLab-generated shape over raw palette: palette clamping can make a good shape exact black/white but cannot fix a wrong silhouette, exposed edge, center-tile seam, or misplaced transition without locally altering the art.
- Prefer standard mode over Pro for strict 1-bit top-down wall/floor tests: Pro outputs can expand at `transition_size: 0.5`, while standard mode is the safer compact 16-tile path.
- When a 1-bit tileset is requested and the route exposes style controls, default any unspecified ones to `detail: low detail`, `shading: flat shading`, and `outline: lineless`; preserve explicit user-supplied values.
- If the route exposes a palette/control image field, use or ask for it. Otherwise state the limitation before generating, or deliver an honestly labeled palette-clamped derivative via `aseprite-cli.md` after saving the untouched original; report the original separately and do not imply the derivative is the raw PixelLab result.
- Do not treat a black/white `color_image` as the default 1-bit fix: it can erase white transitions on black terrain. Verify raw PixelLab shape first, then palette-clamp for exact black/white derivatives.
- Top-down terrain transitions are more reliable than sidescroller generation for full connected-shape white outlines. Do not burn repeated sidescroller prompt-only attempts on that outline goal without a new control route or user-approved post-process.
- For exact niche constraints (strict palettes, monochrome, single-pixel rims, whole-shape sidescroller outlines), run a small proof test before batching. On a miss, suggest post-processing, reference/control routes, another PixelLab image route, or human-authored assets.

## Fetching Results (top-down)

On the MCP route, poll `get_topdown_tileset(tileset_id)` — it returns status, tile data, download links, and base tile IDs directly, with no separate preview-vs-final split. On the REST route, fetch both result surfaces: poll `GET /background-jobs/{background_job_id}` for preview fields, then use `GET /tilesets/{tileset_id}` for the actual tile set, metadata, and generation parameters. The final user-facing tileset for a 16-tile result is the 4x4 sheet in the dual-grid (`15-tileset`) format, assembled from the tiles' `image` data in the exact order returned by the getter (`get_topdown_tileset` or `GET /tilesets/{tileset_id}`); name it plainly, such as `tileset.png` or `tileset-4x4.png`. A 25-tile result uses a 4x8 sheet in the same returned order; do not repack it as 4x4. Do not sort the tiles by `wang_N`, `original_position`, corner pattern, or any other inferred index, because those layouts can scramble the usable sheet. Decode the returned tile PNGs in memory for this sheet; do not save separate per-tile PNG files unless the user asks for individual tiles or a package.

The background job `last_response` may include full-sheet `image` and `quantized_image` fields; treat these as previews, not the final sheet. Save/show `image` as the primary preview (more likely to match the final tiles) and `quantized_image` as secondary. These fields may be base64 raw RGBA buffers rather than PNG, so decode and convert before writing PNGs. Public REST docs expose no tileset ZIP/export endpoint for Wang, dual-grid 15-tileset, or 3x3 formats; use the returned tile PNGs for local packaging only when the user asks.

# Uninstall

Reference for natural-language removal: taking Pip out of an assistant/editor/app using whatever method installed it. This extends the existing Pip skill; it is not a separate skill. Uninstall is destructive, so confirmation before removal is the core of this contract.

The command is one word after the trigger, such as `/pixellab-pip uninstall`, `@pixellab-pip uninstall`, or `$pixellab-pip uninstall`. Some apps pass it as an argument, others as prose; treat it the same either way and require no flags or app-specific syntax.

## 1. Detect the install method first

Stay agent-agnostic and OS-agnostic until the app is named or detected; do not assume an app, OS, shell, or path. Pip is installed for an app in one of three shapes — remove via the same shape it was installed with:

- **Marketplace plugin / extension** — installed through the app's plugin or extension mechanism. Remove with that app's own uninstall command (section 2).
- **Manually-copied skill folder** — a `pixellab-pip` folder copied into a skills directory the app reads. Remove by deleting that one folder (section 2).

If you cannot tell which shape applies, ask, or use the app's documented listing command to check (e.g. `/plugin` list, `extensions list`) before acting. Never scan broad locations to discover an install — act only on the app's own uninstall command or a known skill path.

## 2. Per-app uninstall mechanics

Use the app's documented mechanism; if unsure of exact syntax, check its help/refresh its plugin list rather than guessing. Prefer the non-interactive CLI form (e.g. `claude plugin …`, `codex plugin …`) and run the removal yourself once the user approves; only hand the user an interactive in-app command when the app has no CLI. The marketplace is `pixellab-pip-plugins` and the plugin is `pixellab-pip`.

- **Claude Code**: `claude plugin uninstall pixellab-pip@pixellab-pip-plugins`. Optionally also remove the marketplace: `claude plugin marketplace remove pixellab-pip-plugins`.
- **Codex**: `codex plugin remove pixellab-pip@pixellab-pip-plugins`. Optionally `codex plugin marketplace remove pixellab-pip-plugins`.
- **Gemini CLI**: `gemini extensions uninstall pixellab-pip`.
- **GitHub Copilot CLI**: `copilot plugin uninstall pixellab-pip`. Optionally `copilot plugin marketplace remove pixellab-pip-plugins`.
- **Cursor**: remove it through Cursor's plugin marketplace/management flow, or delete the copied skill folder (`.cursor/skills/pixellab-pip`).
- **Antigravity CLI**: delete the copied skill folder (e.g. `~/.gemini/antigravity-cli/skills/pixellab-pip`); or, if you installed it through the Antigravity CLI plugin manager, `agy plugin uninstall pixellab-pip`.
- **OpenCode, Deep Code, Antigravity IDE/2.0, or any manual skill-copy install**: delete the `pixellab-pip` skill folder from the skills directory the agent reads — e.g. `.opencode/skills/pixellab-pip`, `~/.agents/skills/pixellab-pip`, `.claude/skills/pixellab-pip`, `.cursor/skills/pixellab-pip`. If Pip was installed as an Antigravity custom plugin, delete its `pixellab-pip` plugin folder from Antigravity's plugins directory instead.
- **Any other named app**: use its documented plugin/extension uninstall command, or delete the copied skill folder. Do not invent syntax.

## 3. Confirm before removing

Uninstall is destructive. Report exactly what will be removed and get explicit approval before removing anything. Any bulk or broader-than-default removal needs its own explicit scope confirmation.

Before asking, report:

- **Method**: marketplace/plugin uninstall command, or delete a named skill folder.
- **Exact target**: the plugin/marketplace name, or the full skill-folder path.
- **Config entries touched**: which config entries the uninstall removes (none, for a plain folder delete).
- **Reload**: whether the app must restart or reload for the skill/tools to disappear.

By default remove **only** the Pip skill/plugin and its config entry. Keep everything that belongs to the user, unless they explicitly ask to remove it too:

- the `pixellab-pip-generations/` output folder and any generated assets in it,
- the user's remote PixelLab assets (characters, animations, tilesets, etc.),
- `PIXELLAB_SECRET` and any stored PixelLab credential.

## 4. Optional opt-in extras

You MAY offer, as separate explicit opt-ins never applied automatically:

- Removing a leftover `pixellab` MCP server config entry (the entry `setup.md` may have created), only from a config path the user names or approves.
- Unsetting `PIXELLAB_SECRET`. Never print, read, or echo the value while doing so — follow `credentials.md` for anything touching the Secret.

Offer each only after the default removal, and only if the user asks or agrees. Never scan broad locations to find these — act only on the known install path or a config path the user provides.

## 5. Reload after removal

Tell the user to restart or reload the app only if it requires that for the skill/tools to disappear (many apps drop a removed plugin or deleted skill folder on next launch, some need a manual reload). Do not tell them to restart when the app clears it live.

## 6. Verify after

Confirm Pip is gone, agent-agnostic: it is no longer listed by the app's plugin/extension/skill listing, or the skill folder no longer exists at its path. If PixelLab MCP tools were removed with it, confirm they are no longer exposed. Report what was removed, what was kept (the user's outputs, remote assets, and Secret unless they opted to remove them), and any reload still pending.

## Uninstall guardrails

- Confirm before any removal; never remove without explicit approval, and never remove more than the default scope without separate confirmation.
- Never delete the user's `pixellab-pip-generations/` folder, generated assets, remote PixelLab assets, or `PIXELLAB_SECRET` unless the user explicitly asks.
- Never scan broad locations to find what to delete; act only on the app's own uninstall command or a known install path.
- Never print, read, or measure the Secret when offering to unset it; follow `credentials.md`.

# Update

Reference for natural-language updates: bringing an installed Pip up to the latest version using whatever method installed it. This extends the existing Pip skill; it is not a separate skill. Update only replaces skill/plugin files — it never touches the user's `PIXELLAB_SECRET` or their `pixellab-pip-generations/` outputs.

The command is one word after the trigger, such as `/pixellab-pip update`, `@pixellab-pip update`, or `$pixellab-pip update`. Some apps pass it as an argument, others as prose; treat it the same either way and require no flags or app-specific syntax.

## 1. Detect the install method first

Update via the same method that installed Pip; do not assume. Three shapes exist:

- **Marketplace plugin** — installed through the app's plugin/marketplace command (plugin id `pixellab-pip`, marketplace `pixellab-pip-plugins`).
- **Extension** — installed through the app's extension mechanism.
- **Manual skill copy** — the `skills/pixellab-pip/` folder copied into the app's skills directory, or an extracted release zip.

Detect from what the app exposes (an installed-plugin list, an extensions list, or a skill folder on disk) before choosing an update path. If detection is ambiguous, ask which way the user installed it rather than guessing. If unsure of an app's exact command, use the app's own documented update mechanism or refresh its plugin/extension list — do not invent syntax.

## 2. Per-app update mechanics

Stays agent-agnostic and OS-agnostic until the app is named or detected. The commands below are the documented mechanism for each app; use the named/detected app's mechanism only. Prefer the non-interactive CLI form and run the update yourself; only hand the user an interactive in-app command when the app has no CLI.

- **Claude Code** (marketplace): refresh the marketplace, then update the plugin.

  ```text
  claude plugin marketplace update pixellab-pip-plugins
  claude plugin update pixellab-pip@pixellab-pip-plugins
  ```

  Claude's `plugin update` needs the qualified `plugin@marketplace` id — the bare `pixellab-pip` reports "not found".

- **Codex** (marketplace): upgrade the marketplace, then remove and re-add the plugin.

  ```text
  codex plugin marketplace upgrade pixellab-pip-plugins
  codex plugin remove pixellab-pip@pixellab-pip-plugins
  codex plugin add pixellab-pip@pixellab-pip-plugins
  ```

- **Gemini CLI** (extension):

  ```text
  gemini extensions update pixellab-pip
  ```

- **GitHub Copilot CLI** (marketplace):

  ```text
  copilot plugin update pixellab-pip
  ```

- **Cursor**: if installed via its marketplace, re-index/update it through that flow; otherwise re-copy the skill (below).
- **OpenCode, Deep Code, Antigravity, VS Code Agent Plugins, or any manual skill-copy install**: re-copy the entire latest `skills/pixellab-pip/` folder (every file, not just `SKILL.md`) over the existing install, or re-download and extract the latest release zip. Overwrite in place; do not delete sibling files first.
- **Any other named marketplace/extension app**: use the app's own documented update or refresh command with plugin id `pixellab-pip` / marketplace `pixellab-pip-plugins`. Do not invent syntax; fall back to the skill re-copy when no update command exists.

## 3. Restart or reload

Tell the user to restart or reload to activate the updated version — many apps load plugins and skills at startup, so the running session keeps the old version until then; a few pick up the change live. Also restart if the new version does not appear.

## 4. Verify and report the version

Must confirm the update landed and report the installed version number. Read the version from a plugin manifest's `version` field (`plugin.json`), or the app's plugin/extension list; confirm via that list, the app's version display, or (skill-copy) the files at the install path. Version check only — no credit spend, no secret handling.

## Update guardrails

- Update replaces only skill/plugin files. Do not read, move, rewrite, or clear `PIXELLAB_SECRET` or the `pixellab-pip-generations/` folder.
- Do not guess the install method or invent an app's update syntax; detect or ask, then use the app's documented mechanism.
- Do not spend credits or run any generation, edit, or animation as part of an update or its verification.

# Usage Reporting

Read this after live PixelLab calls when preparing the final user report or a generation manifest. For polling, MCP review state, rate limits, and expiring download URLs, read `job-lifecycle.md`. Once the job returns image(s), apply the bark contract per SKILL.md, then give this report.

## Report Shape

Use this order for completed work, including work that completed but failed verification — then say plainly that verification failed. Omit sections and lines that do not apply; list only files that were actually produced. Do not narrate the process that led here.

```markdown
Done - [one plain sentence: what was produced and whether it passed verification.]

**Files**
- [Frames / image](path-or-url)
- [Spritesheet](path-or-url)
- [other artifacts only if actually produced, e.g. ZIP package, Manifest]

**Route**
- Surface/tool: `MCP create_1_direction_object` or `REST POST /v2/generate-image-v2`
- Output structure: `Atlas image` (one image containing the grid/sheet), `Separate images`, `Single image`, or `Animation frames`; add `Selection state: Drafts` when candidates still need selection
- Asset lifecycle: `Managed asset` when backed by a PixelLab/MCP asset ID, plus the retrieved shape when useful, e.g. `Managed tileset; tile PNGs assembled locally into a 4x4 sheet`
- Prompt prep: user wording preserved, agent-enhanced, inline `enhance_prompt`, or enhance endpoint

**Inputs Used**
- `description` / `action` / other natural-language fields: the exact final text sent, or a redacted summary plus the local Manifest link for secrets, personal data, or user-identified confidential content
- Image/frame fields that anchored the result, by API field name: `image`, `first_frame`, `last_frame`, `reference_image`, `style_image`, `init_image`, `mask_image`; note omissions that change interpretation, e.g. `last_frame: omitted`
- Seed: the seed sent, the resolved seed returned, `multiple, see Manifest`, or `omitted` when none was sent
- Non-default settings that materially affected the output: size, view/direction, count, mode/product label, `no_background`, frame count/timing, palette, reused base asset

**Cost**
- Total: [per-call usage from PixelLab, or the observed cost delta]

**Verified**
- [short checklist of the constraints the user actually asked for]
```

Two rules that always apply:

- Account for every final natural-language field sent to PixelLab (`description`, `action`, `edit_description`, `style_description`, `negative_description`, `item_descriptions`, `text`, `color_palette`) in Inputs Used, even when the output failed verification or the field seems obvious. Never repeat secrets, personal data, or content the user identified as confidential in chat; show a redacted summary instead, warn that the local Manifest contains the exact value, and link it. For all other values, show the exact final text so the user can verify the request. If a value is merely too large for chat, label it truncated and link the manifest/request file holding the full text. For a non-English user, translate only the non-redacted visual prompt text per `references/localization.md`; apply the same redaction to talking dialogue.
- Report settings that materially affected the output; do not dump schema defaults.

Use Markdown links with user-facing labels (`Spritesheet`, `ZIP package`) for every listed file. Files live under the project `pixellab-pip-generations/` folder per SKILL.md; copy temporary URLs or cache paths there before reporting them as local outputs.

OpenCode does not render inline images in chat. Open the output folder.

For REST routes, report the exact public path used, with the `/v2` prefix and without collapsing create and retrieval routes: `REST POST /v2/create-tileset`, `GET /v2/tilesets/{tileset_id}`.

If local assembly produced a sheet/GIF/package, state that PixelLab produced the underlying images and that assembly preserved original pixels.

For cost, prefer per-call `usage` totals for the whole flow. If only balance is available, use `get_balance` / `GET /balance` before and after (no extra permission needed once live work is approved) and report the delta — but if other PixelLab jobs may have run concurrently, label the delta as an overlapping observation rather than the cost of this job. Never derive cost from the number of calls or images — one call is not one generation, and `pro`/quality tiers and multi-output jobs cost several; take the figure from `usage.generations` in the response or the measured balance delta, not a guessed count. If neither is exposed, say `Cost: not exposed by the tool/API` rather than inventing a number.

Never write a balance figure (`credits.usd`, `subscription.generations`, `subscription.total`) or a `before -> after` pair into a blueprint, manifest, or repo file; chat is fine. `usage.generations` is charged, `subscription.generations` is remaining: the parent key decides, not the magnitude. Always label generation counts as charged, used, remaining, or total allowance; never call a bare count a total or balance.

## Manifest

Write a manifest for every live generation flow. Record per call or per result item (not just top-level):

- `job_id` / `background_job_id`, `asset_id`, and route-specific result/child IDs when present — enough to resume, inspect, or reproduce later.
- `seed`: the seed sent, or the resolved seed PixelLab returned. Any async v2 job you already poll may expose it at `last_response.seed` on `GET /background-jobs/{job_id}` — read it there and store it when present (confirmed on `generate-image-v2` and `animate-with-text-v3`; read rather than assume it for PixMiniMax because the field is not declared in OpenAPI). The sync `create-image-*` routes and async `create-image-pixflux-background` return none. Record `omitted` only when none was sent and none came back; never back-fill a value that was not sent or returned.

## Pending Jobs

If an async call times out or stays pending, keep the job or asset ID and poll the matching status route or MCP getter; do not resubmit a paid generation unless the user explicitly wants a fresh run. If a managed object returns `review` status, report the selection step instead of treating the job as incomplete. Details: `job-lifecycle.md`.

# Talking Portraits And Lip Sync

Read this for stored character portraits, mouth/viseme generation, talking GIFs, or a frame-by-frame lip-sync plan.

## Route Choice

| Need | MCP | REST v2 | Cost and lifecycle |
|---|---|---|---|
| Attach/replace a character portrait | `set_character_portrait(character_id, image=...)`, or `from_job_id` from a completed portrait-character conversion | `POST /characters/{character_id}/portrait` with `image` | Free and synchronous. Replacing an existing portrait is destructive; get explicit approval first. |
| Generate mouth visemes | `create_vocal_animation` then `get_vocal_animation` | `POST /vocal-animation` then dedicated `GET /vocal-animation/{job_id}` | Paid-plan async generation; this is the only credit-spending step in this workflow. |
| Render a talking GIF | `create_talking_gif` | `POST /talking-gif` | Free and synchronous; no polling. |
| Return a lip-sync frame plan | `get_lip_sync` | `POST /lip-sync` | Free and synchronous. MCP requires a managed character; REST also supports stateless `viseme_count`. |

Use either a managed `character_id` with a stored portrait or a raw portrait image for vocal generation, never both. Attached portraits may be 16–256 px; attachment centers a non-square image on a transparent square canvas. Raw vocal input has a documented maximum of 256×256 with no published minimum. Managed generation stores the visemes on the character. Raw generation returns them in the completed result without creating a managed character.

## Vocal Generation

- Supported moods: `neutral`, `happy`, `angry`, `sad`, `surprised`; default `neutral`. Generate one mood per call.
- `viseme_count` is 3, 5, 7, or 12; default 7. Keep the same count across every mood stored on one character.
- `no_background` defaults to `true`. Preserve transparency unless the user requests a background.
- Ask for paid-call approval under the normal cost rules. Setting a portrait, rendering the GIF, and requesting the lip-sync plan are free.
- Poll the dedicated vocal getter every 10–15 seconds. Do not use the generic background-job route. `completed_visemes` may be partial progress; wait for the terminal result and all expected frames.

## Talking Output

Preserve `text` / `text_to_speak` exactly: it is dialogue content, not a visual prompt. Do not enhance or translate it. PixelLab documents Latin-alphabet language support; when the dialogue uses another script, ask the user to approve a transliteration.

Talking GIF timing uses `frame_ms` 20–500 (default 90) and `hold_ms` 0–5000 (default 600); GIF timing is rounded to 10 ms. REST accepts either a managed character or inline visemes; MCP accepts a managed character or `from_job_id` from raw portrait generation. The synchronous response is the final GIF, so save and verify it directly. An MCP `from_job_id` remains available for 8 hours after completion; persist needed output before it expires.

The lip-sync plan returns ordered frames with `viseme`, `column`, `duration_ms`, and `text_offset`. With a managed character it also includes the grid URL and row metadata. REST stateless mode takes `viseme_count`; MCP intentionally has no stateless form. REST timing bounds are `frame_ms` 1–5000 and `hold_ms` 0–10000; both default to 90/600.

Verify portrait dimensions and centering, transparency, requested mood, expected viseme count, full completion, frame order and duration, and the dialogue offsets before reporting success.