docs: r8 image-use findings

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185ukXgk6UunFCKyXqLe2Cq

docs/superpowers/notes/2026-11-02-r8-image-use-findings.md

@@ -0,0 +1,40 @@
+# Round 8: how Sitesmith uses uploaded images, and what still looks template-like
+
+Read: whp `web-files/libs/sitesmith-prompts.php` (Images / Using the owner's images rules, `sitesmith_assets_block`),
+`Sitesmith.php` (asset context, captioning, prompt assembly, site build), `SitesmithMedia.php` (`assetContext`),
+craft `clean-ai-response.ts`. Static reading only; no host or gateway contact, no live generations.
+
+## How it works today
+- `assetContext()` lists up to 30 raster/other assets, newest mtime first, with filename, `assets/<file>`, dims, cached caption/alt.
+- Thumbnails (max 6, ~1024px) and the one-shot caption call only happen when `use_assets` is true AND the model can see images.
+  The modal sends `use_assets` true unless the owner un-ticked every asset.
+- The prompt says: every page shows at least one image; owner photos first; "MUST use at least one" in hero or a feature; match by
+  caption and shape; each photo once per page.
+- Site builds: page calls reuse the user turn WITHOUT thumbnails (captions in text only).
+
+## Gaps (ordered by likely impact on template-looking output)
+1. **No enforcement, prompt-only.** "MUST use at least one uploaded image in the hero or a feature" is never checked after the
+   response. A hero built from Section + text (or HeroSimple on a gradient) with photos available passes through unchanged.
+   Suggested: a post-clean check in `clean-ai-response`/`apply-ai-response` that, when assets were offered and the response
+   references none of them, adds a note to the message and/or triggers one bounded repair call (reuse the CTA-check pattern).
+2. **Invented or mistyped `assets/<file>` is not verified.** The cleaner accepts any `assets/<name>`; a wrong filename publishes
+   a broken image. The editor knows the real asset list: drop or swap unknown `assets/` URLs (to a placeholder) with a note.
+3. **Captions are thin or absent in common cases.** Only thumbnailed files (first 6 by mtime) are captioned; files 7-30 are
+   listed by filename only (often `IMG_1234.jpg`), so "match by caption" cannot work for them. Caption failures fall back to
+   filenames. Suggested: caption in batches beyond 6 (thumb-less is impossible, but a second batched call is cheap) or at upload time.
+4. **Selection is mtime-ordered, not relevance-ordered.** With >30 uploads the oldest (often the hero-quality shots) are not listed.
+   Logos, icons, screenshots and tiny images are not classified; nothing tells the model which files are hero-worthy
+   (dims are given, but no "usable as full-bleed: >=1600px wide landscape" hint). Suggested: compute a `role` hint server-side
+   (logo-like: small/transparent PNG/SVG; hero-candidate: landscape >=1400px; portrait; small) and print it in the asset row.
+5. **Site builds pick photos per page independently.** The plan call carries no image assignment, so every page may choose the same
+   best photo for its hero ("once per page" only). Suggested: plan emits `heroAsset` per page; page calls get that assignment.
+   (This round adds a one-line prompt nudge only.)
+6. **Page calls lose the thumbnails** (cost), so quality of matching on later pages depends entirely on captions (gap 3).
+7. **Low-resolution photos as full-bleed backgrounds** are not flagged (dims are in the row but there is no size rule), so a
+   600px upload can be stretched across a hero.
+8. **Placeholders when there are NO uploads**: heroes become flat boxes (this round: contrast-safe colour plus an editor-only
+   "Add a photo here" hint). A real stock/AI image option is still the only way to avoid the empty feel on first generation.
+
+## Done this round (small and safe)
+- Prompt tweak (whp `sitesmith-prompts.php`): home hero uses the largest landscape owner photo; other pages prefer a different
+  hero photo while unused photos remain. Prompt and all sitesmith PHP tests pass.