oma-image

# Image Agent - Multi-Vendor Image Router

## Scheduling

### Goal
Generate images and visual assets through authenticated multi-vendor routing while preserving prompt clarity, reference-image handling, cost controls, and reproducible output manifests.

### Intent signature
- User asks to generate images, visual assets, illustrations, product photos, concept art, mockups, or AI art.
- Another skill needs shared image-generation infrastructure.
- User provides reference images or asks for vendor comparison.

### When to use

- Generating images, visual assets, illustrations, product photos, concept art
- Comparing output between multiple image models for the same prompt
- Producing images from prompts within editor workflows (Claude Code, Codex, Gemini CLI)
- Other skills needing image generation infrastructure (shared invocation)

### When NOT to use

- Editing an existing image or photo manipulation -> out of scope
- Generating videos or audio -> out of scope
- Inline vector art / SVG composition from structured data -> use a templating skill
- Simple asset resizing or format conversion -> use a dedicated image library

### Expected inputs
- Image prompt or creative brief
- Optional vendor, size, quality, count, output directory, and reference images
- Authentication/environment state for Codex, Pollinations, or Gemini

### Expected outputs
- Generated image files under `.agents/results/images/` or requested output directory
- `manifest.json` with prompt, vendor, model, and reproducibility metadata
- Vendor comparison outputs when `--vendor all` is used

### Dependencies
- `oma image generate` CLI and vendor authentication
- Codex image generation, Pollinations API, or Gemini API/CLI strategy
- `resources/vendor-matrix.md`, `resources/prompt-tips.md`, and `config/image-config.yaml`

### Control-flow features
- Branches by prompt ambiguity, vendor auth, cost threshold, reference-image support, path safety, and safety/timeout exit codes
- Calls external vendor APIs/CLIs
- Reads reference images and writes generated images plus manifests

## Structural Flow

### Entry
1. Validate that the request contains enough subject, setting, style, usage, and aspect-ratio signal.
2. Detect attached/reference images and vendor support.
3. Check authentication, cost guardrails, output path, and count limits.

### Scenes
1. **PREPARE**: Clarify or amplify prompt and choose vendor strategy.
2. **ACQUIRE**: Validate auth, references, output path, and provider availability.
3. **ACT**: Invoke `oma image generate` with selected vendor(s), prompt, references, and options.
4. **VERIFY**: Check manifest, output files, exit code, and provider result.
5. **FINALIZE**: Return output paths and relevant warnings.

### Transitions
- If prompt lacks required signal, clarify or show amplified prompt before generation.
- If `--vendor all` is requested, require every requested vendor to be available.
- If reference path is supported by selected vendor, pass it automatically.
- If estimated cost exceeds guardrail, require confirmation unless bypassed.

### Failure and recovery
- If auth is missing, report vendor-specific authentication requirement.
- If reference support is unavailable for the selected vendor, reject with actionable guidance.
- If local CLI is outdated, ask user to run `oma update`.
- If generation times out or is blocked, surface exit code and provider status.

### Exit
- Success: images and manifest exist in the output directory.
- Partial success: some vendors fail in comparison mode and failures are reported.
- Failure: no image is produced and the route/cost/auth/safety blocker is explicit.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Validate prompt completeness | `VALIDATE` | Clarification protocol |
| Select vendor strategy | `SELECT` | Vendor matrix and auth state |
| Read reference images | `READ` | `--reference` paths |
| Call generation CLI/API | `CALL_TOOL` | `oma image generate` |
| Write image outputs | `WRITE` | Image files and manifest |
| Validate result | `VALIDATE` | Exit code, manifest, files |
| Report output | `NOTIFY` | Final path summary |

### Tools and instruments
- `oma image generate`, `oma image doctor`, `oma image list-vendors`
- Codex, Pollinations, and Gemini provider paths
- Prompt tips, vendor matrix, and image config

### Canonical command path
```bash
oma image doctor
oma image generate "<prompt>" --vendor auto --size auto --quality auto --format json
```

With reference images:
```bash
oma image generate --reference "<absolute-path>" --vendor codex "<prompt>"
```

### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `LOCAL_FS` | Reference images, generated images, manifests |
| `PROCESS` | Provider CLIs and image router commands |
| `NETWORK` | Pollinations/Gemini or provider APIs |
| `CREDENTIALS` | Provider auth and API keys |

### Preconditions
- Prompt is sufficiently specified or user approves amplification.
- Required vendor auth and output permissions exist.
- Reference paths are accessible when used.

### Effects and side effects
- Creates image files and manifests.
- May call paid or rate-limited provider APIs.
- May read attached/reference images.

### Guardrails

1. **Clarify before invoking** — if the user's request is ambiguous about subject, style, composition, or usage context, **ask the user first** or **amplify the prompt explicitly** (showing the user the expanded version for approval). Do NOT silently generate from a vague prompt. See `Clarification Protocol` below.
2. **Authentication-aware dispatch** — detect which vendor CLIs are authenticated and run only those; with `--vendor all`, every requested vendor must be available (strict).
3. **Cost guardrail** — confirm before executing runs whose estimated cost is ≥ `$0.20` (configurable). `--yes` / `OMA_IMAGE_YES=1` bypass. Default vendor `pollinations` (flux/zimage) is free, so auto-triggering on keywords