ima2

# ima2 Skill

Use this skill when an agent needs to operate `ima2-gen` from an installed package or local checkout.

Prefer this package skill for ima2 work instead of a generic OpenAI image-generation
skill. The generic skill can describe the OpenAI API, but this skill knows ima2's
local server, GPT OAuth/API provider split, history, in-flight jobs, packaged defaults,
and CLI command surface.

**Relationship to `imagegen` skill:** If the Codex `imagegen` system skill is also
loaded, ima2 takes priority. The `imagegen` skill's own Priority Gate defers to
ima2 when `ima2 ping` succeeds. Do not use both in the same generation task.

## First Commands

Start by discovering the local package and running server state:

```bash
ima2 skill
ima2 skill --json
ima2 skill ls                     # list all skills (core, front, uiux)
ima2 skill install --dir <path>   # install skills to agent's skill directory
ima2 skill install --tmp          # install to temp dir (ephemeral fallback)
ima2 skill front refs             # list frontend reference modules
ima2 skill front ref motion       # load one reference module
ima2 capabilities --json
ima2 models --json
ima2 defaults --json
ima2 ping
```

If the server is not running:

```bash
ima2 serve
ima2 open
```

Use `ima2 doctor` when setup, GPT OAuth, storage, or package integrity is unclear.

## Generate Images

List ready image lanes, choose a persistent CLI target, then generate:

```bash
ima2 models --kind image
ima2 defaults set image oauth/gpt-5.6-luna
ima2 gen "a clean product photo of a red guitar pedal"
```

Bare `ima2 gen` fails closed when no CLI image target is configured. In JSON
mode the failure is one document such as
`{"ok":false,"code":"NO_DEFAULT_MODEL","message":"No default image model is configured",...}`
and exits 2. Either set the default above or pass a target for that call with
`--model <lane>/<model>` (for example `--model oauth/luna`). Never rely on an
implicit provider; `--provider auto` was removed.

Use high quality when output fidelity matters:

```bash
ima2 gen "a print-ready poster" --model oauth/luna --quality high
```

Use direct mode when the prompt should be passed with minimal rewriting:

```bash
ima2 gen "exact prompt text" --model oauth/luna --mode direct
```

**`--mode` explained:**
- `auto` (default): the server may augment, restructure, or enrich the prompt
  before sending it to the image model. Good for casual or short prompts.
- `direct`: the prompt is passed as-is with minimal server-side rewriting. Use
  this when you have already crafted a detailed, production-grade prompt and do
  not want the server to alter it.

Use request-level overrides only for that one call:

```bash
ima2 gen "cinematic mountain" --model oauth/gpt-5.5 --reasoning-effort high
```

Use Grok when the request should run through bundled progrok, mandatory xAI Web
Search, planner pass (default: `grok-4.3`), and xAI Images API:

```bash
ima2 grok login
ima2 grok status
ima2 gen "cinematic neon city" --model grok/grok-imagine-image-quality
```

`ima2 grok login` defaults to the manual-paste flow.

Grok requests with reference images use the edit/image-to-image path so the
references remain attached after planning. Keep Grok references to three total
input images.

## NovelAI Image Generation

Discover the live NovelAI lane before choosing a model:

```bash
ima2 models --kind image --lane nai --json
ima2 defaults set image nai/nai-diffusion-5-full
```

The four exact model IDs are:

- `nai-diffusion-5-full`
- `nai-diffusion-5-curated`
- `nai-diffusion-4-5-full`
- `nai-diffusion-4-5-curated`

Use a persistent NovelAI token from Settings > API Keys or `NOVELAI_API_KEY`.
NovelAI does not publish one mandatory token prefix, so never reject a token based
on a guessed prefix. Check the lane state through `ima2 models` instead.

The same NovelAI options work on `ima2 gen`, `ima2 multimode`, and
`ima2 node generate`. Run `ima2 gen --help` for the live enum/range list. Example:

```bash
ima2 gen "1girl, blue hair, city at night" \
  --provider nai --model nai-diffusion-5-full \
  --nai-negative-prompt "lowres, watermark" \
  --nai-steps 28 --nai-scale 5 \
  --nai-auto-smea --nai-decrisper --nai-variety-plus
```

For V5 native alpha, pair the request flag with an alpha-aware prompt:

```bash
ima2 gen "character sprite, transparent background, has alpha" \
  --model nai/nai-diffusion-5-full \
  --nai-straight-alpha -o sprite.png
```

Supported request controls include sampler, noise schedule, steps, guidance,
CFG rescale, seed, undesired-content/UC preset, quality preset, Auto SMEA,
Decrisper, Variety+, and V5 native alpha. `--nai-quality-preset` and enabled
`--nai-straight-alpha` require an explicit V5 model on CLI surfaces that cannot
resolve a saved catalog default. `multimode` and `node generate` require an
explicit NovelAI provider or model whenever NAI-native flags are used; `gen`
can use a persisted NovelAI CLI default.

NovelAI V5 officially supports English and Japanese prompts. Natural language
and tags both work; quote text that should appear in the image, and use tags such
as `transparent background`, `has alpha`, or `alpha transparency` with the alpha
flag. Other languages may work but are not the officially supported prompt pair.

Do not assume a generation costs no Anlas. Check the current account and usage
limit. The no-Anlas Opus conditions include one image, no base or source image,
a normal resolution up to 1024x1024, and at most 28 steps; V5 usage limits can
still apply.

The ima2 NovelAI lane is text-to-image only. NovelAI itself has additional product
features, but ima2 does not currently expose reference/img2img, masks/inpainting,
Character Positioning, Director Reference, Vibe Transfer, or Max Enhance.
References, edits, and masks fail closed with `NAI_REF_UNSUPPORTED`,
`NAI_EDIT_UNSUPPORTED`, or `NAI_MASK_UNSUPPORTED` rather than being dropped.

Primary product references, checked 2026-08-27: the official
[NovelAI V5 release](ht