Build Log

The bug wasn't in the CSS you'd expect

July 2, 2026

Found the real root cause of Known's 3-page print bug (the app shell, not the card), built Jan's printable onboarding guide from scratch, and corrected a wrong-org production seed before it became a real problem.

KnownBug FixGuideProduction Data

files fixed for the real print root cause

guide iterations to solve the artifact print/click problem

wrong-org prod write caught and corrected

user guides updated (in-app + website)

Timeline

Start

Update the Known user guide and define Jan's MVP path

Audited what shipped since the guide was last touched — household login, Labs, Known Card tiers, note-suggestions, research hub

~40m

Guide rewritten in both locations, MVP day-by-day artifact built

in-app guide (source of truth) + forgekit-website guide synced; day 1/2/week 1/2 critical path artifact for Jan

~1h

Print bug root-caused

Not CSS Grid pagination (already ruled out) — app/layout.tsx's html.h-full + body.flex.flex-col forces 2 blank print pages; fixed in KnownCard.tsx and the public care-card page

~1.5h

Attempted live screenshot capture, blocked by Clerk session rotation

Tried chromium-cli (not installed), then Python Playwright with cookie injection — Clerk's __session JWT expires ~60s after issue, cookie copy-paste couldn't outrun it

~2h

Switched to accurate mockups built from real component code/copy

Printable one-pager for Jan (70s, non-technical, iPad) — 5 steps + Known Card payoff + today-notes quick path, styled from Known's real palette

~2.5h

Print button in the artifact didn't work — 4 rounds of diagnosis

Ruled out: inline onclick blocked, script not executing, click not registering. Root cause: artifact renders in an iframe; window.print() prints whichever frame has focus, and it wasn't the guide's

~3h

Fixed with a two-step instruction instead of a broken button

'Click the guide first, then Ctrl+P' — the only reliable fix, since a button inside the iframe can't force focus on the parent's print target

~3.2h

Added the Known Card payoff and today-notes path to Jan's guide

User caught that the original guide never showed the result of answering questions, and left out the lower-effort today-note habit entirely

~3.5h

Prod reseed requested — present-tense seedData.ts language never pushed to prod

Confirmed seedData.ts (shared dev/prod source) already had the fix; ran seed-prod.ts, a re-runnable delete+reinsert script

~3.6h

Wrong org ID used on first prod write — caught immediately by Zeb

Used org id from an earlier session cookie instead of the actual seeded-demo org from a prior retro. Corrected: reran against the right org — portraits.id is the sole primary key, so the correction moved the row rather than duplicating it

End

Known deployed to production

npm run build passed locally, Zeb confirmed deploy, known.forgekits.build now serving the print fix and updated guides

What shipped

Known: fixed the real root cause of the 3-page print bug — app/layout.tsx forces html.h-full + body.min-h-full.flex.flex-col on every page; a flex-stretched body produces 2 blank pages in Chromium print. Fixed in components/KnownCard.tsx and app/care-card/[shareToken]/page.tsx with an explicit html/body print reset

Known: updated the in-app user guide (app/guide/page.tsx, source of truth) to cover household/org login, Labs opt-in, soft delete, the reworked Known Card core/secondary tier split, note-suggestions, the research hub, and import-from-a-recent-chat

ForgeKit website: synced forgekit-website/lib/guides/known.ts with the same substantive updates, plus a new FAQ entry on multi-family household access

Built a day-by-day MVP critical-path artifact for Jan's first two weeks of real use, graded against live code (not the roadmap) — flagged the print bug and the untested second-household-member invite as the two real risks before her first session

Built a printable, plain-language onboarding guide for Jan (70s, former teacher, non-technical, iPad) — opens with a 'What is Known?' explainer, 5 numbered steps with recreated real-copy mockups, the Known Card payoff, the today-notes quick path, and a troubleshooting section

Corrected a wrong-org production database write within the same session before it went unnoticed — demo-rick portrait moved to the correct household org via the idempotent seed-prod.ts delete+reinsert

“ok. it seems we were much better at working with the prod database this time. thumbs up. good work.”
— Zeb, at session close, contrasting this session's dry-run-first production handling with prior sessions' friction