feat: update instructions

.claude/skills/gen-image/SKILL.md

@@ -49,6 +49,17 @@ node <skill-dir>/banatie-gen.mjs \
 
 The reference image gives the AI a visual anchor (composition, colors, overall shape) while the prompt steers it toward the desired changes. This produces much better results than generating from scratch with a new prompt, because the output stays visually consistent with the original.
 
+## Reference Image Policy
+
+**Never add `--ref` silently when creating a new image.** The rules:
+
+1. **User explicitly provides a ref** (file path or @alias) → use it
+2. **Modification mode** (user gives feedback on an existing image) → use the existing image as ref automatically
+3. **New image, similar assets exist nearby** → **ask the user first**: "I see [filename] in the same folder. Would you like to use it as a reference for visual consistency, or generate from scratch?" Do not assume.
+4. **New image, no similar context** → generate from scratch, no ref
+
+The project's CLAUDE.md may override this policy with project-specific ref rules (e.g. "always use X as ref for assets in folder Y"). If CLAUDE.md provides ref guidance, follow it without asking.
+
 ## Workflow
 
 1. **Determine the mode.** Is this a new image or a modification of an existing one? If the user gives feedback on a recently generated image or asks to change something about an existing file, use modification mode.

CLAUDE.md

@@ -147,6 +147,16 @@ When generating HTML worksheets:
 
 Use the `/gen-image` skill to generate images via the Banatie API. The skill has its own script and full API documentation in `.claude/skills/gen-image/`. Auth via `BANATIE_KEY` in `.env`. Rate limit: 100 requests/hour.
 
+### Reference Policy for This Project
+
+When generating new assets for `assets/items/`, use existing images from the same subfolder as `--ref` to maintain visual consistency across the set. For example, when creating `asteroid2.png`, reference `asteroid1.png` from the same folder. The gen-image skill's default policy is to ask before using refs — this project overrides that: use refs automatically for items in the same asset group.
+
+Style reference chain for themed assets:
+- `assets/items/asteroids/` — use any existing asteroid as ref for new ones
+- `assets/items/crystals/` — use any existing crystal as ref for new ones
+- `assets/icons/` — generate independently (icons have their own pipeline via icon packs)
+- `assets/hero-images/`, `assets/footers/`, `assets/backgrounds/` — generate independently, no refs needed
+
 ## Background Removal
 
 Script `src/scripts/remove-bg.mjs` removes white backgrounds from PNG icons using flood-fill from edges (like magic wand in Photoshop). Uses sharp. White areas inside objects are preserved.

assets/items/asteroids/CLAUDE.md

@@ -0,0 +1,57 @@
+# Asteroid Asset Generation Rules
+
+## Style overview
+
+The set has two tiers:
+
+**Single-piece asteroids (asteroid1–asteroid9)** — each is a standalone rock with its own unique shape and crack color. They serve as style sources for multi-piece variants.
+
+**Multi-piece asteroids (asteroid10–asteroid14)** — compact clusters of 3 pieces tightly pressed together. Each one inherits its style from a corresponding single-piece asteroid.
+
+## Style map
+
+| File | Shape type | Crack color | Style source |
+|------|-----------|-------------|--------------|
+| asteroid1 | round sphere | orange/amber | — |
+| asteroid3 | flat angular boulder | red glowing | — |
+| asteroid5 | tall elongated shard | purple/magenta | — |
+| asteroid7 | flat horizontal disc | pink/purple | — |
+| asteroid9 | tall spire with spikes | cyan/blue | — |
+| asteroid11 | 3-piece cluster | red (from asteroid3) | asteroid3 |
+| asteroid12 | 3-piece cluster | orange/golden (from asteroid1) | asteroid1 — **ideal composition reference** |
+| asteroid13 | 3-piece cluster | purple/magenta (from asteroid5) | asteroid5 |
+
+## Rules for generating new multi-piece asteroids
+
+### Composition
+- Always 3 pieces of **different sizes** tightly pressed together
+- Pieces must touch each other — no gaps, no space between them
+- The cluster must read as one compact object, not a scattered group
+- Vary the arrangement: triangle, stacked, side-by-side — avoid repeating the same layout
+
+### Style
+- Use `--ref` with the corresponding single-piece asteroid (not asteroid12)
+- Do not use `--template illustration` — it makes cracks too prominent and overrides the source style
+- Use the default `--template general`
+- Crack color, surface texture, and painting style must come from the reference
+
+### What to avoid
+- No floating debris or separate small fragments
+- No explosion effects
+- No atmospheric glow, energy bursts, or lightning spread outward from the object
+- No changing the crack color relative to the reference (e.g. if the ref has red cracks, the output must have red cracks — not orange, not purple)
+
+## Generation command pattern
+
+```bash
+node .claude/skills/gen-image/banatie-gen.mjs \
+  --prompt "three dark rocky asteroid pieces of different sizes tightly pressed together, <crack description from ref>, painterly art style, white background, compact cluster no gaps between stones, varied shapes and sizes" \
+  --output assets/items/asteroids/asteroidN.png \
+  --ref assets/items/asteroids/asteroidX.png
+```
+
+Where `asteroidX` is the style source from the table above.
+
+## Approved reference for composition
+
+**asteroid12.png** is the approved example of correct multi-piece composition: compact, no gaps, pieces vary in size, reads as one unit. Use it as a visual benchmark when evaluating new generations — but do NOT add it as `--ref` alongside the style source, as it will pull the style toward orange/golden.