perf(images): WebP banners, text-only related cards, resized list thumbnails

Measured before/after with headless Chrome + CDP (not by eye):

- article banner: <picture> WebP q78 with the PNG as fallback, because the PNG
  must stay for og:image (social scrapers do not reliably render WebP cards).
  70 banners: 6.02 MB -> 2.52 MB (42%). JPEG measured *larger* than PNG here
  (q85 = 129%) — the art is flat terminal-style with sharp text edges.
- post page related cards: dropped four 1200x630 PNGs (183 KB) to display
  526x276 where the embedded code is illegible; now text-only cards with a
  category badge, date and reading time.
- list thumbnails (home + archive): new /og/thumb/<name>-{400,800}.webp served
  via srcset/sizes. Rows display at ~398px but were pulling full 1200x630 PNGs.
  Homepage thumbnails ~450 KB -> 62 KB; archive (71 rows) ~3.2 MB -> 436 KB.
- desktop banner capped at 720px centred: 67% -> 45% of a 900px viewport,
  keeping the art intact instead of cropping it.

Post page totals: images 277 KB -> 38 KB; page height 5758 -> 5065 (desktop)
and 9423 -> 8807 (mobile). Build: 163 pages.

Script: scripts/optimize-images.py; policy: docs/design-guide.md §3; runbook
step added to docs/ops-runbook.md.

docs/design-guide.md

@@ -32,6 +32,16 @@ Read this **before** touching theme, layout, typography, color, or SEO markup. P
 
 - **Mobile-first**: design 390px, then desktop 1280px.
 - **Astro Image** for automatic optimization/WebP (Core Web Vitals win).
+- **Image format policy (measured 2026-10-16 — do not guess this one):**
+
+  | Asset | Served as | Why |
+  |---|---|---|
+  | `og:image` / `twitter:image` | **PNG** (1200×630) | Social scrapers (WhatsApp / LinkedIn / FB / Telegram) do not reliably render WebP share cards. Compatibility beats bytes here. |
+  | Article banner in-page | **WebP q78** + PNG fallback via `<picture>` | 6.02 MB → 2.52 MB across 70 banners (42%); JPEG would be *larger* (q85 = 129% of PNG) because the art is flat terminal-style with sharp text edges. |
+  | List/related thumbnails | **WebP q72 at 400w + 800w** (`/og/thumb/<name>-400.webp`) | Rows display at ~398px; they used to fetch the 1200×630 PNG (~45 KB). 400w is 5.8 KB, 800w is 16.1 KB. The homepage went from ~450 KB of thumbnails to ~62 KB. |
+  | Real photos (author, hardware) | **WebP q82** + JPEG fallback | Continuous-tone images are the opposite case from the flat art above. |
+
+  Regenerate all derivatives after adding a post: `uv run --with pillow python scripts/optimize-images.py`.
 - **Declare `og:image:width/height` explicitly** — mis-declared dimensions get preview cards rejected by WhatsApp/Telegram/LinkedIn.
 - **Favicon**: reference all sizes (`.ico` + 32×32 + 192×192 PNG + apple-touch 180×180). "Favicon not showing" is usually browser cache, not a missing asset — `curl` the live files before "fixing".
 

docs/ops-runbook.md

@@ -21,6 +21,11 @@ Markdown (src/content/posts) → Astro build (dist/) → Gitea Actions → act_r
 1. Create `src/content/posts/<slug>.md` with frontmatter (see `content-guide.md` §6).
 2. Push to `main`.
 3. CI builds `dist/` and deploys to the nginx container automatically.
+   - **Before pushing a post that adds art**, generate its in-page derivatives:
+     `uv run --with pillow python scripts/optimize-images.py <slug>`
+     (banner `.webp` + `/og/thumb/<name>-{400,800}.webp`). The PNGs from
+     `banner-gen` / `og-gen` remain the `og:image` source of truth — see
+     `design-guide.md` §3 for the format policy and measured sizes.
 4. Verify live: `curl -I https://blog.hoelee.com/<slug>` → expect 200.
 
 ---

docs/project-state.md

@@ -28,6 +28,12 @@ Living list of what's done and what's next for blog.hoelee.com. Work through the
 - ✅ Knowledge guides in `docs/` + README index + `hoelee-blog` skill
 - ✅ Both repos public (Gitea + GitHub) with title/description/homepage/topics + `v1.0.0` release
 - ✅ **Live re-audit of the Sept research recorded (§2 Phase E + §4), 2026-09-29** — 53 posts × 2 languages, 127 sitemap URLs, 133/133 internal links 200
+- ✅ **B1 image batch, 2026-10-16 (first batch from the external design review)** — measured with a real browser before/after, not by eye:
+  - **Article banner** → `<picture>` with WebP q78 + PNG fallback: 70 banners 6.02 MB → **2.52 MB (42%)**. The PNG stays for `og:image` (social scrapers do not reliably render WebP cards). JPEG was measured *worse* than PNG on this art (q85 = 129%).
+  - **Related-post cards** on a post page → **text-only** (category badge + title + date + read time). They used to load four 1200×630 PNGs (183 KB) to display 526×276 where the art's code is illegible anyway.
+  - **List thumbnails** (home + archive) → `/og/thumb/<name>-{400,800}.webp` with `srcset`/`sizes` (400w 5.8 KB, 800w 16.1 KB). Homepage thumbnails **~450 KB → 62 KB**; archive (71 rows) **~3.2 MB → 436 KB**. They were fetching full 1200×630 PNGs for a 398px slot.
+  - **Desktop banner height** capped (720px, centred): 67% → **45%** of a 900px viewport, art intact rather than cropped.
+  - Measured post page: images **277 KB → 38 KB**, height **5,758 → 5,065px** desktop / 9,423 → 8,807px mobile. Script: `scripts/optimize-images.py`; format policy: `design-guide.md` §3; runbook step in `ops-runbook.md`.
 
 ---