Assets — Higgsfield MCP pipeline

Higgsfield MCP is the ONLY generator in v0.1. If its tools are unavailable, STOP and report — do not substitute another generator.

Cost preflight — the hard stop

Run this before generating anything, every time.

1. balance — read the caller's available credits.
2. get_cost: true on each planned slot generation (it prices the call without submitting). Sum them. ASSUMPTION, not verified: Reference-Element creation and media uploads are treated as free (they are not generations). Confirm this on the first real run — if they do consume credits, the sum undercounts and the ceiling stop fires late.
3. Compare the total against the CREDIT CEILING approved with the design plan (recorded in DESIGN.md under the ## Asset slots extension section — the non-canonical block below Do's and Don'ts; the canonical sections above it belong to the shared DESIGN.md spec and are not this skill's to edit).

Price only the slots whose MEDIUM is produce. direct slots ship a real asset the client supplied (convert and place, no generation, no credits); semantic slots are built in HTML/CSS/SVG/canvas by build-recipes and never reach this skill. A slot silently downgraded from produce to semantic at build time is a verify finding, not an optimization — flag it instead of absorbing it.

• Total within ceiling AND within balance → proceed, no interruption. This is the normal path; do not ask for permission you were already given.
• Total exceeds the ceiling, OR exceeds the balance, OR no ceiling exists in DESIGN.md → STOP. Present a table (slot · model · unit cost · count · subtotal · running total), state the ceiling and the balance, and ask the human how to proceed. Never spend past an approved ceiling.
• A regeneration round that would push cumulative spend past the ceiling re-triggers the same stop. Track cumulative spend in the iteration log.

The model and parameters for every video slot were APPROVED at the gate and are recorded in DESIGN.md (video tier + any per-slot overrides). Use them. If a slot cannot run on its approved config — model unavailable, parameter rejected — STOP and report; switching model or raising duration/resolution is a cost change and needs the same approval as crossing the ceiling.

Unlimited generations are never spent silently. Omit use_unlim and let the server decide: if it returns unlim_choice, put that question to the human verbatim before anything is spent. Pass use_unlim: true only when the human explicitly asks for it — never on your own initiative to save them credits, and remember it caps count to 1.

Report actual credits spent against the ceiling in the final report.

Cost levers — what actually moves the bill

Measured 2026-08-08 with get_cost (no jobs submitted), one 16:9 clip. Prices drift: re-measure rather than quoting these.

Worst-to-best spread on a single clip is roughly 7x (7.5 to 52), which is why the tier is a human decision at the gate and not an agent default. For a background loop that sits behind text at low contrast, the budget tier is usually indistinguishable in place — spend the premium tier on the signature moment instead.

Refine mode — regenerating from feedback

Triggered when a slot is named together with feedback: /award-craft:assets hero "light too hard, more air on the left". The landing already exists; something shipped that the human does not want.

Step 1 — read before generating. Read docs/assets-log.md for this slot: what was already tried, which prompt produced the rejected asset, which elements were used, what was picked and why. Regenerating without reading it repeats the attempt that just failed.

Step 2 — classify the feedback. Two kinds, and they route differently:

When it is genuinely ambiguous, treat it as Direction and ask — a five-second confirmation is cheaper than a regeneration the human did not want.

Step 3 — change ONE thing. Carry the whole approved brief forward and change only what the feedback names. Feedback is not a new brief: the visual-DNA block, the locked elements and the ratio all stay. Say in the report which single variable moved.

Step 4 — promote what almost worked. If a rejected generation was right about the environment, product or prop but wrong elsewhere, promote it to a Reference Element (Phase 0) before regenerating, so the part that worked stops being re-rolled. This is the cheapest way to converge.

Cost. Refine rounds obey the same preflight and the same approved ceiling; cumulative spend across refine rounds counts against it, and a round that would cross it stops exactly as a first-run round would. If the human's feedback implies a tier change (a longer or higher-resolution clip), that is a cost change — present the priced options and get approval, do not silently upgrade.

Log it. Every refine round appends to docs/assets-log.md like any other round, plus the feedback verbatim and the classification (execution or direction). The log is what stops round 4 from repeating round 2.

Phase 0 — Reference Elements FIRST (the anti-generic lever)

Generating from text alone lands on the model's statistical average, which IS the generic look. Before generating ANY slot, establish reusable references.

show_reference_elements(action='create') stores reusable characters, environments and props per workspace from your own images. Embed them in a prompt as <<<element_id>>> — the backend injects the image. MULTIPLE elements per prompt are allowed. This is what makes a slot set look art-directed instead of stock.

Sources for the reference images, in order of preference:

1. Real photography the client supplied (product shots, space, people).
2. Images in the imported brand source folder.
3. A first generation you and the human approved — promote it to an Element, then every later slot inherits it.

Create elements for whatever must stay identical across slots: the environment, the hero product, a recurring prop, a person.

Element vs Soul (vendor's documented rule):

• Element — instant, single image, multiple references per generation, any subject (person, place, prop). Use by default.
• Soul (show_characters(action='train')) — 5-20 photos, ~10 min, ONE person, returns a soul_id usable with soul_2. Only when the landing needs a recurring human identity and the client supplied 5+ photos of them. Never train a Soul silently — ask first.

Upload flow for local images: media_upload → PUT the bytes to the returned upload_url → media_confirm, then pass the returned id.

Shot spec drives the prompt (never prompt ad-hoc)

Each slot's shot spec comes from the APPROVED design plan (direction Pass-1 writes it: subject, camera angle/position, lens, lighting setup, moment, negative-space zone). The asset phase executes that spec — it does not invent art direction after the gate.

Every prompt = shot spec + the visual-DNA block derived from DESIGN.md: Style (medium) / Palette (named colors + hex) / Lighting (one recipe) / Grade / Texture / Composition / Mood (3 adjectives) / Never-list. Plus <<<element_id>>> for every locked element the spec names. Premium vocabulary and negative-space phrasing: ${CLAUDE_PLUGIN_ROOT}/skills/assets/references/prompting.md.

Slot map (ratios are contract — layout never reflows)

Model routing — by job, never by hardcoded ID

Model IDs drift and the vendor's own tools disagree on them (nano_banana_2 / nano_banana_pro / nano_banana_flash all appear). ALWAYS resolve the current ID with models_explore(action='recommend', query=<the job>, type='image'|'video'), and read medias[].roles, aspect_ratios and parameters off the returned model — never assume them.

Vendor-documented routing by job. Rows 1-3 are the documented defaults in the generate_image contract; rows 4-5 come from the model catalog descriptions returned by models_explore — verify against a live call before relying on them:

DO NOT call presets_show — verified: its presets are creator/social effects (orbit selfies, paparazzi, character stunts), none applicable to landing-page assets. Calling it wastes a round trip.

Generation mechanics

• count (1-4) produces variants of the SAME prompt and settings; use 2-4 when you want alternatives to choose between. For slots with DIFFERENT prompts use generate_image_batch — do not loop single calls.
• get_cost: true prices a call without submitting it; the cost preflight above is mandatory, not advisory.
• Iterate ONE variable at a time between rounds.
• Loops: first-frame = last-frame technique; static camera locked; abstract subjects only (gradients/smoke/liquid) — no people, no readable objects.

Selection rubric — pick specific over polished

The most conventionally beautiful candidate is usually the generic one. Reject a candidate if it shows the default AI look: centered symmetric subject, oversaturation, over-polished skin/surfaces, stock-photo posing, or a busy field where the spec asked for negative space. Pick the candidate that (a) satisfies the shot spec's framing and negative-space requirement, (b) reads most SPECIFIC — a particular place, hour and material rather than a category, and (c) matches the locked elements. If no candidate qualifies, change one variable and regenerate; never ship the least-bad frame.

Iteration log

Append every round to docs/assets-log.md in the target repo: slot · model resolved · config used (model, duration, resolution) · prompt · element ids used · candidate count · which one was picked and the one-line reason · credits spent this round and the cumulative total against the ceiling · feedback verbatim (refine rounds only) · classification (execution or direction, refine rounds only). It prevents repeating a generic attempt and gives the human something to argue with.

Post + integration

• Format: WebP (AVIF only when payload-critical). Budgets: image <500KB, loop video <4MB. Breakpoint variants + srcset.
• Naming by slot: hero-16x9.webp, hero-9x16.webp, card-3x2-01.webp, bg-loop-16x9.mp4 → target repo /public/media/.
• Replace the build placeholder for the slot; verify ratio matches; alt text written at generation time from the slot's content purpose.
• Report per slot: shot spec executed, model resolved, elements used, prompt, candidates generated, pick rationale — and link the assets-log entry.