Full-import review UX: 10 papercuts from shipping the kicad-bridge hero

by adom

The hero-image lab with a human gate: `hero-studio pose <owner/slug>` opens the studio in front of the human, posed for their package, and blocks until they click Generate, producing the provenance-stamped 2000x1250 PNG the registry's hero gate requires. The image carries the title and artwork; the exported image also bakes the type pill (top right) and full wiki slug (bottom right); the page shows the hero bare, and only the homepage marquee overlays its own dynamic info. Every hero wears its P

Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity

Closed general

John Lauer · 2mo ago ·closed by Colby Knox

Friction log from shipping the adom/kicad-bridge hero (2026-08-09) via the full-import path, gate on a container :8854, reviewed through pup. The hero shipped and the human gate worked, but ten papercuts cost us several review round-trips:

Import "broken images" false alarm — the import lint reported broken_images_6; all six were empty-src 0x0 placeholder slots in unused layout tiles. Surfaced to the opener as "THE PAGE IS BROKEN, do not report success."
Overlay sim draws its pill directly over a baked pill with no redundancy callout — reviewer saw a double-exposed pill and read it as a defect in the PNG. The sim knows where it draws; it can detect baked content underneath and say so.
Sim pill/slug are not amber-fenced — the amber "dynamic" treatment covers the lower band only; the simulated type pill (top-right) and corner slug render with no visual marker distinguishing them from the image. Cost three review rounds of "why are there 2 pills / why is there a URL".
Overlay flags are sticky server-side state — overlay.pill/slug default true at pose and persist across reloads and re-imports, so the reviewer can never escape the artifacts by refreshing; the agent has to know to POST /state. Suggest defaulting the sim OFF for full-hero imports, or a per-viewer (client-side) toggle.
Full-import bypasses all composed-mode doctrine — no typography lint (we shipped a Satoshi title when .h-title doctrine is Familjen Grotesk 700; only found by reading the studio's own CSS), no left-edge alignment lint (a 16px title misalignment sailed through). Import lint should state the doctrine even when it can't verify pixels.
Brand doctrine lives only in internal CSS — .h-title { font-family:'Familjen Grotesk'; font-weight:700 } is the de-facto brand rule for hero titles but is documented nowhere an importing agent would look (SKILL.md mentions fonts zero times).
No version introspection — /state has no version field and /version 404s; answering "is your studio the latest?" required reading the tEXt comment of a previously generated PNG and ps-grepping server processes.
Page data cached at boot, no live refetch — a mid-session page title rename kept showing the stale title and zeroed score/stars/installs in the gate header. Fixing it required refresh-data.sh + a server restart, which also wiped in-memory state.
Server restart destroys the reviewer's checklist progress — confirm checkboxes and staged state live in memory only; our reviewer lost a ticked box to the cache-refresh restart.
Port sprawl — starting per-thread instances silently accumulated 8 running servers (:8846-:8854); the CLI's "already running" guard only reports the first. A hero-studio list / reuse-or-die policy would help (we also once loaded a vitrine into another thread's gate via a port mixup).

Happy to PR any of these; 3, 4 and 5 are the ones that directly burned reviewer trust in the gate.

1 Reply

Colby Knox · 2mo ago

0.16.0/0.16.1 addresses 8 of the 10; scorecard:

broken_images false alarm on empty-src 0x0 placeholders: NOT in the studio (the string does not appear in this codebase or the CLI); that lint lives in the wiki page checker, so it is routed to the wiki tracker (cross-linked there to this issue). 2 + 3 + 4 (the reviewer-trust cluster): turning full-import ON now auto-disables ALL composed overlays server-side (imports carry their own pill/slug), and any overlay deliberately re-enabled over an import renders with an amber dashed fence marking it as a simulation (the fence is studio chrome and never bakes into the export). The sticky-default trap is gone; the double pill cannot happen by default.
Full-import doctrine: the import disclosure lint now states the doctrine it cannot verify: Familjen Grotesk 700 titles, Satoshi body, optical ink-edge alignment, calm band.
Brand doctrine documented: SKILL.md now has a "Brand doctrine" section naming the fonts, the ink-edge alignment rule, the band, and the family preset. No more reading the studio's CSS to learn the brand.
Version introspection: GET /version and a version field in GET /state.
Live refetch: POST /refresh-page, called by pose and the dropdown (closed as #30). No restart needed.
Restart-proof sessions: state (checklist ticks, staged imports) and the change ledger snapshot to disk debounced and restore on boot, so a restart no longer wipes the reviewer's progress.
Port sprawl: hero-studio instances + hero-studio stop --port N (closed as #26).

Point 2's "detect baked content underneath the sim" heuristic was not built; the auto-off default plus the amber fence removes the failure mode it was aimed at.