image-generate

# Image Generate

Read this skill only after route lock when the task needs synthesized or content-aware reconstructed pixels: `GENERATE`, semantic `EDIT`, or the raster phase of `HYBRID`. Do not load it for `COMPOSE`, deterministic transforms, or overlays. It governs direct `generate_image` calls and the stable host workflow kernel; engine-specific request formats and reusable graphs remain private skill resources rather than new application tools.

This production skill is the earliest point at which a manifest for a direct `GENERATE` or `EDIT` task may be created. Initialize `image-manifest.json` from the `Canonical image-manifest v1` block in `image-router`; it is the single structural source. Replace the locked route and budget, then add the reference and generation fields below. Do not reconstruct the base schema from memory.

## Generation rules

- Respect `generation_budget.max_calls` within the current user turn. The host reapplies this limit independently for each new user turn while retaining older transactions only as audit history. `COMPOSE` has a budget of zero; `HYBRID`, `GENERATE`, and `EDIT` normally use one call. Set a two-call budget only when the user explicitly requests iterative refinement or authorizes another billable attempt. A review finding alone never authorizes that second call.
- Generate at the final aspect ratio whenever the provider supports it. Do not rely on destructive cropping to fix a mismatched composition.
- Use reference images only when they encode composition, identity, product fidelity, or edit continuity that the prompt cannot preserve reliably.
- Mirror manifest references into `generate_image.reference_bindings` using the exact concatenated reference order. Include role, strength, preserve, may-change, and target region. Send `generation_contract.negative_prompt` separately.
- Compile `reference_intent.mode` into the request: reproduction asks for the declared protected attributes to match; guide limits influence to declared roles; editing uses the required `edit_source` as the original. User-declared instructions and boundaries have priority over inferred defaults and provider convenience.
- Treat every planned `output_path` as one stable artifact binding. Reuse that exact string byte-for-byte for the provider/workflow result, later `project.inspect`, optional review candidate, and export input; never retype, derive, or silently correct the path in a downstream handoff.
- For edits, send the manifest instructions, protected regions, unchanged attributes, and allowed changes explicitly. Prefer a localized edit over regenerating the full scene, and never reinterpret an edit as a fresh variation.
- For reproduction, do not silently change subject, crop, layout, identity, typography, palette, or other preserved axes merely because regeneration is easier. Choose the provider/control path that can honor the declared fidelity floor.
- For hybrid work, generate only the difficult raster layer. Exclude final copy, logos, labels, diagrams, and UI text from the model request.
- Save every generated output inside the image project and record its relative path in `image-manifest.json` before inspection.

`generation_contract.controls` records provider-neutral IP-Adapter/ControlNet-style intent. Translate its reference, strength, and target region into the generic reference contract. A provider may additionally consume structured fields, but never claim that it applied a native control unless returned capability or provider evidence says so.

## Provider availability and billing disclosure

Before every direct `generate_image` call, call `image_studio generation.quote` with the same stable `image_request_id`, exact `size`, and combined local-plus-URL `reference_count` that will be dispatched.

- Treat the returned quote as a local capability check. `external` means the configured BYO/local provider can handle the request and may bill through its own account; `unavailable` is a blocker.
- The open build does not estimate provider prices or maintain an in-app credit balance. Never infer a price from model names, cache a local price table, or multiply a remembered per-image rate.
- Stop when the quote reports an unavailable provider or `sufficient:false`. Do not spend a new request id, consume a manifest call slot, or silently switch to another billing path.
- `generate_image` checks provider availability again immediately before it creates the durable generation transaction.
- A completed stable request id is reused without a new quote or provider call only within the same user turn. A pending or failed id remains closed in that turn and cannot be bypassed. A later user turn receives a fresh call scope even when it resumes the same project; do not treat earlier-turn exhaustion as current-turn exhaustion.

When returning a cost decision or execution handoff, keep the state machine
machine-readable: state whether dispatch is allowed, whether external billing
applies, project call slots consumed in the current turn, the exact next operation, and the
`generation.quote` recheck. Do not replace these fields with a vague prose
summary.

`project.status` may include a next-call quote using provider-default size and manifest reference count. Use it for orientation only; `generation.quote` must carry the exact request immediately before a direct call.

## External workflows

Use an external workflow only when the user or host has already configured ComfyUI, InvokeAI, AUTOMATIC1111, or IOPaint and a reusable project-local request offers a concrete control or model advantage. First call `image_studio workflow.capabilities`; never infer availability from a file or a prior session. Read [external-workflows.md](references/external-workflows.md) for the project-local formats.

- The endpoint and credential are host-managed. Never accept, construct, print, or persist them in agent output or project files.
- Read the engine-specific reference before drafting its request an