# Makeables images

Local reference tools need no generation service, account or repository checkout.
Use these when `cards` needs measured geometry, preparation or selective tracing.
Parameters are a JSON object (or `@file`) passed through `--params`. Outputs use
new paths; originals are never overwritten. Read each generated preview.

```sh
makeables image detect --file reference.png
makeables image prepare --file reference.png --out prepared --params '{"crop":"20,30,1000,630","patch":["80,80,120,80,300,80,6,0"]}'
makeables image trace --file prepared --out card.svg --params '{"title":"My card","credit":"Source and author","tones":7}'
makeables image sample --file reference.png --params '{"points":["20,30","100,80"]}'
makeables image measure --file reference.png --params '{"rows":"100,200","cols":"80","dark":250}'
makeables image map --file reference.png --params '{"box":"10,20,100,80","colors":6}'
makeables image glyphs --file reference.png --out glyph.svg --params '{"box":"20,30,200,80","at":"100,200","fill":"#111111"}'
makeables image rotate --file portrait.svg --out card.svg --params '{"top":"left"}'
makeables image compare --file card.svg --ref reference.png --out compare.png --params '{"upright":"left","ref-box":"20,30,756,1200"}'
makeables validate --file card.svg --out preview.png
```

`detect` suggests crop regions; inspect the image rather than trusting the
heuristic. `prepare` uses source-pixel coordinates, crops near the 1200:756 ratio,
patches from the untouched source and fills background at the crop border.
A patch is `destinationX,destinationY,width,height,sourceX,sourceY,feather,flop`;
only remove details the user wants removed. Compare every patched area closely.
Optional `edge-band` and `bg-tol` tune edge cleanup. A substantially different
crop ratio is rejected to avoid stretching; rotate portrait objects instead.

`trace` uses 2–12 luminance bands and optional `ink` threshold (0–1). `raster:true`
keeps the prepared image under vector ink. Tracing and `glyphs` require the
optional `potrace` executable; `makeables doctor` checks it. Install it only
within the user's installation authorization (macOS: `brew install potrace`).
Other operations do not need potrace. No automatic package install occurs.

`sample` returns a local 3×3 color average and center pixel. `measure` returns
dark runs in rows/columns; use these for borders, stroke slopes and barcodes.
`map` produces a color legend and a small pixel map (at most 160 × 200).
For flat reference objects, use measured shapes, shared geometry and original
text; trace unusual glyphs selectively. Keep counters with even-odd fill. Draw
portrait objects upright, retain proportions, then rotate the entire card.

Web research is optional and uses tools available in the current agent session.
Prefer official sources for assets and provenance, use community sources for
context, and do not bypass bot checks or invent permission. Preserve attribution
and distinguish an unofficial colorway from a documented variant. Respect no-web
requests; these CLI tools operate on local inputs.

## Optional image generation

Use this after the user chooses generation or requests a change that needs new image content. A style reference alone does not authorize transforming the portrait. Honor an original-photo or filters-only choice; editable monochrome, tint, thermal, crop and other native treatments do not require ai-cli.

Distinguish transforming the person's photo from generating separate decorative artwork. A portrait transformation needs the actual portrait, not just the style reference. Keep the person's identity, framing, pose and proportions. For separate artwork, leave the portrait unchanged unless the user also requested its transformation.

Check `makeables preflight --json` (add `--probe` to catch an invalid key before the run). If no generator is ready, use the host's own image tool when it has one; otherwise ask whether to install ai-cli for the requested transformation, then run:

```sh
npm install --global ai-cli
ai image --help
ai models --type image --json
```

Use the installed CLI's setup instructions for the user's AI Gateway credentials. Never put keys in chat, files, prompts, page storage, WebMCP arguments or the session URL. Explain that generation sends the selected source images to an external provider and uses Gateway credits separately from the coding agent's subscription. Confirm that processing and spending if not already authorized. If declined, offer the original photo or editable filters and continue with the user's choice.

Use the original local photo where available. To transform the current editor photo instead:

```sh
makeables studio call badge_get_image --url "$MAKEABLES_URL" --params '{"target":"portrait"}' --json > portrait-response.json
makeables image extract --file portrait-response.json --out portrait.webp
```

The extraction helper also accepts agent-browser's WebMCP JSON envelope and refuses to overwrite files. Keep image bytes out of the conversation.

Choose a currently available model that accepts reference images. Verify the installed `ai image --help` flags, then use a prompt tailored to the design:

```sh
ai image -m "$BADGE_IMAGE_MODEL" -i portrait.webp --output transformed.png --json \
  "Transform only the supplied portrait into detailed pixel art. Preserve this person, head-and-shoulders framing, pose and proportions. No typography and no invented body."
```

For a cutout, request background removal explicitly and inspect whether the output has real alpha. An opaque background is not transparency. Do not report an image as transformed if generation failed; keep the original and explain the failure.

Import the result using a fresh state:

```sh
makeables studio call badge_inspect --url "$MAKEABLES_URL" --params '{"section":"state"}' --json > state.json
makeables image params --file transformed.png --state state.json > image-params.json
makeables studio call badge_set_image --url "$MAKEABLES_URL" --params @image-params.json --json
```

For artwork, add an image layer first, then pass `--target artwork` to `image params`. Inspect the resulting badge on both faces. Original and generated images stay separate so the user can return to the photograph.