From 94bbfd3ec9258c56dda3aa12b4c2691583da295c Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Mon, 2 Nov 2026 07:49:39 -0800 Subject: [PATCH] docs: r8 image-use findings Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0185ukXgk6UunFCKyXqLe2Cq --- .../notes/2026-11-02-r8-image-use-findings.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/superpowers/notes/2026-11-02-r8-image-use-findings.md diff --git a/docs/superpowers/notes/2026-11-02-r8-image-use-findings.md b/docs/superpowers/notes/2026-11-02-r8-image-use-findings.md new file mode 100644 index 0000000..3dd1111 --- /dev/null +++ b/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/`, 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/` is not verified.** The cleaner accepts any `assets/`; 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.