image

Produce one image asset with actor-≠-auditor verification: Nano Banana 2 draws, Gemini 3.1 Pro vision model inspects with a structured JSON schema, the loop runs until verdict=pass or max_auto_turns is exhausted, every frame gets uploaded to the DO Spaces CDN, and the final frame URL is returned.

This is the first fully-worked skill in snappy-os. It's graduated - the prose steps point at a real script in state/bin/image/.

Inputs

Steps

1. Scope (default - no side effects)

Read last image run from state/log/chain.ndjson. Report the plan:

image: generate-iterate → linkedin-post → CDN (turns=1)

If inputs are missing, list them and stop. Do not touch the CDN.

2. Apply (requires all three inputs)

Run the script:

bash state/bin/image/generate-iterate.sh \
  --illustration "<prompt>" \
  --text "<overlay>" \
  --slug "<slug>" \
  --out-dir "/tmp/snappy-image-<slug>" \
  --format "<format>" \
  --max-auto-turns <n>

The script writes /tmp/snappy-image-<slug>/<slug>/state.json with a frames[] array. Each frame is {n, kind, url} - kind is draft, edit, or final.

3. Read state.json, return the final frame URL

const state = JSON.parse(readFileSync(statePath, "utf8"));
const last = state.frames[state.frames.length - 1];
return { ok: true, link: last.url, note: `${state.frames.length} frame(s)` };

4. Log from the caller (not the script)

generate-iterate.sh writes its own state.json under /tmp/snappy-image-<slug>/ but does NOT write to state/log/chain.ndjson or state/log/evals.ndjson. The snappy-os caller (the agent loop invoking this skill) is responsible for appending the chain row from the frame metadata the script returns:

{"ts":"...","run_id":"...","skill":"image","action":"delivered","link":"https://..."}

Eval

Actor: Nano Banana 2 (gemini-3.1-flash-image-preview) draws frames. Auditor: Gemini 3.1 Pro vision model (gemini-3.1-pro-preview) inspects each frame with responseJsonSchema returning:

{"verdict": "pass" | "fix", "primary_issue": "...", "fix_instruction": "..."}

Scoring (the caller - not the script - appends to state/log/evals.ndjson via score(). The script returns the verdict; the snappy-os runtime emits the eval row):

import { score } from "../lib/eval.ts";
score("image", run_id, {
  score: verdict === "pass" ? 1.0 : fixed ? 0.5 : 0.0,
  primary_issue: primary_issue ?? null,
  frames: frames.length,
});

Why this is a real eval, not a metric: the inspector is a different model from the generator, with a structured schema it cannot rubber-stamp. The shell exit code is not the signal - the verdict field is.

Gotchas (P-fix any new ones here)

• The 6-layer composite template is encoded in the helper scripts under

state/bin/image/ itself (compose-ref.sh, composite-labels.py, classroom-mosaic.sh). There is no dedicated templates/ subdirectory - never freehand, always invoke the helpers.

• Light-on-cream logos fail contrast invisibly. Run the contrast check before

compositing (compose-ref.sh --contrast-check).

• Empty string for text is valid (text-free background for composite).

The gate does not treat empty text as missing.

• Round-tripped drafts in the kernel sometimes have , where em dashes

used to be. Image prompts are §4a-exempt - do not strip em dashes from illustration / prompt frontmatter.

Graduation

This skill is graduated. The script in state/bin/image/generate-iterate.sh is the deterministic path. Prose here exists only to explain intent and to document the eval. If the agent needs to regenerate the logic from scratch, it reads this page + the script.

Rubric

criteria:
  - name: script_execution_success
    kind: deterministic
    check: "The `state/bin/image/generate-iterate.sh` script exits successfully (exit code 0)."
  - name: cdn_url_returned
    kind: deterministic
    check: "The skill returns a well-formed URL for the final image frame, as indicated in the `link` field of the skill's output."
  - name: state_json_integrity
    kind: deterministic
    check: "The `/tmp/snappy-image-<slug>/<slug>/state.json` file exists and contains a valid JSON object with a `frames` array, where the last frame has `kind: 'final'`."
  - name: vision_model_verdict
    kind: judge
    check: "The `verdict` field in the vision model's inspection output for the final frame is 'pass'."

image - loader

Per-turn rules for the image skill. Full reference: state/skills/image/SKILL.md. Do not skip these.

Critical Rules

1. Always use the helper scripts in state/bin/image/ (generate-iterate.sh, compose-ref.sh, composite-labels.py, classroom-mosaic.sh) - never freehand. There is NO state/bin/image/templates/ directory; the 6-layer composite is encoded inline in those scripts. Stale templates/ path tripped every fresh agent (FIXED 2026-04-29).
2. Image-prompt frontmatter is §4a-exempt. Do NOT strip em-dashes from illustration / layer_* / metaphor_rationale / image_prompt - those go to the image model, not a reader. (memory feedback_image_prompts_not_4a)
3. Actor ≠ auditor. Nano Banana 2 (gemini-3.1-flash-image-preview) draws; Gemini 3.1 Pro (gemini-3.1-pro-preview) inspects with responseJsonSchema returning {verdict, primary_issue, fix_instruction}. Never collapse them. (CONSTITUTION invariant #3.)
4. Light-on-cream logos fail contrast invisibly. Run compose-ref.sh --contrast-check BEFORE compositing.
5. Pipeline is sealed. 6-layer template + cream-paper ref + locked layers + learned suffix is the validated path that produced "masterful" consistency. Don't change the pipeline. (memory feedback_image_system_validated)
6. Educational formats (cycle-*, process-*, comparison-*, hierarchy-*, annotated-*) enforce HARD R6: NO text labels inside the drawing area; titles only in the lower-third title slot. If --illustration includes stage labels like STAGE 1, SKILL RUNS, or letter tags, the inspector fails v1 every time. Describe each zone's VISUAL SHAPE only; let the title carry the words. (FIXED 2026-04-29 from snappy-os-system-poster.)
7. Never fan out parallel agent-browser writes to upload - silent drops. Serialize uploads; parallelize generation only. (memory feedback_no_parallel_browser_writes)
8. --max-auto-turns N is a misnomer. generate-iterate.sh runs ONE auto-edit pass regardless of N (lines 332-348). v2 frames are uninspected. Force a v2 verdict via --resume <run-dir> + rerun, or extend the script's loop (>10 LOC, structural).
9. The CALLER appends the eval row, not the script. generate-iterate.sh writes only state.json under /tmp/snappy-image-<slug>/; it does NOT touch state/log/chain.ndjson or state/log/evals.ndjson. The snappy-os runtime is responsible for the row.

Commands

| ui dashboard | state/skills/image/resources/ui.openui |

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/image/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Skill-owned Lang shape (defineComponent, zod schema, view): state/skills/image/ui.tsx. This is the canonical source for ImageGalleryPreview and its sub-shape ImageGalleryPreviewImage - their props (images, captions, the 2-col grid contract), descriptions, and view chrome. Snappy-chat re-exports them from web/src/genui/image-gallery-preview.tsx; do NOT inline a parallel definition there. Surfaced + enforced by state/lint/skill-shape-locality.ts.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Empty string for text is valid (text-free background for composite). The gate does not treat empty text as missing.
• The shell exit code is irrelevant - the verdict field in the inspector's structured JSON is the signal.
• Run-this from drain is a paid call (Nano Banana 2 + Gemini Pro vision). When briefs queue image for "RUN THIS" without illustration/text/slug inputs, emit [SKIPPED] rather than fabricating an eval row.
• The 6-layer composite template lives inside the helper scripts - there is no templates/ directory.

Self-Test

An agent reading this should correctly:

1. [ ] Use the helper scripts in state/bin/image/ (NOT a non-existent templates/)?
2. [ ] Skip §4a (em-dash) checks on image-prompt frontmatter?
3. [ ] Run compose-ref.sh --contrast-check before compositing logos?
4. [ ] Trust the verdict field, not the shell exit code?
5. [ ] Read frame kind as one of draft|auto-edit|manual-edit (NOT final) and treat only frame[0].verdict as the score signal?
6. [ ] For educational formats, describe each zone's visual shape - never embed stage/letter labels in the drawing area?
7. [ ] Recognize --max-auto-turns as effectively 1 until the script's retry loop is added?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] image: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.