docs(readme): gallery-first hero shot above the fold (#67) (#94)

* docs(readme): gallery-first hero shot above the fold (#67)

Issue #67 (T5 Leader frontend-architect + T1 Expert business-panel
Godin/Drucker): README was text/badges-first; hackathon judges saw a
wall of badges before any visual payoff. Business panel recommendation
was to lead with the gallery hero shot — "screenshot-worthy moment is
the 26 tiles, not the modal form".

Changes:

- New: tools/capture-gallery-hero.py — playwright-based deterministic
  screenshot helper. Reads runs/r-clean-20260425-max/mockups/gallery.html
  (W4.10 evidence, 26-card max profile = highest visual density),
  renders viewport-only at 1600x1100 with device_scale_factor=2 (retina),
  outputs docs/assets/v1.6-gallery-hero.png (3200x2200, ~190KB).
  Animations disabled, fonts loaded, file:// URI for offline determinism.

- New: docs/assets/v1.6-gallery-hero.png — captured artifact, committed.

- README.md: hero <img> embedded immediately after H1 + tagline; badges
  pushed below hero block; "TDD/SpecDD/PreviewDD" pitch repositioned as
  caption-style footer of the hero band. The 3-DD methodology table
  remains intact further down — not deleted, just no longer pre-fold.

- docs/SUBMISSION.md: same hero embedded after H1 (with caption tying
  it back to the spec narrative).

- docs/DEMO-STORYBOARD.md: hero embedded after H1, captioned as the
  0:50–1:02 cut from the demo storyboard (matches the existing
  storyboard timing).

Codex review (single pass): 0 P1, 1 P2 noted as out-of-scope follow-up:
- Playwright is an undeclared local dev dependency (the binary is on
  the user's PATH but no requirements.txt / pyproject.toml). The hero
  PNG is now committed, so re-capture is only needed when the gallery
  template changes — a separate dev-tooling PR can pin Playwright if
  this becomes a regular workflow.

Closes #67

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(readme): apply PR #94 review feedback (gemini)

- tools/capture-gallery-hero.py docstring: corrected mode description
  (was "full-page", actual default is viewport-only — gemini medium #1).
- Replaced redundant wait_for_load_state("networkidle") with
  page.evaluate("document.fonts.ready") so fonts actually rasterise
  before capture (gemini medium #3).
- Default --source path retained: runs/r-clean-20260425-max/mockups/
  gallery.html IS committed (W4.10 evidence at PR #92), so the
  default works for any clone (gemini medium #2 — explained in reply).

Re-ran capture: PNG size unchanged (~190 KB, 3200×2200).

Refs PR #94 review comments

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sgwannabe

README.md

@@ -2,10 +2,17 @@
 
 # Preview Forge for Claude Code
 
-### `TDD` drove code with tests. `SpecDD` drove code with specs. We put `PreviewDD` in front.
+### One-line idea → 26 AI-generated previews in your browser. Pick with your eyes.
 
-**A self-contained Claude Code plugin that introduces the 3-DD Methodology.**
-143 Opus 4.7 agents turn a one-line idea into a frozen full-stack app with only two human clicks.
+![26 advocate gallery at Gate H1 — Preview Forge v1.6](docs/assets/v1.6-gallery-hero.png)
+
+> Above: Gate H1 gallery — 26 advocate-generated mockups, side-by-side, in your browser.
+> You pick the one that matches your intent. The rest of the pipeline (spec, tests, deploy)
+> is driven by that pick.
+
+</div>
+
+<div align="center">
 
 [![CI](https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode/actions/workflows/ci.yml/badge.svg)](https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode/actions/workflows/ci.yml)
 [![Marketplace Validate](https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode/actions/workflows/marketplace-validate.yml/badge.svg)](https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode/actions/workflows/marketplace-validate.yml)
@@ -20,6 +27,11 @@
 [![14 Slash Commands](https://img.shields.io/badge/%2Fpf%3A*-14%20commands-7aa6c2)](#slash-commands)
 [![Stars](https://img.shields.io/github/stars/Two-Weeks-Team/PreviewForgeForClaudeCode?style=social)](https://github.com/Two-Weeks-Team/PreviewForgeForClaudeCode/stargazers)
 
+`TDD` drove code with tests. `SpecDD` drove code with specs.
+**We put `PreviewDD` in front.** Mockup-first, eyes-first decision-making —
+143 Opus 4.7 agents turn one line of idea into a frozen full-stack app
+with only two human clicks.
+
 </div>
 
 ---

docs/DEMO-STORYBOARD.md

@@ -1,5 +1,9 @@
 # 3-Minute Demo Storyboard — Preview Forge v1.7+ (gallery-first)
 
+![Gate H1 gallery hero — 26 mockups](assets/v1.6-gallery-hero.png)
+
+> 0:50–1:02 cut: this is the screenshot judges see in the demo.
+
 > 해카톤 제출용 데모 영상. 180초 타깃, 170–190초 허용. 첫 5초가 고정적으로
 > "PreviewDD 이게 뭔데?" 후크. 마지막 10초는 저장소·라이선스 박제.
 > v1.7 ship 이후: **gallery-first** 톤 — Socratic 질문(4개)에서 바로 26 mockup

docs/SUBMISSION.md

@@ -1,5 +1,10 @@
 # Hackathon Submission Package
 
+![Preview Forge gallery — 26 advocate-generated mockups at Gate H1](assets/v1.6-gallery-hero.png)
+
+> 26 mockups, side-by-side, in your browser. Pick the card that matches
+> your intent — that picture becomes the spec.
+
 > 해카톤 제출 폼에 넣을 준비 완료 텍스트 + 체크리스트.
 > 마감: 2026-04-26 20:00 EST.
 > Version: v1.10+ (Phase 9 — Business-panel UX shipped: Socratic interview 4-required + Skip-interview + tiered fallback).

docs/assets/v1.6-gallery-hero.png

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Capture the v1.6 gallery-hero screenshot used in README.md (#67).
+
+Source: runs/r-clean-20260425-max/mockups/gallery.html (26-card profile —
+maximum visual density per hackathon-judge JTBD). The W4.10 evidence
+artifact is committed to the repo, so re-running this script produces
+the same PNG without needing to regenerate the gallery.
+
+Output: docs/assets/v1.6-gallery-hero.png
+
+Mode: viewport-only capture at 1600x1100 with device_scale_factor=2
+(retina), giving a 3200x2200 PNG. Picked over full-page because
+full_page captures the entire 26-card vertical strip (~3200x8200) which
+renders as a comically tall banner in the README; viewport-only shows
+the "lots of tiles side-by-side" wow factor in a normal banner ratio.
+
+Determinism: fonts loaded, animations disabled, viewport pinned, file://
+URI. Re-running on the same gallery.html produces a byte-stable PNG.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from playwright.sync_api import sync_playwright
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--source",
+        default=str(REPO / "runs/r-clean-20260425-max/mockups/gallery.html"),
+        help="path to gallery.html",
+    )
+    parser.add_argument(
+        "--out",
+        default=str(REPO / "docs/assets/v1.6-gallery-hero.png"),
+        help="output PNG path",
+    )
+    parser.add_argument("--width", type=int, default=1600)
+    parser.add_argument("--height", type=int, default=1100)
+    parser.add_argument(
+        "--full-page",
+        action="store_true",
+        help="capture entire scrollable page (default: viewport only — README hero wants above-fold density, not a 26-tile vertical strip)",
+    )
+    args = parser.parse_args()
+
+    src = Path(args.source).resolve()
+    out = Path(args.out).resolve()
+    if not src.is_file():
+        print(f"capture-gallery-hero: source not found: {src}", file=sys.stderr)
+        return 1
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    with sync_playwright() as pw:
+        # Firefox is the only browser already installed locally per the
+        # plan's preflight; falls back to chromium if firefox unavailable.
+        try:
+            browser = pw.firefox.launch(headless=True)
+        except Exception:
+            browser = pw.chromium.launch(headless=True)
+        ctx = browser.new_context(
+            viewport={"width": args.width, "height": args.height},
+            device_scale_factor=2,  # crisper PNG for retina demos
+            reduced_motion="reduce",
+        )
+        page = ctx.new_page()
+        page.goto(src.as_uri(), wait_until="networkidle")
+        # Disable animations + transitions deterministically.
+        page.add_style_tag(content="*, *::before, *::after { animation: none !important; transition: none !important; }")
+        # Wait for web-fonts to actually rasterise (gemini #3 — networkidle
+        # doesn't cover document.fonts state on every browser).
+        page.evaluate("document.fonts.ready")
+        page.screenshot(path=str(out), full_page=args.full_page)
+        browser.close()
+
+    size_kb = out.stat().st_size / 1024
+    print(f"capture-gallery-hero: wrote {out} ({size_kb:.1f} KB)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())