mimo2codex 0.1.0

package/dist/util/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/util/sse.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,sBAAsB,CAAC,GAAmB;IACxD,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,kCAAkC,CAAC,CAAC;IAClE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;IACzD,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAC1C,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,OAAQ,GAAgD,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QACxF,GAA+C,CAAC,YAAY,EAAE,CAAC;IAClE,CAAC;IAED,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,CAAC,KAAK,EAAE,IAAI;YACf,IAAI,QAAQ;gBAAE,OAAO;YACrB,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACvE,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,WAAW,OAAO,MAAM,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,CAAC,IAAI;YACV,IAAI,QAAQ;gBAAE,OAAO;YACrB,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,GAAG;YACD,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,MAAM;YACJ,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAQD,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO;QACL,MAAM;QACN,QAAQ;QACR,KAAK,CAAC,KAAK,EAAE,IAAI;YACf,IAAI,QAAQ;gBAAE,OAAO;YACrB,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,IAAI;YACV,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QACD,GAAG;YACD,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,MAAM;YACJ,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/mimoskill/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: mimoskill
+description: Use Xiaomi MiMo V2.5 (the LLM behind mimo2codex) for chat, vision, web search, TTS and ASR — and route around capabilities MiMo doesn't natively support, especially image generation needed for things like Codex Pets `/hatch`. Trigger when the user mentions MiMo, calls into mimo2codex, asks to generate / hatch a Codex pet, asks for image generation while using MiMo as the chat backend, or hits a "no image generation available" / "image_gen tool unavailable" message inside Codex.
+---
+
+# mimoskill — Xiaomi MiMo V2.5 + gap fillers
+
+This skill bundles two things:
+
+1. **Direct MiMo V2.5 access** — recipes for hitting `https://api.xiaomimimo.com/v1` for chat, vision, web search, TTS, and ASR (works whether or not the [mimo2codex](../README.md) proxy is running).
+2. **Workarounds for MiMo's gaps** — concrete scripts for the few things MiMo doesn't do, particularly **image generation** (which is what Codex's `/hatch` pet creation needs).
+
+## When to use
+
+Trigger this skill when:
+
+- User asks to hit MiMo's API directly (chat / vision / web search / TTS / ASR)
+- User asks "how do I generate a Codex pet" / "/hatch isn't working" / "image_gen tool not available"
+- User wants image generation as part of a MiMo-backed workflow
+- User pastes the Codex error: `the image generation tool (image_gen) is not available in this environment` or `the CLI fallback requires the openai Python package`
+- Anything in the `mimo2codex` repo that touches a feature MiMo doesn't support
+
+## What MiMo V2.5 does and doesn't do
+
+Quick answer:
+
+| Capability | MiMo native | Best model | Notes |
+|---|---|---|---|
+| Text chat | ✅ | `mimo-v2.5-pro` | reasoning + tools |
+| 1M context | ✅ | `mimo-v2.5-pro[1m]` | append `[1m]` suffix |
+| Tool / function calling | ✅ | any | parallel calls supported |
+| Vision (image input) | ✅ | `mimo-v2.5` or `mimo-v2-omni` | NOT mimo-v2.5-pro |
+| Web search | ✅ | any | requires Web Search Plugin activated in MiMo console |
+| TTS (speech synth) | ✅ | `mimo-v2.5-tts` | separate endpoint |
+| ASR (speech recog) | ✅ | `mimo-v2.5-asr` | separate endpoint |
+| Audio chat | ✅ | `mimo-v2-omni` | input only |
+| Video understanding | ✅ | `mimo-v2-omni` | input only |
+| **Image generation** | ❌ | — | **see workaround below** |
+| Code interpreter / sandbox | ❌ | — | not provided |
+
+For the full capability matrix and examples, read [references/models.md](references/models.md).
+
+## Decision tree: what does the user actually want?
+
+```
+Is it chat / vision / search / TTS / ASR?
+├── Yes → use MiMo directly (see "Calling MiMo directly" below) or via mimo2codex if Codex is the client
+└── No, they want image generation
+    │
+    Is it for a Codex pet (`/hatch`)?
+    ├── Yes → see "Generating a Codex pet" below
+    └── No → see "Image generation in general" below
+```
+
+## Calling MiMo directly
+
+Use `scripts/mimo_chat.py` to send a single chat completion (or stream):
+
+```bash
+export MIMO_API_KEY=sk-xxxxxxxxxxxxxxxx
+python3 mimoskill/scripts/mimo_chat.py "your prompt here"
+python3 mimoskill/scripts/mimo_chat.py --model mimo-v2.5 --image https://example.com/x.png "describe this"
+python3 mimoskill/scripts/mimo_chat.py --search "今天上海天气?"
+python3 mimoskill/scripts/mimo_chat.py --stream "tell me a story"
+```
+
+The script handles all the MiMo-specific quirks — `max_completion_tokens` instead of `max_tokens`, the required `text` part next to `image_url`, web_search plugin invocation, `reasoning_content` round-tripping, etc.
+
+For non-trivial integrations, [references/models.md](references/models.md) and [the official MiMo OpenAI-compat doc](https://platform.xiaomimimo.com/docs/api/chat/openai-api) are the authoritative references.
+
+## Generating a Codex pet (the `/hatch` alternative)
+
+**Why this needs special handling**: Codex's built-in `/hatch` pet generation requires OpenAI's image generation API (`gpt-image-1`). MiMo doesn't have an image generation endpoint, and mimo2codex can't fake one. So `/hatch` from inside Codex won't work when Codex is pointed at MiMo.
+
+**The workaround**: generate the pet image *outside* of Codex, then drop the result into Codex's pet directory and restart Codex. The script supports several image-gen backends:
+
+- **`auto` (default)** — picks `gpt-image-1` if you have an OpenAI key set, otherwise falls back to **pollinations.ai** (free, no key, no signup). **Works with only a MiMo key.**
+- **`pollinations`** — free, no key required
+- **`gpt-image-1`** — best quality, needs a real OpenAI key (separate from `MIMO_API_KEY`)
+- **`replicate`** — FLUX/SDXL, ~$0.003/img, needs `REPLICATE_API_TOKEN`
+- **`local-sd`** — Automatic1111/ComfyUI on `127.0.0.1:7860`, free, needs local setup
+
+### Quickstart (only MiMo key required)
+
+```bash
+# 1. No OpenAI key, no pip install — just run with the free fallback
+python3 mimoskill/scripts/generate_pet.py \
+    --description "a chubby cyberpunk axolotl coding hero" \
+    --out ~/Downloads/my-pet.png
+
+# 2. Install into Codex's pet folder
+bash mimoskill/scripts/install_pet.sh ~/Downloads/my-pet.png "axolotl-coder"
+
+# 3. Restart Codex completely and select the new pet from the pet menu
+```
+
+`generate_pet.py` will print `[provider] auto → pollinations` so you know the free path is in use.
+
+### Optional: better quality with an OpenAI key
+
+If you do want gpt-image-1 quality (and image-to-image edit via `--reference`):
+
+```bash
+export PET_OPENAI_API_KEY=sk-real-openai-key  # NOT mimo2codex-local
+python3 mimoskill/scripts/generate_pet.py \
+    --reference path/to/source-image.jpg \
+    --description "a chubby cyberpunk axolotl coding hero" \
+    --out ~/Downloads/my-pet.png
+```
+
+`auto` will pick gpt-image-1 automatically when this env var is set. This OpenAI key is **only** used for the image generation call — your chat conversations still go through MiMo via mimo2codex.
+
+### Step-by-step walkthrough + prompt design
+
+Read [references/pet_workflow.md](references/pet_workflow.md) for:
+
+- The exact Codex pet folder location on macOS / Linux / Windows
+- How to make a static image work (most pets are animated GIFs, but a static PNG fallback works)
+- How to generate animated states (idle / working / done) — typically requires multiple gpt-image-1 calls with edit / remix prompting
+- How to mix MiMo + image gen: have MiMo write the prompt, then feed that prompt to gpt-image-1
+
+Use the proven pet prompt formula in [assets/pet_prompt_template.md](assets/pet_prompt_template.md) — it's tuned for the chibi / sticker style Codex uses.
+
+## Image generation in general
+
+If the user wants image generation for some other reason (not a pet), the same workaround applies: `gpt-image-1` is the highest-quality option but requires a real OpenAI key. Free alternatives:
+
+- **Stable Diffusion** locally via [Automatic1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui) or [ComfyUI](https://github.com/comfyanonymous/ComfyUI) — heavy setup but no per-call cost
+- **Together AI** / **Replicate** — pay-as-you-go for SDXL / FLUX
+- **Pollinations.ai** — free, no key required, lower quality
+
+`scripts/generate_pet.py` defaults to gpt-image-1 but accepts `--provider pollinations` for the free path (with reduced quality).
+
+## Cost notes
+
+- Direct MiMo: pay-as-you-go (`sk-xxx`) or token plan (`tp-xxx`). See [pricing](https://platform.xiaomimimo.com/docs/pricing).
+- Web Search plugin: separately metered per keyword search. Cap with `max_keyword`.
+- gpt-image-1: ~$0.04 per 1024×1024 image (low quality), up to ~$0.17 (HD). One pet usually costs <$0.50 even with retries.
+- Pollinations.ai: free.
+
+## Don't use this skill for
+
+- Just running mimo2codex (that's an HTTP proxy; this skill is direct API + workarounds). For mimo2codex itself, see the project [README.md](../README.md) / [README.zh.md](../README.zh.md).
+- Configuring Codex (use `mimo2codex print-config` or `mimo2codex print-cc-switch`).
+- Anything Anthropic / Claude — this is MiMo-specific.

package/mimoskill/assets/pet_prompt_template.md

@@ -0,0 +1,94 @@
+# Pet prompt templates
+
+Tuned for the chibi / sticker style Codex's built-in pets use. `generate_pet.py`
+auto-prepends and appends the boilerplate, so what you pass via `--description`
+should just be the **subject** (and optionally an action / pose for state-aware
+variants).
+
+The full assembled prompt looks like:
+
+```
+Chibi sticker mascot of <description>, <action>, front-facing, expressive face,
+soft cel-shading, thin clean outline, transparent background, high detail,
+playful, single character centered, 1024x1024 sticker style
+```
+
+## Subject formula
+
+```
+<adjective> <species/character> <(optional) accessory or trait>
+```
+
+Examples:
+
+| Description | Result style |
+|---|---|
+| `chubby cyberpunk axolotl` | rounder body, neon highlights |
+| `wise old shiba inu wearing tiny glasses` | classic dev mascot vibe |
+| `tiny astronaut cat with a USB cable tail` | sci-fi quirky |
+| `pixel-art slime in a hoodie` | indie game feel |
+| `red panda with antennae and a debugger sword` | combat-coder mood |
+| `kawaii rubber duck with a tie and laptop` | corporate-debug humor |
+
+Tips:
+- **One creature only.** "axolotl AND a cat" produces clutter.
+- **Keep adjectives concrete.** "soft", "round", "tiny", "neon", "glowing" >
+  "cool", "epic", "amazing".
+- **Mention 1 accessory max.** A laptop, a coffee cup, a wrench — not all three.
+
+## State action overrides (for `--bundle` mode)
+
+These are inserted between subject and the boilerplate, replacing the script's
+default actions if you customize.
+
+| State | Default action |
+|---|---|
+| `idle` | `calm pose, hands together, soft smile` |
+| `working` | `typing on a tiny laptop, focused expression, sparkles around hands` |
+| `done` | `celebrating with arms raised, sparkles and confetti` |
+
+Custom action examples:
+
+- working: `welding sparks flying, goggles down, intense concentration`
+- done: `triumphantly holding up a 'shipped' flag, confetti raining`
+- error: `comedic stunned face, smoke wisps, holding a broken keyboard`
+
+## Generating descriptions with MiMo
+
+Have MiMo describe the reference image first:
+
+```bash
+python3 mimoskill/scripts/mimo_chat.py \
+    --image path/to/reference.jpg \
+    "Describe this character in 12-25 words as a chibi pet sticker prompt for \
+     image generation. Output ONLY the description, no preamble. Format: \
+     '<adjective> <species> <accessory>'."
+```
+
+Pipe it straight into the generator:
+
+```bash
+DESC=$(python3 mimoskill/scripts/mimo_chat.py --image src.jpg \
+    "Describe this character in 12-25 words ... Output ONLY the description.")
+python3 mimoskill/scripts/generate_pet.py \
+    --reference src.jpg --description "$DESC" --bundle ./my-pet/
+```
+
+## Style overrides
+
+If the default chibi-sticker style isn't what you want, edit
+`scripts/generate_pet.py` and change `PROMPT_PREFIX` / `PROMPT_SUFFIX`. Common
+alternatives:
+
+- **Pixel art**: prefix `Retro 16-bit pixel art sprite of `, suffix `, transparent background, single sprite, 64x64 upscaled to 1024x1024 with nearest-neighbor`
+- **Hand-drawn**: prefix `Hand-drawn ink-and-watercolor sticker of `, suffix `, transparent background, loose linework, watercolor wash, single character`
+- **3D rendered**: prefix `Cute 3D render mascot of `, suffix `, soft global illumination, transparent background, octane render, isometric three-quarter view`
+
+## Anti-patterns
+
+These tend to produce bad pets — avoid:
+
+- Listing more than 3 visual traits in the subject (model averages them poorly)
+- Naming a real human ("looks like Steve Jobs") — gpt-image-1 will refuse
+- Negative prompts in the description ("not blurry") — handled by the suffix
+- Specifying impossible camera angles ("from below") for sticker-style outputs

package/mimoskill/references/models.md

@@ -0,0 +1,111 @@
+# MiMo V2.5 model capability matrix
+
+Authoritative source: <https://platform.xiaomimimo.com/docs>. This file summarizes
+the bits the skill cares about — read the official docs for full schemas.
+
+## Models at a glance
+
+| Model | Text | Vision | Audio in | Image gen | Audio gen | Reasoning | Context | Best for |
+|---|---|---|---|---|---|---|---|---|
+| `mimo-v2.5-pro` | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ strong | 128K | Coding, agentic tasks, complex reasoning |
+| `mimo-v2.5-pro[1m]` | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ strong | 1M | Long-doc / large-codebase analysis |
+| `mimo-v2.5` | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ medium | 128K | Multimodal chat with image input |
+| `mimo-v2.5[1m]` | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ medium | 1M | Long-context with images |
+| `mimo-v2-omni` | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | 128K | Full-modal input (text/image/audio/video) |
+| `mimo-v2-flash` | ✅ | ❌ | ❌ | ❌ | ❌ | – | 128K | Cheap / fast simple chat |
+| `mimo-v2.5-tts` | ❌ | ❌ | ❌ | ❌ | ✅ | – | – | TTS (separate endpoint) |
+| `mimo-v2.5-asr` | ❌ | ❌ | ✅ | ❌ | ❌ | – | – | ASR (separate endpoint) |
+
+> **Image generation is not in this table because no MiMo model produces images.**
+> For image generation, see [pet_workflow.md](./pet_workflow.md) → "Image gen alternatives".
+
+## Endpoints
+
+| Capability | Endpoint | Compatible with |
+|---|---|---|
+| Chat (text + vision) | `https://api.xiaomimimo.com/v1/chat/completions` | OpenAI Python SDK / curl |
+| Chat (Anthropic shape) | `https://api.xiaomimimo.com/anthropic/v1/messages` | Anthropic SDK / Claude Code |
+| TTS | (consult MiMo TTS docs) | MiMo SDK |
+| ASR | (consult MiMo ASR docs) | MiMo SDK |
+
+Token Plan users substitute `https://token-plan-cn.xiaomimimo.com` for the host.
+
+## Authentication
+
+Both header forms are accepted:
+
+```
+Authorization: Bearer ${MIMO_API_KEY}
+```
+
+or
+
+```
+api-key: ${MIMO_API_KEY}
+```
+
+Key prefixes:
+
+- `sk-...` — pay-as-you-go (uses default `api.xiaomimimo.com` base URL)
+- `tp-...` — token plan subscription (uses `token-plan-cn.xiaomimimo.com` base URL)
+
+## Field quirks (vs OpenAI)
+
+These trip people up:
+
+1. Use **`max_completion_tokens`**, not `max_tokens`. MiMo follows the newer spec.
+2. **Reasoning is exposed as `reasoning_content`** on assistant messages (DeepSeek-style), not OpenAI's `reasoning_summary`.
+3. For **multi-turn tool calls in thinking mode**, *re-inject all prior `reasoning_content`* on the next request — MiMo recommends this, drops in quality otherwise.
+4. **Image input requires both `image_url` AND a `text` part**. An image-only message returns `400 Param Incorrect: text is not set`. Add a `{type: "text", text: " "}` part if you don't have a real prompt.
+5. **`tool_choice` other than `"auto"`** is currently silently ignored upstream — behavior is always equivalent to `auto`.
+6. **Web Search builtin** is a tool of `type: "web_search"` (not a function tool). Requires the [Web Search Plugin](https://platform.xiaomimimo.com/#/console/plugin) to be activated in your console first; separately metered.
+7. Annotations come back on `message.annotations` as `{type: "url_citation", url, title, summary}`.
+
+## Tools and function calling
+
+Standard OpenAI function tool format works:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "...",
+    "description": "...",
+    "parameters": { "type": "object", "properties": { ... } },
+    "strict": false
+  }
+}
+```
+
+`tool_calls` come back on the assistant message; reply with `{role: "tool", tool_call_id, content}`. Parallel tool calls are supported.
+
+## Web search
+
+```json
+{
+  "type": "web_search",
+  "max_keyword": 3,
+  "force_search": true,
+  "limit": 1,
+  "user_location": {
+    "type": "approximate",
+    "country": "China",
+    "region": "Hubei",
+    "city": "Wuhan"
+  }
+}
+```
+
+Streaming: search sources arrive in the **first** SSE chunk's `delta.annotations`.
+
+## Quick model picker
+
+```
+Need image input?            → mimo-v2.5 (or mimo-v2-omni for audio/video too)
+Need 1M context?             → mimo-v2.5-pro[1m] or mimo-v2.5[1m]
+Doing heavy reasoning/code?  → mimo-v2.5-pro
+Just doing cheap text chat?  → mimo-v2-flash
+Need TTS?                    → mimo-v2.5-tts (separate endpoint)
+Need ASR?                    → mimo-v2.5-asr (separate endpoint)
+Need image generation?       → MiMo can't. Use gpt-image-1 / Pollinations / SD.
+```

package/mimoskill/references/pet_workflow.md

@@ -0,0 +1,197 @@
+# Codex Pet generation workflow (the `/hatch` alternative)
+
+`/hatch` inside Codex calls OpenAI's image generation API (`gpt-image-1`). When
+Codex is pointed at MiMo (via mimo2codex), `/hatch` fails because MiMo doesn't
+have an image generation endpoint and the `mimo2codex-local` placeholder key
+isn't a real OpenAI key.
+
+This doc shows you how to generate the pet **outside** of Codex and drop it in.
+
+## TL;DR (only MiMo key required)
+
+```bash
+# No OpenAI key, no pip install — defaults to free Pollinations
+python3 mimoskill/scripts/generate_pet.py \
+    --description "chibi cyberpunk axolotl with a laptop" \
+    --out ~/Downloads/my-pet.png
+
+bash mimoskill/scripts/install_pet.sh ~/Downloads/my-pet.png "axolotl-coder"
+# fully quit and relaunch Codex; pick the new pet from the picker
+```
+
+The script prints `[provider] auto → pollinations` to confirm the free path
+is in use. For better quality, see "Image gen alternatives" below.
+
+## TL;DR (with OpenAI key for higher quality)
+
+```bash
+export PET_OPENAI_API_KEY=sk-real-openai-key   # NOT mimo2codex-local
+python3 mimoskill/scripts/generate_pet.py \
+    --reference path/to/source.jpg \
+    --description "chibi cyberpunk axolotl with a laptop" \
+    --out ~/Downloads/my-pet.png
+
+bash mimoskill/scripts/install_pet.sh ~/Downloads/my-pet.png "axolotl-coder"
+```
+
+`--reference` (image-to-image edit) only works with `gpt-image-1`.
+
+## Pet folder location
+
+Codex looks for custom pet bundles in these locations (it picks the first that exists):
+
+| OS | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Codex/pets/` (desktop), or `~/Documents/Codex/pets/` (CLI dump) |
+| Linux | `~/.config/Codex/pets/` or `~/.codex/pets/` |
+| Windows | `%APPDATA%\Codex\pets\` |
+
+The exact path depends on your Codex version. `install_pet.sh` will probe each
+candidate and put the file in the first writable directory it finds, falling
+back to `~/.codex/pets/` if none exist (creating it).
+
+After install, **fully quit Codex** (system tray → Quit, not just close window)
+and reopen — the picker will show the new entry.
+
+## Pet bundle format
+
+A Codex pet bundle is a small directory:
+
+```
+my-pet/
+├── manifest.json   # name, author, sprite filenames, default state
+├── idle.png        # required: idle animation
+├── working.png     # required: shown while Codex is processing
+├── done.png        # optional: shown briefly on success
+└── error.png       # optional: shown on failure
+```
+
+If you only have one image, use it for `idle.png` — Codex will reuse it for the
+other states.
+
+`scripts/install_pet.sh` writes a minimal `manifest.json` for you.
+
+> **Note:** This format is reverse-engineered from observed behavior and may
+> evolve. If a future Codex version rejects the bundle, check the Codex docs at
+> <https://developers.openai.com/codex/app/pets> (or run `/pet --debug` if such a
+> flag exists in your version) to see the current schema, and update the script.
+
+## Step-by-step
+
+### 1. Pick a reference image
+
+Anything works — a photo of yourself, a screenshot of a character, a logo.
+gpt-image-1's edit mode will turn it into a chibi-style sticker. PNG or JPG,
+recommended ≤ 4 MB.
+
+If you don't have a reference image, skip `--reference` and gpt-image-1 will
+generate from your text description alone.
+
+### 2. Write a description
+
+The "description" goes into the prompt. Use [assets/pet_prompt_template.md](../assets/pet_prompt_template.md)
+for the proven pattern. In short:
+
+> `chibi sticker of <subject>, <pose>, transparent background, soft cel-shading,
+> playful, sticker outline, 1024x1024`
+
+The script will wrap your description with the rest of the prompt automatically.
+
+You can also have **MiMo write the description for you**:
+
+```bash
+python3 mimoskill/scripts/mimo_chat.py \
+    --image path/to/source.jpg \
+    "Describe this image as a 25-word chibi pet sticker prompt for an image generator. \
+     Use this format: 'chibi sticker of {subject}, {pose}, transparent background, \
+     soft cel-shading'."
+```
+
+Then paste the output as `--description`.
+
+### 3. Generate states (single image vs animated)
+
+The default `generate_pet.py` produces **one** PNG (idle). For an animated pet
+with multiple states, run it 3 times with different action descriptions:
+
+```bash
+python3 mimoskill/scripts/generate_pet.py \
+    --reference src.jpg --description "chibi axolotl, calm, hands on lap" \
+    --out idle.png
+
+python3 mimoskill/scripts/generate_pet.py \
+    --reference src.jpg --description "chibi axolotl, typing on laptop, focused expression" \
+    --out working.png
+
+python3 mimoskill/scripts/generate_pet.py \
+    --reference src.jpg --description "chibi axolotl, hands raised in celebration, sparkles" \
+    --out done.png
+```
+
+Then point `install_pet.sh` at the directory containing all three:
+
+```bash
+bash mimoskill/scripts/install_pet.sh --bundle ./my-axolotl/ "axolotl-coder"
+```
+
+### 4. Restart Codex completely
+
+This is the step people skip. Codex caches the pet list at startup:
+
+- **CLI**: just exit and rerun `codex`
+- **Desktop**: system tray / menu bar → **Quit** (not just close window). Relaunch.
+
+### 5. Select the new pet
+
+Open the pet picker (e.g. `/pet` slash command, or settings → Pets) and select
+your new entry by the name you passed to `install_pet.sh`.
+
+## Image gen alternatives (if you don't want to pay OpenAI)
+
+The script supports `--provider`:
+
+| Provider | Quality | Cost | Setup |
+|---|---|---|---|
+| `gpt-image-1` (default) | best | ~$0.04–0.17/image | needs OpenAI key |
+| `pollinations` | ok | free | no setup |
+| `replicate` | great (FLUX/SDXL) | ~$0.003/image | needs Replicate key |
+| `local-sd` | varies | free (after setup) | needs Automatic1111/ComfyUI running locally |
+
+Examples:
+
+```bash
+# Free, no key
+python3 mimoskill/scripts/generate_pet.py --provider pollinations \
+    --description "..." --out pet.png
+
+# Replicate FLUX-Schnell
+export REPLICATE_API_TOKEN=r8_...
+python3 mimoskill/scripts/generate_pet.py --provider replicate \
+    --description "..." --out pet.png
+
+# Local Stable Diffusion (Automatic1111 with --api flag, default port 7860)
+python3 mimoskill/scripts/generate_pet.py --provider local-sd \
+    --description "..." --out pet.png
+```
+
+## Troubleshooting
+
+**"Authentication failed"**
+You're using the placeholder `mimo2codex-local` key. Set `PET_OPENAI_API_KEY`
+to a real OpenAI key for `gpt-image-1`. The MiMo key won't work for OpenAI's
+image API.
+
+**"Codex doesn't see my new pet"**
+- Check the install path in the install script's output
+- Fully quit & relaunch Codex (not just close the window)
+- Make sure `manifest.json` is valid JSON
+- Try copying a built-in pet's directory, replacing only the PNGs, to rule out
+  manifest schema drift
+
+**"The image looks bad / off-character"**
+- Iterate on the description with MiMo: "Improve this image-gen prompt for a
+  chibi pet sticker"
+- For gpt-image-1, add `quality: "hd"` (script default is `medium`); pass
+  `--quality hd` for the high-quality 1024×1024 path
+- For consistency across states, use `--reference` so all three calls edit the
+  same source image instead of generating from scratch