Neo Kinpaku design system + Live Mode v3 (#169)

* Add neo kinpaku design system page * skill: rip out baked-in category recipes and saturated-default motion tropes Programmatic bias mining (impeccable-evals) traced four major defects back to specific lines in this skill that contradicted SKILL.md's own first-order-reflex warning: - brand.md "Pairing and voice" prescribed four category→aesthetic recipes (editorial → serif+sans, tech/dev/fintech → tight tracking, consumer/food/travel → script/display serif, creative → rule-break). These directly drove OpenAI's 76% extreme-negative letter-spacing on tech briefs and Anthropic/Google's 28-34% italic-serif-display slop on editorial/food briefs. Replaced with one sentence: the shape depends on the brand, not on the brand's category. - brand.md "Brand permissions" had "Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero." — a four-for-one slop driver behind 97% OpenAI comically-large H1, 42% bad-SVG illustration, and the editorial-italic slop. Deleted outright. - typeset.md and teach.md repeated the same category recipes; trimmed to the principle without the recipe. - SKILL.md Typography: added a hard hero-H1 ceiling (clamp() max ≤ 6rem ≈ 96px), with a <codex> block to make it explicit since OpenAI over-indexes here (97% ≥128px vs 24% for Anthropic). - animate.md, bolder.md, brand.md: removed "staggered reveals" and "scroll-triggered transitions" as the prescribed default ambitious motion. By 2026 that's the saturated AI tell, not a choreography. Reserved stagger for legitimate list-sibling rhythm. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: anti-cream + codex-specific defect bans + universal slop bans Second pass after measuring more biases against the eval corpus. - SKILL.md Color: explicit "cream/sand/beige body bg is the saturated AI default of 2026" rule. Tone down the "tint every neutral" line so it doesn't read as "default to warm-tinted near-white" (which OpenAI hits at 74% and Anthropic at 31%-47%). - SKILL.md Absolute bans: add universal bans for two slop patterns detected at 55-95% across providers — tiny uppercase tracked eyebrow above every section (the 2023-era kicker that's now AI grammar) and numbered section markers (01/02/03). Also explicit "text that overflows its container is the universal defect on tablet/mobile." - SKILL.md Absolute bans → <codex> block: ban the GPT-specific defects Paul annotated repeatedly — `border:1px solid` + soft-wide-shadow (≥16px blur) "ghost cards", `border-radius:32px+` over-rounding, hand-drawn/sketchy SVG illustrations (loose-sketch / *-sketch classes, feTurbulence paper-grain filters), repeating-linear-gradient stripes, "X theater" AI-slop copy phrases. - SKILL.md Motion → <gemini> block: the image :hover transform tell (38% Google skill-on rate). Hover effects on images add no info; the image isn't an action target. Animate card chrome, not the image. - SKILL.md Typography: hard display letter-spacing floor ≥-0.04em (OpenAI defaults to -0.075em → cramped). Existing hero ceiling <codex> block extended with the letter-spacing rule. - codex.md Step A example: stop seeding "warm-grounded (deep oxblood + cream)" as the warm-palette template, which primes the cream default. - colorize.md Tinted backgrounds: stop printing the literal cream recipe `oklch(97% 0.01 60)`; replace with brand-anchored guidance. - document.md examples: warm-ash-cream → cool-paper so the example doesn't seed cream as the canonical neutral example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: universal anti-slop bans + contrast/font-count/all-caps-body rules Third pass after measuring the rest of the cross-provider matrix: - Color: explicit "Verify contrast" rule. Low-contrast text fires at 68% across all providers skill-on (90+% off). The most common failure is muted gray body on a tinted near-white; light-gray-for- elegance is named as the single biggest cause of unreadable AI pages. - Typography: max-3-font-families rule. Overused-fonts (>4 families) fires at 28% Anthropic / 36% Google / 0% OpenAI skill-on; >50% off. Also: universal "no all-caps body copy" (moved from brand-only ban to Shared design laws since product-register also overuses caps). - Copy: anti-aphoristic-cadence ban targets Anthropic's signature "X. No Y." / "X. Just Y." voice (63% skill-on copy-slop rate, 77% off — the worst rate in the matrix). Once-is-voice / three-or-more- is-tell framing per the runner's copy-slop detector. - Copy: anti-SaaS-buzzword-string ban with the literal phrase list the detector watches for (streamline/empower/supercharge, trusted- by-leading, best-in-class/enterprise-grade/cutting-edge, etc). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: strengthen anti-cream rule across full warm-neutral band Smoke validation showed the cream fix worked for Google + OpenAI but Anthropic Sonnet italian-restaurant still shipped `--paper: oklch(90% .018 88)` — cream just outside the L≥95% band the rule cited. Broaden the rule: - Band: OKLCH L 0.84-0.97, C < 0.06, hue 40-100 (was 95-97% / 60-95). - Name the token-name tells explicitly (paper / cream / sand / bone / flour / linen / parchment / wheat / biscuit / ivory) — the model defaults to one of these regardless of what hex it lands on. - Call out the specific brief patterns ("warm, traditional, family- coastal-Italian" / "editorial-restraint") that the model translates into cream by reflex. Then provide three explicit non-cream options: saturated brand color, true off-white at C=0, or darker mid-tone. Warmth in the brand is carried by accent + typography + imagery, not by body bg. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v3.2.0: skill bias-fix release Bumps version from 3.1.1 to mark the four-commit skill cleanup that rips out baked-in category recipes (brand.md), saturated-default motion tropes (staggered reveals everywhere), the cream/sand body-bg AI tell, codex-specific defects (1px+wide-shadow, over-rounding, hand-drawn SVGs, stripes, X-theater copy), the extreme-letter-spacing default, and universal slop bans (all-caps eyebrow on every section, numbered-section markers, all-caps body, font-family-count > 3, aphoristic copy cadence, SaaS buzzword strings). Plus a hard hero-H1 ceiling (clamp() ≤6rem) and a Gemini-specific image:hover transform block. Validated against ~190 post-fix samples — see impeccable-evals biases tab for per-provider deltas. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * drop "no pure black/white" rule entirely The rule was contested in the design world and causing more damage than good — pushing every page into the tinted-near-white default which is the cream/sand AI tell we already explicitly ban elsewhere. Vercel, SVKMS, Brutalist sites, et al. use pure black/white successfully; the skill shouldn't second-guess that. Skill markdown deletions: - SKILL.md Color: drop the "Never use #000 or #fff" bullet. - color-and-contrast.md: drop the "Never Use Pure Gray or Pure Black" subsection, the "Never pure black" table-row prescription, and the "Avoid: Using pure black for large areas" bullet. - colorize.md: drop the "NEVER use pure black or pure white for large areas" bullet. - polish.md: drop the "Tinted neutrals: No pure gray or pure black" half of the bullet (the gray-on-color bullet survives). Detector code (cli/engine): - registry/antipatterns.mjs: remove the `pure-black-white` entry. - rules/checks.mjs: remove the three `findings.push({ id: 'pure-black-white', ... })` emit points (inline #000 bg, Tailwind bg-black class, plain-HTML scan path). - engines/regex/detect-text.mjs: remove the two pure-black-white regex rules (CSS `background: #000…` + Tailwind `bg-black`). - detect-antipatterns-browser.js: regenerated via scripts/build-browser-detector.js. Tests: - detect-antipatterns-fixtures.test.mjs: invert the assertion that pure-black-white fires; expect it to NOT fire post-v3.2. Drop the Tailwind bg-black-opacity edge-case test (no longer relevant). - detect-antipatterns.test.js: drop the standalone "detects pure- black-white in styled-components" test and remove pure-black-white from the multi-detector assertions in PricingCard, globals.css, and GlobalStyle.tsx tests. 166 bun tests pass; 24 node fixture tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: strip example patterns from copy rules, strengthen gemini block v3.2 rerun validation surfaced two issues: 1. Copy-slop detector fires more on Gemini under v3.2 (48% → 84%) than under no-skill baseline. Root cause: the anti-aphoristic-cadence rule printed the literal "X. No Y." / "X. Just Y." patterns as examples, and Gemini imitated them as the recommended voice. Same recipe-becomes- bias trap we hit with brand.md:116's "Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines" enumeration. Fix: describe the cadence as a rhythm ("serious statement, then punchy short negation") without printing literal patterns. Buzzword list trimmed to a single inline phrase family rather than quoted strings. 2. Gemini image:hover transform Gemini-tell hadn't dropped (31% off → 32% v3.2). Strengthen the <gemini> block: explicit "Never animate <img> elements on hover", call out the Tailwind group-hover:scale / group-hover:rotate / group-hover:translate parent-hover patterns by name (Gemini was reaching for these via Tailwind even though the prior text talked about :hover on the image directly). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: simplify context loading and inline register directive Replaces load-context.mjs's JSON output with a tight markdown block from the renamed context.mjs. The script now extracts PRODUCT.md's `## Register` field and appends a `NEXT STEP:` directive naming the matching reference (brand.md / product.md), which moved Gemini from skipping the register load entirely to honoring it. Drops the `.impeccable.md` auto-migration; makes IMPECCABLE_CONTEXT_DIR a lazy escape hatch consulted only when the default paths come up empty. Setup is now four bullets in one list. The DESIGN.md nudge is gone; in its place, a "familiarize with the existing design system" step that calls out CSS / tokens / running app as authoritative sources alongside DESIGN.md. The standalone `### Register` H3 stays for the cascade rules (task cue → surface → register field). New LLM-backed test suite at tests/skill-behavior/ runs five scenarios against claude-haiku-4-5, gpt-5.4-mini, and gemini-3.1-flash-lite via Vercel AI SDK. Captures real tool traces, asserts on context.mjs calls, brand.md loads, and teach.md fallback. Skips cleanly when API keys are unset. 13-14/15 pass; only stable failure is the v3.2.0-era gpt-mini S4 "don't re-run" regression. Adds @ai-sdk/google as devDep and the test:skill-behavior npm script. Touches em-dashes in skill/SKILL.md and four reference files so `bun run build:skills` passes its skill-prose validator. teach.md and document.md drop their "re-run the loader to refresh session cache" steps since the agent's own write is now the freshest source. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: merge orphan reference files into command sub-skills + inline S-tier invariants Two related restructurings: 1. SKILL.md now carries the cross-domain invariants that catch defects in any project (contrast/placeholder/gray-on-color, similar-font pairing, text-wrap, tabular-nums, centered-stack default, Flex/Grid choice, auto-fit grids, semantic z-index, reduced motion, stagger vs section-fade, premium motion materials, focus-visible, placeholders-aren't-labels, dropdown overflow trap, button/link copy). Greenfield-only rules (theme picking, color strategy, tinted neutrals) live under "New projects only". 2. Reference files merged into their command counterparts: - spatial-design.md -> layout.md - motion-design.md -> animate.md - color-and-contrast.md -> colorize.md - responsive-design.md -> adapt.md - ux-writing.md -> clarify.md - typography.md -> typeset.md (bolder.md redirected) - cognitive-load.md + heuristics-scoring.md + personas.md -> critique.md craft.md and shape.md "load references" lists updated to new file homes. interaction-design.md stays standalone (no 1:1 command verb). Net: 36 -> 27 reference files. Same content, fewer files, no orphaned reference loaded only from craft.md. Also extends the routing rules: if the user's first word doesn't match a command but the intent clearly maps to one, load that command's reference and proceed as if invoked. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: add sub-command + existing-project scenarios; move sub-command load to step 2 Adds three new LLM-backed scenarios to tests/skill-behavior: - S6: `/impeccable polish` → loads polish.md - S7: `/impeccable audit` → loads audit.md - S8: existing SvelteKit project (PRODUCT.md + DESIGN.md + src/app.css + src/lib/components/*.svelte + src/routes/+page.svelte) → agent reads at least one project code file to understand the existing design system S6/S7 surface a real model-floor: gpt-5.4-mini reads brand.md, reads the target index.html, and just does the polish/audit without ever loading the sub-command reference. Stronger SKILL.md wording didn't move it. Captured in the README baseline as a known weakness. Claude and Gemini honor the load reliably. To fix Gemini on S6/S7, sub-command reference loading is now Setup step 2 (right after context.mjs), not step 4 — placing it before the model gets focused on "doing the work". Step 3 (design-system familiarization) is tightened to require at least one project code read even when a sub-command reference loads in step 2, so Claude doesn't laser-focus on the sub-command flow and skip the broader exploration. Two new fixtures: MINIMAL_LANDING_HTML (a tiny static landing page for S6/S7) and SVELTE_PROJECT_FILES (a minimal SvelteKit scaffold with tokens, components, and a routes/+page.svelte for S8). Both designed to look real enough that agents treat them as production code. Suite is now 24 tests across three providers; baseline is 21-22/24, with the stable failures being gpt-5.4-mini scenarios 6 and 7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: add reveal-animation safety rule (must enhance, not gate visibility) Class-triggered visibility transitions pause on hidden tabs and headless renderers. The italian-restaurant smoke produced a build where 2 sections shipped opacity:0 because the CSS transition never advanced past currentTime=0 (timeline paused). Added one-liner under Motion to prevent the antipattern: reveals must enhance an already-visible default, never gate content visibility on a class-triggered transition. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: restore prescriptive cream/sand/beige paragraph Bisection across 5 historical skill commits on Gemini 3.5 flash fast lane n=3 found that 0cf2debd was the peak quality state. The regression between 0cf2debd and HEAD came from simplifying the long anti-cream paragraph into a one-liner. Restoring the paragraph (with em-dashes replaced by parens to satisfy prose lint) recovers ~0.22pt average on Gemini vs HEAD, with the largest gains on: - 09-luxury-hotel: +0.50 (restores editorial drama in photo-led briefs) - 10-food-magazine: +0.67 - 03-italian-restaurant: +0.51 The paragraph's load-bearing parts are the (a)(b)(c) alternatives that give the model actionable replacements for cream-tinted body bg ("saturated brand color as body", "true off-white at chroma 0", "darker mid-tone tinted neutral"). Without them, the one-line warning left the model with no concrete alternative. Cross-provider validation showed the pattern matches historical behavior: Gemini benefits from prescriptive scaffold (+0.12 over off), Sonnet is roughly neutral (+0.01), GPT-5.5 slightly regresses (-0.11 matching the v3.1.0 pattern of -0.11). The skill has never been uniformly better than skill-off across providers; this is the closest achievable state without provider-specific rework. The structural improvements from the prior restructure stay (file merges, S-tier inlines, routing rule extension, reveal-animation safety rule). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: teach CLAUDE.md / AGENTS.md / DEVELOP.md about the skill-behavior tests Adds the `bun run test:skill-behavior` script to the test commands lists in all three docs. CLAUDE.md gets a full `### Skill-behavior tests` subsection paralleling the existing Live-mode E2E one: how the suite works (inlines source SKILL.md, scoped tools, asserts on the trace), which providers it always runs (claude-haiku-4-5, gpt-5.4-mini, gemini-3.1-flash-lite — all three every run), the eight scenarios, the baseline (21-22/24 with stable gpt-mini sub-command-routing failures), auth via repo-root `.env`, and how to add a scenario. AGENTS.md gets the one-liner plus a paragraph in Testing Guidelines that points contributors at the suite for Setup-touching edits (SKILL.md Setup section, context.mjs, teach.md, document.md, register / sub-command refs). DEVELOP.md gets a short Testing section that didn't exist before, plus a nudge in the "Test across providers" bullet pointing at the new suite as the automated way to do that. No code changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * detector: add 5 new antipatterns (em-dash-overuse, broken-image, marketing-buzzword, numbered-section-markers, aphoristic-cadence) Consolidates eval-side detection logic into the canonical impeccable detector. Before this change, the eval harness had its own duplicate implementations of em-dash, copy-slop, and broken-image checks. They now live alongside the existing 28 antipatterns in the impeccable registry, available to the CLI, browser extension, critique skill, and eval (via the existing slop grader child-process call). New antipatterns: - em-dash-overuse: 5+ em-dashes in body text content (threshold permits legitimate prose use of em-dash; only triggers on AI cadence-level density) - broken-image: <img> with empty src, missing src, or src="#" - marketing-buzzword: SaaS phrase list (streamline / empower / supercharge / enterprise-grade / cutting-edge / etc) - numbered-section-markers: repeated 01 / 02 / 03 sequence as section labels — the AI editorial scaffold one tier deeper than tracked eyebrow chips - aphoristic-cadence: 3+ manufactured-contrast ("Not a X. A Y.") or short-rebuttal ("Sentence. No clause." / "Sentence. Just clause.") constructions in body text Engine wiring: - broken-image runs as a static-html element rule (selector: img) and a fallback regex matcher (for non-HTML files) - em-dash / buzzword / numbered / aphoristic run as regex page-analyzers, factored into a new runTextContentAnalyzers() helper that both detectText (non-HTML) and detectHtml (HTML) call, so .html files get the same coverage as .css/.tsx Tests: 166 detector + 12 browser + 24 fixture all pass. Browser detector rebuilt (162.7 KB). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: drop unvalidated anti-centering rule; add image-led hero carve-out The anti-centering rule ("Don't default to centering everything") was added without empirical support. We have a detector for it (everything-centered, threshold ≥70%) that fires on 0 / 998 samples in the corpus — never validated, never useful. Meanwhile the rule was almost certainly responsible for collapsing Gemini 3.5 flash's luxury-hotel skill-on output from the canonical "full-bleed photo + centered overlay headline" cinematic hero (the shape skill-off Gemini chooses 67% of the time) to a 50/50 magazine grid (full-bleed rate drops to 18% under skill-on, -49pp). Changes: - skill/SKILL.md #### Layout: drop "Don't default to centering..." - skill/reference/brand.md ## Layout: drop the same rule; replace with a positive carve-out — image-led briefs (hotels, restaurants, magazines, photography) often want full-bleed hero with overlaid menu and centered headline; let the photograph be the design - skill/reference/layout.md: drop the assessment question and the "asymmetric breaks centered-content pattern" framing Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply neo-kinpaku design system and improve live picker UX Restyle the live picker to match the site kinpaku kit, persist pick mode in localStorage, fix DESIGN.md color swatches in the parser, and land the neo-kinpaku site refresh with new tokens, assets, palette script, and detector rules. Co-authored-by: Cursor <cursoragent@cursor.com> * Add live Steer end-to-end: poll protocol, browser UI, and E2E harness. Wire page-level Steer through the live server and agent poll loop with steer_done unlock semantics, extend live.md for agents, and add smoke tests with LLM handleSteer plus recovery for hidden heroes, HMR lag, and dev-tool overlays. Co-authored-by: Cursor <cursoragent@cursor.com> * Add experimental live-poll --stream mode; keep one-shot default for Cursor. Stream keeps one process alive with ack-aware resume, but live.md documents that Cursor should stay on one-shot background notify after testing showed ~5s pickup vs sub-second on exit-based notify. Co-authored-by: Cursor <cursoragent@cursor.com> * Sync harness output and fix build validators for poll stream release. Regenerate provider skills after live-poll --stream work, update homepage detection counts to 41, and replace em dashes in site/skill copy so bun run build passes prose and count checks. Co-authored-by: Cursor <cursoragent@cursor.com> * homepage: add testimonials marquee section A two-row testimonial marquee on a tinted graphite plinth, sitting between the hero and the slop teaser. 29 testimonials sourced via api.fxtwitter.com (lightly cleaned: leading @-mention reply targets stripped, trailing self-links removed). Avatars downloaded into site/public/assets/testimonials/ so they're served locally. Quote order curated for impact — both rows lead with the punchiest quotes (Ben Davis spotlight, "Impeccable > Claude design", "THIS. This shit works.", "Uninstall whatever frontend skill you're using.") so the first viewport is loaded with the most memorable testimonials. Engineering notes: - Section uses width:100vw + margin-left:calc(50% - 50vw) to escape main.site-content's max-width + side padding (cards now clip cleanly at the actual viewport edges). - Marquee runs at 110s linear infinite. Both rows share the same duration so on-screen speeds match; track is doubled so the loop back to 0 reads as continuous. - Hero min-height reduced from 100svh to calc(100svh - 115px) so the dotted divider and top of row A peek above the fold on landing, signalling the section is there. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * homepage: keep the hero demo clear of the fixed header on short viewports The hero centers its content in the full viewport (the site header is a fixed overlay), so on shorter screens the tall Live Mode demo tucked under the nav. Raise the hero's top padding above the 97px header (113px wide, 108/92px when stacked) so content always pins below the header while still centering on tall viewports, and cap the demo frame to the viewport so the whole demo stays on screen. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Add steer voice input and refine processing animation. Wire Web Speech API on the Steer mic with auto-submit, block Cursor's preview browser with a clear message, and replace truncated "Working" text with a dots-only processing state. Co-authored-by: Cursor <cursoragent@cursor.com> * Add agent poll connectivity indicator and tighten global bar spacing. Surface poller state on the Impeccable mark via SSE and /status, with an instant disconnected tooltip, steer timeout failsafe, and matched brand/chat section gaps. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix steer focus to allow page text selection without losing type-to-steer. Blur the hidden steer input on page interaction, pause refocus during selection gestures, and reschedule focus recovery after clicks and cleared selections. Co-authored-by: Cursor <cursoragent@cursor.com> * site: rework "Design in production" section glyphs and audience band Put the three how-it-works steps back into thin-line cards and drop the overused browser-chrome bars from each glyph. Redraw the step 2 and 3 visuals to mirror the real Live Mode UI: step 2 shows the on-canvas pick outline with an attached comment bubble, step 3 shows the floating contextual accept bar plus the source-write confirmation. Re-treat the audience tiles as verdigris-lined text (no card box) under a "Who it's for" eyebrow, so each role reads as distinct from the gold step band. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Add live insert mode with HMR-safe placeholder recovery. Ships insert picking, scaffold helpers, variant cycling fixes for hidden variants, and placeholder snapshot/recreation so Astro HMR does not drop the wait-state box or re-anchor to the hero container. Co-authored-by: Cursor <cursoragent@cursor.com> * site: mobile pass — hamburger nav + designing hero overflow fix The header was rendering inline nav links + GitHub button that overflowed narrow viewports (~363px). Pre-existing display:none hacks hid Designing and Live to make the row fit, but those items still belonged in the menu. Header.astro: added a hamburger toggle button + inline script. The right cluster (nav + GitHub) becomes a collapsible drawer below the header on mobile, with data-nav-open driving the open/closed state and animating the two-line glyph into an X. kinpaku-kit.css: hamburger button (kinpaku-bordered glyph), mobile drawer panel (solid lacquer-deep bg, hairline separators between rows, full-width tappable rows), and overrides for the older sub-pages.css mobile rules (horizontal-scroll mask on the nav, hidden [data-nav="home"] item, hidden GitHub star label) — all redundant now that the drawer surfaces everything. home-kinpaku.css: dropped the @media (max-width: 560px) block that hid Designing / Live / GitHub. The drawer pattern shows them all. designing-kinpaku.css: hero h1 "Designing with Impeccable" was overflowing at narrow viewports. Three fixes: - grid-template-columns 1fr → minmax(0, 1fr) so the column shrinks to fit container instead of growing to "Impeccable"'s 472px intrinsic min-content width. - mobile h1 size override (clamp(2.2rem, 11vw, 3rem) at <=480px) since the display token's 3.4rem minimum is sized for desktop hero impact. - hide the decorative loop-wheel SVG below 600px (was overflowing 22px past the right edge). Verified clean at both 363px and 403px viewports across /, /docs, /docs/animate, /slop, /designing, /live-mode. scrollWidth matches viewport width on every page (no horizontal scroll). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * detector: refine new rules + run provider tells in browser env Follow-up to the detector port (rules landed in 7648af00): - oversized-h1: flag long headlines set at display size, not punchy one/two-word heroes (length, not size alone, is the tell) - provider tells (--gpt/--gemini) now always run in a real browser env (detector page, live overlay, extension); gating is a CLI-output concern only, applied in the Node engine return paths - move theater-slop-phrase into checkHtmlPatterns so it runs in the bundled browser path, not just CLI/static (browser bundle excludes detect-text.mjs) - hero-eyebrow-chip overlay highlights the eyebrow, not the heading - gemini-tells fixture: data-URI images so the hover-zoom renders - rebuild browser bundle Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: migrate /detector lab to neo-kinpaku design system Rebuild the detector lab tool shell on --ks-* tokens (lacquer ground, gold hairlines, champagne/mono type) instead of the legacy warm-paper palette. Swap the "/" placeholder for the real carved-tile brand lockup, restyle the toolbar actions as kinpaku primary/secondary buttons, and recolor the finding overlay from off-brand magenta to vermilion. Update the global theme-color from #fafafa to #010101 (the sRGB render of the lacquer ground) so the browser chrome matches the dark site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Homepage: hero finalist, compact live demo, real picker bar. Switch the hero to m-01-v2-01, tighten the in-hero demo layout, and replace the marketing gbar with a shared LiveDemoGbar that mirrors live-browser.js. Size the bar with max-content so controls are not clipped inside the capsule. Co-authored-by: Cursor <cursoragent@cursor.com> * site: migrate /cases/neo-mirai to neo-kinpaku design system Rebuild the Neo Mirai case-study page on --ks-* tokens: lacquer ground (drops the off-brand magenta radial spotlight), Alumni Sans Pinstripe display headings instead of the banned italic serif, gold eyebrow/labels, gold hairline image frames, kinpaku primary/secondary buttons, and a lacquer-deep command panel with a gold-bordered code block. Opt .neon-case-page into the shared kinpaku site-header/footer chrome in kinpaku-kit.css (per the "add new kinpaku pages to the selector list" note) so the global header and footer go dark to match the page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: consolidate kinpaku header+footer into one reusable .kinpaku-chrome class The dark header/footer were not a reusable unit: the header was scoped to a per-page selector list, the github star pill was home-only, and the default footer was copy-pasted into four page stylesheets. Pages not on the lists (like /cases/neo-mirai) fell back to the legacy light chrome. Collapse all of it into one `.kinpaku-chrome` block in kinpaku-kit.css — header, github pill, and default footer — and opt every kinpaku page in via a single body class. Delete the four duplicated per-page footer blocks and the home-only github pill. The home page keeps its textured verdigris footer as a deliberate override, raised to body.home-kinpaku specificity so it wins regardless of import order. Genuinely light pages (privacy, tutorials) just omit the class. Fixes on /cases/neo-mirai: footer and github star now render dark/kinpaku (were legacy-light), and the content sections are wrapped in the .neon-case container so they sit in header-aligned gutters instead of bleeding to the viewport edge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: migrate privacy + tutorials to kinpaku via a reusable surface class These were the last two light pages. Rather than rewrite their per-rule styling, add a reusable .kinpaku-surface class that remaps the legacy --color-* / --font-* tokens to kinpaku values at the body scope, so the existing legacy-token CSS (sub-pages.css prose, the pages' inline styles) renders dark for free. Same trick docs-kinpaku/slop-kinpaku use per page, lifted into one shared class. Pair it with .kinpaku-chrome for header + footer. privacy + both tutorials pages now carry both classes. Also force the sub-1.2rem headings (tutorial card titles, prose h1/h2) back to the upright body face: the legacy display face was italic serif, and the kinpaku Pinstripe face reads wrong synthesized-italic at small sizes. No light pages remain. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: re-add Tutorials to the /docs sidebar Tutorials lost its docs placement across two refactors: the Astro docs rebuild never carried over the sidebar tutorials list the old generated pages had, and the kinpaku homepage redesign dropped the "Full walkthrough" link. It survived only via /designing and /live-mode. Add a "Tutorials" group at the top of the docs sidebar (matching the command-category styling) linking the index plus all four tutorials, restoring the old information architecture. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: make kinpaku the default — flip legacy :root tokens to dark (phase 1) Repoint the legacy design tokens in tokens.css from light-mode to kinpaku: --font-* now reference the --ks-* brand faces (retiring Cormorant/Instrument/ Space Grotesk), surfaces carry dark-lacquer oklch, and --color-accent is gold instead of magenta. Values mirror the per-page kinpaku remaps. Every live page already overrides these at its body-class scope, so this changes the fallback (any classless/new page now renders kinpaku) without altering existing pages — verified home, designing, slop, live-mode, docs unchanged, and the deliberate-light demos (slop specimens, home's Aurelia mock) still render light via their own colors. First step toward removing the per-page remaps; those become redundant next. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * detector + slop: cream-palette rule, drop everything-centered, polish catalog - new deterministic cream-palette rule ("claude beige"): flags warm lightly-tinted off-white page backgrounds; wired into static + browser engines, with fixture + test - remove everything-centered rule entirely (no longer in the skill) from registry, regex analyzer (+ index-offset fix), checkPageLayout, and tests - catch Instrument Serif in overused-font (regex + OVERUSED_FONTS) - /slop: reconcile catalog (cream card in, everything-centered out; counts), and fix demo visuals — visible hairline border, gigantic clipped hero, more extreme crushed tracking, padded gray-on-color card, uniform-rhythm monotonous-spacing, long line-length line, elastic-overshoot dialog for bounce easing, real zooming image for image-hover; flip the demo surface off warm beige to a cool neutral Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * detector page: add cream-palette fixture to the catalog Surfaces the new cream/beige palette rule on /detector alongside the other Color specimens. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: shared docs sidebar + tutorial pages join the layout Extract the /docs section sidebar into a reusable DocsSidebar component and wire it into all three entry points so the navigation is consistent across docs index, command pages, and tutorial pages. site/components/DocsSidebar.astro (new): one source of truth. Loads the tutorials + skills collections, renders Tutorials → Commands grouped by category, and highlights the active entry via activeCommand / activeTutorial props. site/pages/docs/index.astro: swap the inline sidebar markup for the component. Drop the "All tutorials" link — the dedicated tutorials listing page wasn't earning its slot in the rail. site/layouts/Doc.astro: same swap. Command pages now also see the Tutorials section above Commands, matching /docs. site/pages/tutorials/[...slug].astro: rewrite from a standalone page (custom .tutorial-page wrapper, ad-hoc breadcrumb) to the full skills-layout shell with DocsSidebar in the left rail. Tutorial content now reads in the same layout as command reference pages. site/content/tutorials/brand-vs-product.md (deleted): the skill picks the register automatically from PRODUCT.md, so a tutorial telling users to pick it themselves was misleading. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * detector: catch Tailwind warm-light bg utilities in cream-palette The static engine can't resolve Tailwind classes to computed CSS, so a `bg-amber-50` on <body> slipped past the cream-palette rule. Add a class-list fallback that scans body/html for arbitrary `bg-[...]` values and named warm-light utilities (amber/orange/yellow/stone), each run through the same isCreamColor test so neutrals and over-saturated shades drop out. Fixture + test for the class-only case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: drop redundant per-page token remaps (phase 2) With kinpaku now the :root default, the --color-* / --font-* remap blocks in docs/slop/designing/live-mode-kinpaku.css re-declared values identical to :root. Removed them, keeping only the --ks-muted alias (still read by name in those files) and each page's shell (gradient bg, color, min-height). home-kinpaku.css keeps its remap: it uses home-specific values (e.g. --color-charcoal: var(--ks-text), --color-cream: var(--ks-lacquer-raised)) plus the --cat-* gradient overrides, so it is not redundant. Verified designing (PRODUCT.md viz), slop (specimens stay light), docs, live-mode unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: drop italic from 15 dead editorial-serif heading rules Audited every font-style: italic in sub-pages.css and main.css against the live markup. Removed italic from the 15 rules whose selectors don't appear in any page/component/content/script: sub-pages.css: docs-home-card-title, docs-category-title, tutorial-embed-caption, skill-demo-caption, skill-source-card-subtitle, skill-references-heading, skill-reference-title main.css: hero-title-combined, hero-tagline-combined, impeccable-title, loading-state, install-primary-howto .install-path-desc em, install-howto-steps > li::before, install-step-status, consulting-title These were dormant remnants of the retired Cormorant italic-serif look — the kinpaku Pinstripe face renders them as bad synthesized-italic, but no markup matches the selectors so nothing rendered. Removed only the font-style declaration; the rest of each rule stays (whole-rule cleanup is out of scope). Kept the 5 live selectors (slop-section-heading, tutorial-card-title, visual-mode-demo-caption, visual-mode-method-name, gallery-card-title) per the "if they're not used anywhere" condition, plus .prose em (real emphasis) and .prose blockquote (conventional blockquote italic). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: brand-seed palette.mjs + Setup step to run it New-brand color now starts from a curated seed color (129 OKLCH seeds) instead of the model guessing or defaulting to warm-cream. The script returns one seed + composition guidance (pure-bg architecture, perceptual text-on-fill, anti-cliché moods, jewel-tone range), with inverse-frequency hue weighting for fair rainbow exposure and deterministic --from picking. SKILL.md Setup step 5 makes it run for greenfield projects. Curation tooling lives in the impeccable-evals repo (tools/palette/). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Remove accidental live mode inject from Base.astro. The localhost live.js tag was left in the site layout after a dev session and should never ship in the Astro template. Co-authored-by: Cursor <cursoragent@cursor.com> * site: dedicated /changelog + /faq, epic v3.5.0 notes, Live Mode → Beta Split changelog and FAQ out of the homepage into two standalone kinpaku pages, linked from the footer (and a quiet hint under the Get-started CTA). /changelog: every release inline (no collapsible), newest first. The v3.5.0 entry leads with a one-line summary, a real before/after pair from the GPT-5.5 eval corpus (luxury-hotel brief, skill off vs on), and a stat row (74% cream-bg, 76% extreme tracking, 90%+ low-contrast — measured across ~190 samples). Then five scannable bold-led bullets, biggest takeaway first: per-provider skill compilation, the bias-fix, Live Mode, the 7 new detector rules, the tighter skill. Before/after JPGs optimized to ~470KB total (down from ~2.5MB PNGs). /faq: the six support questions, each deep-linkable. Live Mode is now Beta everywhere it surfaces: the /live-mode eyebrow badge and note, the homepage bento tile badge, and the changelog entry. The historical v3.0 changelog entry stays "Alpha" — accurate to what shipped then. Footer trimmed to the four links not already in the top nav (Changelog, FAQ, Privacy, GitHub). Version bumped 3.2.0 → 3.5.0 across the three plugin manifests; the 3.2 bias-fix work folds into this release rather than shipping separately. astro.config.mjs: disable the dev toolbar. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: point /design-system hero at the m-01-v2-01 finalist design-system.css referenced kintsugi-hero-v2.png, an untracked orphan that was never committed. Repoint it at the committed m-01-v2-01 finalist so /design-system and the homepage hero share one image, and the page no longer depends on a file outside the repo. The v2 orphan moved to tmp/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * build: sync harness mirrors + green the prose gate Rebuild propagates the committed skill source (palette.mjs Setup step, detector rule updates, brand.md) into the 13 harness output dirs and the plugin subtree, which had drifted from source. Also fixes the prose validator, which had been red on six pre-existing hits across committed files: - Four em dashes in code comments (Testimonials.astro, LiveDemoGbar.astro, index.astro) and one in skill/reference/live.md — reworded to colons/commas. - Two in the slop catalog (an em-dash-overuse specimen and the marketing-buzzword rule naming "empower"). Those are intentional: the slop page documents every antipattern by example, so it must contain them. Exempted site/pages/slop from validateProse rather than neutering the specimens. `bun run build` is now green end to end: counts validate, prose passes, site builds. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: rewrite no-section-fade rule to fix Gemini zero-motion overcorrection The old rule ("whole-section fade-on-scroll is the saturated AI motion reflex") drove Gemini to overcorrect into shipping pages with no motion at all: motion-variety 39% / zero-motion 12% with the skill on, vs ~74-78% variety and ~3% zero-motion without it. Rewrite keeps the legitimate-stagger carve-out, names the defect at shape level (one identical entrance on every section) without enumerating motion primitives, and adds an explicit clause that suppressing the reflex is never grounds for a static page. Validated on Gemini 3.5-flash (n=10, luxury-hotel + infra-platform): motion-variety 39% -> 70%, zero-motion 12% -> 0%, staggered-reveal stays 0% (reflex not re-inflated). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: bump CLI to 2.2.0 and extension to 1.1.0 Both ship the expanded detector: the 7 new rules (cream-palette, em-dash-overuse, marketing-buzzword, numbered-section-markers, aphoristic-cadence, broken-image, italic-serif-display) plus hero-eyebrow-chip, with everything-centered removed. 41 rules total. The extension settings page already supports toggling them: the rule list renders from detector/antipatterns.json, grouped by category, and disabledRules flows through chrome.storage.sync into the scan config, which detect.js honors by rule id. New rules are toggleable with no UI change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * release: fix release.mjs for the moved changelog + add CLI/ext entries The changelog moved from site/pages/index.astro to its own site/pages/changelog.astro with new markup (cf-version / cf-entry / cf-items), which left release.mjs reading the wrong file with the old selectors. All three release commands would have failed at note extraction. Point it at changelog.astro, match cf-version, and scope notes to the <ul class="cf-items"> bullet list — that also skips the lead paragraph, before/after figure, and stat row on the v3.5.0 entry, keeping release notes to clean bullets. Add CLI v2.2.0 and Extension v1.1.0 changelog entries (the shared detector update: 7 new rules, everything-centered removed, 41 total; plus the extension's per-rule toggles) so release:cli and release:ext have notes to extract. Verified extraction for all three labels: v3.5.0 (5 bullets), CLI v2.2.0 (3), Extension v1.1.0 (2). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: correct dev server port to 4321 and drop stale pnpm-lock Astro serves on 4321, not 3000 as the docs claimed; update CLAUDE.md, AGENTS.md, and screenshot-antipatterns.js. Remove the leftover pnpm-lock.yaml from the Astro migration so Cloudflare's frozen install uses the maintained, in-sync bun.lock instead of a drifted pnpm lockfile. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: rework /designing flow, rhythm, Live Mode mock, and CTA Restructure the page so iteration reads as the core value, not net-new. The four loop phases are wrapped in a track with a sticky scroll-spy nav (Start/Iterate/Polish/Maintain) that pins under the header and highlights the active phase; the surfaces section (skill/CLI/extension) moves out of the loop into the post-loop context group so the loop runs uninterrupted. Fix the iterate split: shared subgrid row tracks so the terminal and the Live Mode mock align on the same baseline regardless of paragraph length, wider intro measure (52ch, was a crammed 36ch), and a deeper picker stage so the context and global bars breathe instead of stacking on the card. Rebuild the Live Mode mock to mirror the real picker: carved-tile mark plus Pick / Insert / Detect / DESIGN.md controls on lacquer-deep with the gold border, and a /impeccable live entry line so the reader knows how to start. Reframe Start as the hard mode, move h3 subheads off the thin display face onto Albert Sans, and trim Start so it no longer dominates the loop. Rework the closing CTA into two standalone raised cards (the bento plinth made them read as boxes nested in a box), and fix the tutorials copy: there are three walkthroughs now, and the brand-vs-product tutorial is gone, so drop it from the CTA and remove the dead lane link to it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: reorder Get Started so usage follows setup, link out to more Move the /impeccable usage examples below the Chrome extension, CLI, and Stay-updated block. Running a command is the logical next step once the skill, extension, CLI, and subscriptions are all in place, so the section now reads install -> set up the extras -> use it. Add a closing "Go deeper" line linking to the Designing with Impeccable workflow page and the docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: install compiled per-provider skill variants, not uncompiled source `npx skills add` (and `impeccable skills install`, which wrapped it) installed the uncompiled skill/ source verbatim: the skills CLI dedupes discovery by name and picks skill/SKILL.md first, so installs shipped unresolved {{placeholders}} and no vendored detector (#168). - Rename skill/SKILL.md -> skill/SKILL.src.md so the skills CLI's discovery skips the source and falls through to a compiled .agents variant; update the build reader, skill-behavior harness, and docs to match. - Refactor `impeccable skills install` to copy each harness's compiled variant from the universal bundle (real dirs, no npx skills, no symlink), with project/global harness detection and a --providers override. - Fix stale unit tests (replacePlaceholders, readPatterns, transformer prefix/summary) that asserted removed pre-v3.0 behavior, and wire the three orphaned test files into `bun run test` so the drift can't recur. - Split skills-cli.test.js: pure blocks run by default, network blocks move behind a new `bun run test:cli-e2e`; fix its stale update assertions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: default to `npx impeccable skills install`, restore install-method panel Get Started recommended `npx skills add`, which installs a single shared build across harnesses. Make our CLI the default (it installs the build compiled for each harness) and bring back the "Other install methods" disclosure the neo-kinpaku redesign dropped. - Homepage: primary command is now `npx impeccable skills install`; a native <details> panel offers the Claude Code plugin and `npx skills` (caveated as installing one shared build rather than the per-harness one). - FAQ: recommend `npx impeccable skills install` to install, `--force` to reinstall, and note the npx skills shared-build caveat. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * site: reword craft tagline so it doesn't lead with "Shape" The craft card's tagline began with the word "Shape", which reads like the name of the sibling /shape command and made the two cards look swapped (#166). Reword to "Design it, then build it, all in one flow." No data was actually swapped; this is a copy collision fix. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * skill: rename teach -> init and expand its setup flow Rename the `/impeccable teach` command to `/impeccable init` across the skill, site, CLI, and tests. `teach` stays as a deprecated router alias and /docs/teach + /skills/teach redirect to /docs/init. Expand the command beyond writing PRODUCT.md/DESIGN.md: the same codebase crawl now also pre-configures `.impeccable/live/config.json` (Step 6, with CSP consent) so live mode boots with no first-time detour, and the flow ends by recommending the best commands to run next from what the scan surfaced (Step 7). Fold two items into the unreleased v3.5.0 changelog entry: the init rename and the brand-seed palette picker. No version bump. Regenerates all harness skill output dirs and the _redirects file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: lead README install + usage with the CLI installer Add `npx impeccable skills install` as the recommended install option and update the Usage section to the `/impeccable <command>` form, dropping the nonexistent `/normalize` example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(skill-behavior): swap to production-tier models (sonnet + gpt-5.5) Replace the cheap-tier default lineup (claude-haiku-4-5, gpt-5.4-mini) with production-tier models (claude-sonnet-4-6, gpt-5.5) so the skill-behavior suite reflects what users actually run. gemini stays on flash-lite. Sync the docs (CLAUDE.md, AGENTS.md, tests/skill-behavior/README.md): new model names, cost estimate raised to ~$0.50-1.50/sweep, and the old 21-22/24 baseline reframed as previous-cheap-tier history pending re-measurement on the new lineup. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: self-updating skill via boot-time version check context.mjs now polls a new lightweight /api/version endpoint at most once per day (cached globally in ~/.impeccable) and appends an UPDATE_AVAILABLE directive when a newer skill version has shipped, prompting the agent to offer `npx impeccable skills update`. Best-effort and silent on any failure; asks before updating; suppresses re-prompts for a declined version for a week. Opt out with IMPECCABLE_NO_UPDATE_CHECK=1. - skill/scripts/context.mjs: version read, throttle + anti-nag cache, directive - scripts/build.js + _redirects: /api/version endpoint (from plugin.json version) - skill/SKILL.src.md: document the UPDATE_AVAILABLE boot branch - tests/context.test.mjs: coverage for cached/newer/suppressed/opt-out paths - changelog: v3.5.0 entry - synced harness skill dirs via bun run build Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: cover the self-update path (network + LLM behavior) context.test.mjs: add a localhost stub-server integration test for the live fetch path (poll /api/version, cache a newer version, stay silent on same-or-older, fail silent + stamp lastCheck when unreachable). Runs against 127.0.0.1 only, never the real site; uses async spawn so the in-process stub isn't deadlocked by spawnSync blocking the event loop. skill-behavior: add scenario 9 asserting the agent surfaces UPDATE_AVAILABLE but never auto-runs `npx impeccable skills update` without asking. New prepareWorkspace `skillVersion` copy-mode (so context.mjs has a SKILL.md to version-check), env threading through runTurn -> execBash, and bash-output capture to prove the agent actually received the directive. Passed on claude-sonnet-4-6, gpt-5.5, and gemini-3.1-flash-lite. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 23:26:39 +03:00 · 2026-05-28 14:22:22 -07:00
parent 84135db0e6
commit 9ffd3211d5
955 changed files with 121730 additions and 38852 deletions
@@ -25,7 +25,7 @@ import { join, resolve } from 'node:path';
 const DEPRECATED_NAMES = [
  // v2.0 renames
  'frontend-design',    // renamed to impeccable
-  'teach-impeccable',   // folded into /impeccable teach
+  'teach-impeccable',   // folded into /impeccable init
  // v2.1 merges
  'arrange',            // renamed to layout
  'normalize',          // merged into polish
@@ -3,8 +3,8 @@
    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
    "argumentHint": "[feature description]"
  },
-  "teach": {
-    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+  "init": {
+    "description": "Sets up a project for impeccable. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles); offers DESIGN.md (visual: colors, typography, components) when code exists; pre-configures live mode; then recommends the best commands to run next. Every other command reads these files before doing work. Use once per project.",
    "argumentHint": ""
  },
  "document": {
@@ -0,0 +1,266 @@
+/**
+ * Context loader: prints PRODUCT.md (and DESIGN.md if present) as one
+ * markdown block on stdout, or exits with empty stdout when no PRODUCT.md
+ * is found anywhere. The skill keys off "empty stdout" to branch into the
+ * init flow.
+ *
+ * Path resolution (first match wins):
+ *   1. cwd, if PRODUCT.md or DESIGN.md is there
+ *   2. .agents/context/ then docs/
+ *   3. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
+ *      escape hatch, only consulted when defaults are empty
+ *   4. cwd as a "nothing found" default
+ *
+ * `resolveContextDir()` and `loadContext()` are also exported for the
+ * server-side scripts (live.mjs, live-server.mjs) that need the structured
+ * shape rather than the markdown block.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const FALLBACK_DIRS = ['.agents/context', 'docs'];
+
+// ─── Update check ──────────────────────────────────────────────────────────
+// Piggyback a lightweight skill-version check on the once-per-session boot.
+// When a newer skill ships, append an UPDATE_AVAILABLE directive so the agent
+// can offer `npx impeccable skills update`. Everything here is best-effort and
+// silent on failure: a network problem, sandbox, or missing cache must never
+// block context output or print an error.
+
+const UPDATE_HOST = (process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style').replace(/\/$/, '');
+const UPDATE_CACHE_PATH =
+  process.env.IMPECCABLE_UPDATE_CACHE || path.join(os.homedir(), '.impeccable', 'update-check.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // throttle the network poll to once a day
+const RENOTIFY_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // don't re-surface the same version for a week
+const FETCH_TIMEOUT_MS = 1200;
+
+export function resolveContextDir(cwd = process.cwd()) {
+  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+    return cwd;
+  }
+  for (const rel of FALLBACK_DIRS) {
+    const candidate = path.resolve(cwd, rel);
+    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+      return candidate;
+    }
+  }
+  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
+  if (envDir && envDir.trim()) {
+    const trimmed = envDir.trim();
+    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+  }
+  return cwd;
+}
+
+export function loadContext(cwd = process.cwd()) {
+  const contextDir = resolveContextDir(cwd);
+  const productPath = firstExisting(contextDir, PRODUCT_NAMES);
+  const designPath = firstExisting(contextDir, DESIGN_NAMES);
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    contextDir,
+  };
+}
+
+function firstExisting(dir, names) {
+  for (const name of names) {
+    const abs = path.join(dir, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try {
+    return fs.readFileSync(p, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
+ * for a `## Register` section and reading the first non-empty line that
+ * follows it. Returns null when the file is legacy / register-less.
+ */
+function extractRegister(product) {
+  if (!product) return null;
+  const lines = product.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Register\b/i.test(lines[i].trim())) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const next = lines[j].trim();
+        if (!next) continue;
+        const word = next.toLowerCase();
+        if (word === 'brand' || word === 'product') return word;
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the installed skill's own version from the sibling SKILL.md frontmatter
+ * (this file lives at `<skill>/scripts/context.mjs`). Returns null when the
+ * frontmatter is missing or unreadable.
+ */
+function readLocalSkillVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const skillMd = path.join(here, '..', 'SKILL.md');
+    const content = fs.readFileSync(skillMd, 'utf-8');
+    const match = content.match(/^version:\s*(.+)$/m);
+    return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
+  } catch {
+    return null;
+  }
+}
+
+function readUpdateCache() {
+  try {
+    return JSON.parse(fs.readFileSync(UPDATE_CACHE_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdateCache(cache) {
+  try {
+    fs.mkdirSync(path.dirname(UPDATE_CACHE_PATH), { recursive: true });
+    fs.writeFileSync(UPDATE_CACHE_PATH, JSON.stringify(cache));
+  } catch {
+    // Best-effort: a read-only home dir just means we re-poll next session.
+  }
+}
+
+/** Compare dotted numeric versions. Returns >0 when a is newer than b. */
+function compareSemver(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+async function fetchLatestSkillVersion() {
+  try {
+    const res = await fetch(`${UPDATE_HOST}/api/version`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data?.skills === 'string' ? data.skills : null;
+  } catch {
+    return null; // offline, sandboxed, timed out, or bad JSON: all non-fatal
+  }
+}
+
+function buildUpdateDirective(localVersion, latestVersion) {
+  return (
+    `UPDATE_AVAILABLE: A newer Impeccable skill is available ` +
+    `(installed v${localVersion}, latest v${latestVersion}). ` +
+    `Before continuing, ask the user once: "A newer Impeccable (v${latestVersion}) is available. ` +
+    `Update now? It runs \`npx impeccable skills update\`." ` +
+    `If they agree, run \`npx impeccable skills update\` (the update applies to the next session, not this one). ` +
+    `Either way, continue the current task without waiting, and do not raise this again.`
+  );
+}
+
+/**
+ * Best-effort update directive for the boot output. Returns a string to append
+ * or null. Polls the version endpoint at most once per day (cached globally in
+ * the user's home dir) and re-surfaces a given version at most once per week so
+ * the agent never nags. Opt out entirely with IMPECCABLE_NO_UPDATE_CHECK=1.
+ */
+async function computeUpdateDirective(now = Date.now()) {
+  try {
+    if (process.env.IMPECCABLE_NO_UPDATE_CHECK) return null;
+    const localVersion = readLocalSkillVersion();
+    if (!localVersion) return null;
+
+    const cache = readUpdateCache();
+
+    // Poll the network only when the throttle window has elapsed. Stamp
+    // lastCheck even on failure so an offline machine doesn't poll every boot.
+    if (!cache.lastCheck || now - cache.lastCheck > CHECK_INTERVAL_MS) {
+      const latest = await fetchLatestSkillVersion();
+      cache.lastCheck = now;
+      if (latest) cache.latestVersion = latest;
+      writeUpdateCache(cache);
+    }
+
+    const latest = cache.latestVersion;
+    if (!latest || compareSemver(latest, localVersion) <= 0) return null;
+
+    // Anti-nag: surface a given version at most once per RENOTIFY window.
+    if (cache.notifiedVersion === latest && cache.notifiedAt && now - cache.notifiedAt < RENOTIFY_INTERVAL_MS) {
+      return null;
+    }
+    cache.notifiedVersion = latest;
+    cache.notifiedAt = now;
+    writeUpdateCache(cache);
+
+    return buildUpdateDirective(localVersion, latest);
+  } catch {
+    return null;
+  }
+}
+
+async function cli() {
+  const ctx = loadContext(process.cwd());
+  const updateDirective = await computeUpdateDirective();
+
+  if (!ctx.hasProduct) {
+    // Direct stdout message instead of relying on empty output as a signal
+    // — cheap models miss the empty case more often than the explicit one.
+    const parts = [
+      'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
+      'Stop the current task, load reference/init.md, and follow its ' +
+      'instructions to write PRODUCT.md before resuming.',
+    ];
+    if (updateDirective) parts.push(updateDirective);
+    process.stdout.write(parts.join('\n\n---\n\n') + '\n');
+    process.exit(0);
+  }
+  const parts = [`# PRODUCT.md\n\n${ctx.product.trim()}`];
+  if (ctx.hasDesign) {
+    parts.push(`# DESIGN.md\n\n${ctx.design.trim()}`);
+  }
+  const register = extractRegister(ctx.product);
+  const next = register
+    ? `NEXT STEP: This project's register is \`${register}\`. You MUST now read \`reference/${register}.md\` before producing any design output.`
+    : `NEXT STEP: You MUST now read the matching register reference (\`reference/brand.md\` or \`reference/product.md\`) before producing any design output. Pick based on PRODUCT.md above.`;
+  parts.push(next);
+  if (updateDirective) parts.push(updateDirective);
+  process.stdout.write(parts.join('\n\n---\n\n') + '\n');
+}
+
+// Run cli() only when this module is the entry point. Compare realpaths
+// rather than endsWith(): a loose suffix match also fires for unrelated
+// scripts like `load-context.mjs`, and realpath tolerates symlinked
+// invocation (the test harness symlinks the skill dir).
+function invokedAsScript() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return fs.realpathSync(arg) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript()) {
+  cli();
+}
@@ -63,7 +63,7 @@ function parseYamlSubset(yaml) {
    }

    const key = content.slice(0, colonIdx).trim();
-    const rest = content.slice(colonIdx + 1).trim();
+    const rest = stripInlineYamlComment(content.slice(colonIdx + 1).trim());
    const parent = stack[stack.length - 1].obj;

    if (rest === '') {
@@ -93,6 +93,21 @@ function findTopLevelColon(s) {
  return -1;
 }

+function stripInlineYamlComment(s) {
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inQuote) {
+      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === '#' && i > 0 && /\s/.test(s[i - 1])) {
+      return s.slice(0, i).trimEnd();
+    }
+  }
+  return s;
+}
+
 function parseScalar(raw) {
  const s = raw.trim();
  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
@@ -0,0 +1,101 @@
+/**
+ * Shared event validation for the live helper server.
+ * Extracted for unit testing (insert mode rules).
+ */
+
+import { canCreateInsert } from './live-insert-ui.mjs';
+
+export const VISUAL_ACTIONS = [
+  'impeccable', 'bolder', 'quieter', 'distill', 'polish', 'typeset',
+  'colorize', 'layout', 'adapt', 'animate', 'delight', 'overdrive',
+];
+
+const ID_PATTERN = /^[0-9a-f]{8}$/;
+const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
+const INSERT_POSITIONS = new Set(['before', 'after']);
+
+function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
+function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
+
+function validateAnnotationFields(msg) {
+  if (msg.screenshotPath !== undefined && typeof msg.screenshotPath !== 'string') {
+    return 'generate: screenshotPath must be string';
+  }
+  if (msg.comments !== undefined && !Array.isArray(msg.comments)) {
+    return 'generate: comments must be array';
+  }
+  if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) {
+    return 'generate: strokes must be array';
+  }
+  return null;
+}
+
+function validateInsertGenerate(msg) {
+  if (!msg.insert || typeof msg.insert !== 'object') return 'generate: insert mode requires insert object';
+  if (!INSERT_POSITIONS.has(msg.insert.position)) return 'generate: insert.position must be before or after';
+  const anchor = msg.insert.anchor;
+  if (!anchor || typeof anchor !== 'object') return 'generate: insert.anchor required';
+  if (!anchor.tagName && !anchor.outerHTML && !(Array.isArray(anchor.classes) && anchor.classes.length)) {
+    return 'generate: insert.anchor needs tagName, classes, or outerHTML';
+  }
+  if (!msg.placeholder || typeof msg.placeholder !== 'object') return 'generate: insert mode requires placeholder dimensions';
+  if (!Number.isFinite(msg.placeholder.width) || !Number.isFinite(msg.placeholder.height)) {
+    return 'generate: placeholder width and height must be numbers';
+  }
+  if (!canCreateInsert({
+    prompt: msg.freeformPrompt,
+    comments: msg.comments,
+    strokes: msg.strokes,
+  })) {
+    return 'generate: insert requires freeformPrompt or annotations';
+  }
+  return validateAnnotationFields(msg);
+}
+
+function validateReplaceGenerate(msg) {
+  if (!msg.action || !VISUAL_ACTIONS.includes(msg.action)) return 'generate: invalid action';
+  if (!msg.element || !msg.element.outerHTML) return 'generate: missing element context';
+  return validateAnnotationFields(msg);
+}
+
+export function validateEvent(msg) {
+  if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
+  switch (msg.type) {
+    case 'generate':
+      if (!isValidId(msg.id)) return 'generate: missing or malformed id';
+      if (!Number.isInteger(msg.count) || msg.count < 1 || msg.count > 8) return 'generate: count must be 1-8';
+      if (msg.mode === 'insert') return validateInsertGenerate(msg);
+      return validateReplaceGenerate(msg);
+    case 'accept':
+      if (!isValidId(msg.id)) return 'accept: missing or malformed id';
+      if (!isValidVariantId(msg.variantId)) return 'accept: missing or malformed variantId';
+      if (msg.paramValues !== undefined) {
+        if (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues)) {
+          return 'accept: paramValues must be an object';
+        }
+      }
+      return null;
+    case 'discard':
+      return isValidId(msg.id) ? null : 'discard: missing or malformed id';
+    case 'checkpoint':
+      if (!isValidId(msg.id)) return 'checkpoint: missing or malformed id';
+      if (!Number.isInteger(msg.revision) || msg.revision < 0) return 'checkpoint: revision must be a non-negative integer';
+      if (msg.paramValues !== undefined && (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues))) {
+        return 'checkpoint: paramValues must be an object';
+      }
+      return null;
+    case 'exit':
+      return null;
+    case 'prefetch':
+      if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return 'prefetch: missing pageUrl';
+      return null;
+    case 'steer':
+      if (!isValidId(msg.id)) return 'steer: missing or malformed id';
+      if (typeof msg.message !== 'string' || !msg.message.trim()) return 'steer: message required';
+      if (msg.message.length > 4000) return 'steer: message too long';
+      if (msg.pageUrl !== undefined && typeof msg.pageUrl !== 'string') return 'steer: pageUrl must be string';
+      return null;
+    default:
+      return 'Unknown event type: ' + msg.type;
+  }
+}
@@ -0,0 +1,458 @@
+/**
+ * Pure helpers for live-mode insert UI (browser + tests).
+ * Kept separate from live-browser.js so insert logic is unit-testable.
+ */
+
+export const PLACEHOLDER_DEFAULT_HEIGHT = 80;
+export const PLACEHOLDER_MIN_HEIGHT = 48;
+export const PLACEHOLDER_MIN_WIDTH = 120;
+
+/** @typedef {'before' | 'after'} InsertPosition */
+/** @typedef {'row' | 'column'} InsertAxis */
+
+/**
+ * Infer sibling flow axis from a container's computed layout styles.
+ * @param {{ display?: string, flexDirection?: string, gridTemplateColumns?: string, gridAutoFlow?: string }} style
+ * @returns {InsertAxis}
+ */
+export function detectInsertAxisFromStyle(style) {
+  const display = style?.display || 'block';
+  if (display.includes('flex')) {
+    const dir = style.flexDirection || 'row';
+    return dir.startsWith('row') ? 'row' : 'column';
+  }
+  if (display === 'grid' || display === 'inline-grid') {
+    const flow = style.gridAutoFlow || 'row';
+    if (flow.includes('column')) return 'column';
+    const cols = (style.gridTemplateColumns || '').trim();
+    if (cols && cols !== 'none') {
+      const colCount = cols.split(/\s+/).filter(Boolean).length;
+      if (colCount > 1) return 'row';
+    }
+    return 'row';
+  }
+  return 'column';
+}
+
+/**
+ * Pick insertion side from pointer position against an anchor element box.
+ * @param {number} clientX
+ * @param {number} clientY
+ * @param {{ top: number, left: number, width: number, height: number, bottom?: number, right?: number }} rect
+ * @param {InsertAxis} [axis]
+ * @returns {InsertPosition}
+ */
+export function computeInsertPosition(clientX, clientY, rect, axis = 'column') {
+  if (!rect) return 'after';
+  if (axis === 'row') {
+    if (!Number.isFinite(rect.left) || !Number.isFinite(rect.width) || rect.width <= 0) return 'after';
+    const mid = rect.left + rect.width / 2;
+    return clientX < mid ? 'before' : 'after';
+  }
+  if (!Number.isFinite(rect.top) || !Number.isFinite(rect.height) || rect.height <= 0) return 'after';
+  const mid = rect.top + rect.height / 2;
+  return clientY < mid ? 'before' : 'after';
+}
+
+/**
+ * Whether Create is allowed for an insert session.
+ * Requires a non-empty prompt OR at least one annotation.
+ */
+export function canCreateInsert({ prompt, comments, strokes }) {
+  const hasPrompt = typeof prompt === 'string' && prompt.trim().length > 0;
+  const hasComments = Array.isArray(comments) && comments.length > 0;
+  const hasStrokes = Array.isArray(strokes) && strokes.some(
+    (s) => Array.isArray(s?.points) && s.points.length >= 2,
+  );
+  return hasPrompt || hasComments || hasStrokes;
+}
+
+/** Tooltip/title when Create is disabled. */
+export function insertCreateDisabledReason({ prompt, comments, strokes }) {
+  if (canCreateInsert({ prompt, comments, strokes })) return null;
+  return 'Add a prompt or annotate the placeholder to create';
+}
+
+/**
+ * Fixed-position insert line coordinates (viewport px).
+ * @param {{ top: number, left: number, width: number, height: number, bottom?: number, right?: number }} rect
+ * @param {InsertPosition} position
+ * @param {InsertAxis} [axis]
+ */
+export function insertLineCoords(rect, position, axis = 'column') {
+  if (axis === 'row') {
+    const right = rect.right ?? rect.left + rect.width;
+    const x = position === 'before' ? rect.left - 2 : right + 2;
+    return { axis: 'row', top: rect.top, left: x, width: 0, height: rect.height };
+  }
+  const bottom = rect.bottom ?? rect.top + rect.height;
+  const y = position === 'before' ? rect.top - 2 : bottom + 2;
+  return { axis: 'column', top: y, left: rect.left, width: rect.width, height: 0 };
+}
+
+/** Cursor while hovering an insert boundary. */
+export function cursorForInsertAxis(axis) {
+  return axis === 'row' ? 'ew-resize' : 'ns-resize';
+}
+
+function groupSiblingRows(siblings, rowThreshold = 8) {
+  const sorted = [...siblings].sort((a, b) => a.rect.top - b.rect.top || a.rect.left - b.rect.left);
+  const rows = [];
+  for (const entry of sorted) {
+    let placed = false;
+    for (const row of rows) {
+      if (Math.abs(entry.rect.top - row[0].rect.top) <= rowThreshold) {
+        row.push(entry);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) rows.push([entry]);
+  }
+  return rows;
+}
+
+function horizontalOverlap(a, b) {
+  const left = Math.max(a.left, b.left);
+  const right = Math.min(a.right ?? a.left + a.width, b.right ?? b.left + b.width);
+  return Math.max(0, right - left);
+}
+
+/**
+ * Hit-test the gap between adjacent siblings (flex rows, grid columns, stacked blocks).
+ * @param {number} clientX
+ * @param {number} clientY
+ * @param {Array<{ el: unknown, rect: { top: number, left: number, width: number, height: number, bottom?: number, right?: number } }>} siblings
+ * @param {{ slop?: number, minOverlap?: number }} [opts]
+ */
+export function hitSiblingInsertGap(clientX, clientY, siblings, opts = {}) {
+  if (!Array.isArray(siblings) || siblings.length < 2) return null;
+  const slop = opts.slop ?? 12;
+  const minOverlap = opts.minOverlap ?? 0.25;
+
+  for (const row of groupSiblingRows(siblings)) {
+    if (row.length < 2) continue;
+    const sorted = [...row].sort((a, b) => a.rect.left - b.rect.left);
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const a = sorted[i];
+      const b = sorted[i + 1];
+      const aRight = a.rect.right ?? a.rect.left + a.rect.width;
+      const bLeft = b.rect.left;
+      if (bLeft <= aRight) continue;
+      const top = Math.max(a.rect.top, b.rect.top);
+      const aBottom = a.rect.bottom ?? a.rect.top + a.rect.height;
+      const bBottom = b.rect.bottom ?? b.rect.top + b.rect.height;
+      const bottom = Math.min(aBottom, bBottom);
+      const span = bottom - top;
+      const minH = Math.min(a.rect.height, b.rect.height);
+      if (span < minH * minOverlap) continue;
+
+      const inX = clientX >= aRight - slop && clientX <= bLeft + slop;
+      const inY = clientY >= top - slop && clientY <= bottom + slop;
+      if (!inX || !inY) continue;
+
+      const midX = (aRight + bLeft) / 2;
+      return {
+        anchor: b.el,
+        position: 'before',
+        axis: 'row',
+        line: { axis: 'row', left: midX, top, width: 0, height: span },
+      };
+    }
+  }
+
+  const sortedCol = [...siblings].sort((a, b) => a.rect.top - b.rect.top || a.rect.left - b.rect.left);
+  for (let i = 0; i < sortedCol.length - 1; i++) {
+    const a = sortedCol[i];
+    const b = sortedCol[i + 1];
+    const overlap = horizontalOverlap(a.rect, b.rect);
+    const minW = Math.min(a.rect.width, b.rect.width);
+    if (overlap < minW * minOverlap) continue;
+
+    const aBottom = a.rect.bottom ?? a.rect.top + a.rect.height;
+    const gapTop = aBottom;
+    const gapBottom = b.rect.top;
+    if (gapBottom <= gapTop) continue;
+
+    const overlapLeft = Math.max(a.rect.left, b.rect.left);
+    const overlapRight = Math.min(
+      a.rect.right ?? a.rect.left + a.rect.width,
+      b.rect.right ?? b.rect.left + b.rect.width,
+    );
+    const inY = clientY >= gapTop - slop && clientY <= gapBottom + slop;
+    const inX = clientX >= overlapLeft - slop && clientX <= overlapRight + slop;
+    if (!inY || !inX) continue;
+
+    const midY = (gapTop + gapBottom) / 2;
+    return {
+      anchor: b.el,
+      position: 'before',
+      axis: 'column',
+      line: { axis: 'column', top: midY, left: overlapLeft, width: overlap, height: 0 },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Resolve insert hover target, side, axis, and indicator line for the pointer.
+ */
+export function resolveInsertHover({ clientX, clientY, target, rect, axis, siblings }) {
+  const gap = hitSiblingInsertGap(clientX, clientY, siblings);
+  if (gap) return gap;
+
+  const position = computeInsertPosition(clientX, clientY, rect, axis);
+  const line = insertLineCoords(rect, position, axis);
+  return { anchor: target, position, axis, line };
+}
+
+/**
+ * How the in-flow placeholder should participate in layout.
+ * Prefer implicit sizing (flex / %) so row inserts don't inherit the full parent width in px.
+ * @returns {{ kind: 'flex', flex: string, minWidth: number } | { kind: 'percent' } | { kind: 'auto' } | { kind: 'explicit', width: number }}
+ */
+export function placeholderSizing({ axis, parentDisplay, parentWidth, anchorFlex }) {
+  const display = parentDisplay || 'block';
+  const w = Number.isFinite(parentWidth) ? parentWidth : 0;
+
+  if (axis === 'row') {
+    if (display.includes('flex')) {
+      const flex = anchorFlex && anchorFlex !== 'none' && anchorFlex !== '0 1 auto'
+        ? anchorFlex
+        : '1 1 0';
+      return { kind: 'flex', flex, minWidth: 0 };
+    }
+    if (display === 'grid' || display === 'inline-grid') {
+      return { kind: 'auto' };
+    }
+  }
+
+  if (w >= PLACEHOLDER_MIN_WIDTH) {
+    return { kind: 'percent' };
+  }
+
+  return {
+    kind: 'explicit',
+    width: Math.max(PLACEHOLDER_MIN_WIDTH, w || PLACEHOLDER_MIN_WIDTH),
+  };
+}
+
+/** Width kinds that need materializing to px before edge-resize. */
+export function placeholderWidthIsImplicit(kind) {
+  return kind === 'flex' || kind === 'percent' || kind === 'auto';
+}
+
+/**
+ * Clamp user-resized placeholder dimensions.
+ */
+export function clampPlaceholderSize(width, height, parentWidth, opts = {}) {
+  const minW = opts.minWidth ?? PLACEHOLDER_MIN_WIDTH;
+  const minH = opts.minHeight ?? PLACEHOLDER_MIN_HEIGHT;
+  const maxW = opts.maxWidth ?? Math.max(minW, parentWidth || minW);
+  return {
+    width: Math.min(maxW, Math.max(minW, Math.round(width))),
+    height: Math.max(minH, Math.round(height)),
+  };
+}
+
+/** CSS cursor for a placeholder edge resize handle. */
+export function cursorForPlaceholderEdge(edge) {
+  if (edge === 'n' || edge === 's') return 'ns-resize';
+  if (edge === 'e' || edge === 'w') return 'ew-resize';
+  return 'default';
+}
+
+/**
+ * Compute placeholder box after dragging one edge (in-flow margins shift for n/w).
+ * @param {{ width: number, height: number, marginLeft?: number, marginTop?: number }} start
+ * @param {'n'|'e'|'s'|'w'} edge
+ * @param {number} dx pointer delta X since drag start
+ * @param {number} dy pointer delta Y since drag start
+ * @param {number} parentWidth
+ */
+export function resizePlaceholderFromEdge(start, edge, dx, dy, parentWidth, opts = {}) {
+  const base = {
+    width: start.width,
+    height: start.height,
+    marginLeft: start.marginLeft ?? 0,
+    marginTop: start.marginTop ?? 0,
+  };
+  if (edge === 'e') base.width = start.width + dx;
+  else if (edge === 'w') {
+    base.width = start.width - dx;
+    base.marginLeft = start.marginLeft + dx;
+  } else if (edge === 's') base.height = start.height + dy;
+  else if (edge === 'n') {
+    base.height = start.height - dy;
+    base.marginTop = start.marginTop + dy;
+  }
+
+  const clamped = clampPlaceholderSize(base.width, base.height, parentWidth, opts);
+  if (edge === 'w') {
+    base.marginLeft = start.marginLeft + start.width - clamped.width;
+  } else if (edge === 'n') {
+    base.marginTop = start.marginTop + start.height - clamped.height;
+  }
+
+  return {
+    width: clamped.width,
+    height: clamped.height,
+    marginLeft: Math.round(base.marginLeft),
+    marginTop: Math.round(base.marginTop),
+  };
+}
+
+/** Pick and insert toggles are independent but turning one ON turns the other OFF. */
+export function applyPickToggle(pickActive, insertActive) {
+  const nextPick = !pickActive;
+  return {
+    pickActive: nextPick,
+    insertActive: nextPick ? false : insertActive,
+  };
+}
+
+export function applyInsertToggle(pickActive, insertActive) {
+  const nextInsert = !insertActive;
+  return {
+    pickActive: nextInsert ? false : pickActive,
+    insertActive: nextInsert,
+  };
+}
+
+/**
+ * Build the browser generate payload for insert mode.
+ */
+export function buildInsertGeneratePayload({
+  id,
+  count,
+  pageUrl,
+  anchorContext,
+  position,
+  placeholder,
+  freeformPrompt,
+  comments,
+  strokes,
+  screenshotPath,
+}) {
+  const payload = {
+    type: 'generate',
+    mode: 'insert',
+    id,
+    count,
+    pageUrl,
+    insert: {
+      position,
+      anchor: anchorContext,
+    },
+    placeholder,
+    freeformPrompt: freeformPrompt?.trim() || undefined,
+  };
+  if (comments?.length) payload.comments = comments;
+  if (strokes?.length) payload.strokes = strokes;
+  if (screenshotPath) payload.screenshotPath = screenshotPath;
+  return payload;
+}
+
+/**
+ * Whether a variant wrapper is currently shown (handles `hidden` and display:none).
+ * @param {{ hidden?: boolean, style?: { display?: string } } | null | undefined} el
+ */
+export function isVariantShown(el) {
+  if (!el) return false;
+  if (el.hidden) return false;
+  if (el.style?.display === 'none') return false;
+  return true;
+}
+
+/**
+ * Show or hide a variant wrapper for cycling.
+ * @param {{ hidden?: boolean, style?: { display?: string }, removeAttribute?: (name: string) => void, setAttribute?: (name: string, value?: string) => void } | null | undefined} el
+ * @param {boolean} shown
+ */
+export function setVariantShown(el, shown) {
+  if (!el) return;
+  if (shown) {
+    el.removeAttribute?.('hidden');
+    if (el.style) el.style.display = '';
+  } else {
+    el.setAttribute?.('hidden', '');
+    if (el.style) el.style.display = 'none';
+  }
+}
+
+/**
+ * Pick the best live anchor during an insert session (placeholder until variants land).
+ * @param {{
+ *   wrapper?: unknown,
+ *   variantCount?: number,
+ *   visibleVariant?: number,
+ *   placeholder?: unknown,
+ *   insertAnchor?: unknown,
+ *   pickVariantContent?: (wrapper: unknown, index: number) => unknown,
+ * }} opts
+ */
+export function resolveInsertSessionAnchor(opts) {
+  const {
+    wrapper,
+    variantCount = 0,
+    visibleVariant = 0,
+    placeholder,
+    insertAnchor,
+    pickVariantContent,
+  } = opts || {};
+  if (wrapper && variantCount > 0 && visibleVariant > 0 && pickVariantContent) {
+    const vis = pickVariantContent(wrapper, visibleVariant);
+    if (vis) return vis;
+  }
+  return placeholder || insertAnchor || null;
+}
+
+/**
+ * Snapshot placeholder geometry + anchor fingerprint so HMR can recreate the box.
+ * @param {{
+ *   tagName?: string,
+ *   className?: string,
+ *   textContent?: string,
+ * }} anchor
+ * @param {{
+ *   offsetWidth?: number,
+ *   offsetHeight?: number,
+ *   style?: { marginLeft?: string, marginTop?: string },
+ * }} placeholder
+ * @param {{ position: 'before' | 'after', layoutAxis?: 'row' | 'column' }} meta
+ */
+export function buildInsertPlaceholderSnapshot(anchor, placeholder, { position, layoutAxis }) {
+  return {
+    width: Math.round(placeholder.offsetWidth || 0),
+    height: Math.round(placeholder.offsetHeight || PLACEHOLDER_DEFAULT_HEIGHT),
+    marginLeft: parseFloat(placeholder.style?.marginLeft || '') || 0,
+    marginTop: parseFloat(placeholder.style?.marginTop || '') || 0,
+    position,
+    layoutAxis: layoutAxis || 'column',
+    anchorTag: anchor.tagName || 'DIV',
+    anchorClasses: anchor.className || '',
+    anchorText: (anchor.textContent || '').trim().slice(0, 120),
+  };
+}
+
+/**
+ * Re-find an insert anchor after framework HMR replaced the live DOM node.
+ * @param {Pick<Document, 'body' | 'querySelectorAll'>} doc
+ * @param {ReturnType<typeof buildInsertPlaceholderSnapshot> | null | undefined} snapshot
+ * @param {Element | null | undefined} liveAnchor
+ */
+export function findInsertAnchorInDom(doc, snapshot, liveAnchor = null) {
+  if (liveAnchor && doc.body.contains(liveAnchor)) return liveAnchor;
+  if (!snapshot) return null;
+  const tag = (snapshot.anchorTag || 'div').toLowerCase();
+  const cls = (snapshot.anchorClasses || '').split(/\s+/).filter(Boolean)[0];
+  const needle = snapshot.anchorText || '';
+  const sel = cls ? `${tag}.${cls}` : tag;
+  const candidates = doc.querySelectorAll(sel);
+  for (const candidate of candidates) {
+    if (needle && !(candidate.textContent || '').includes(needle.slice(0, 40))) continue;
+    return candidate;
+  }
+  return null;
+}
@@ -0,0 +1,232 @@
+/**
+ * CLI helper: find an anchor element in source and splice an insert-variant
+ * wrapper before or after it (no original variant — net-new content).
+ *
+ * Usage:
+ *   node live-insert.mjs --id SESSION_ID --count N --position after \
+ *     --classes "hero" --tag section [--file path]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+import {
+  buildSearchQueries,
+  findElement,
+  findAllElements,
+  filterByText,
+  findFileWithQuery,
+  detectCommentSyntax,
+  detectStyleMode,
+  buildCssAuthoring,
+  buildCssSelectorPrefixExamples,
+} from './live-wrap.mjs';
+
+const INSERT_POSITIONS = new Set(['before', 'after']);
+
+export function isInsertPosition(value) {
+  return INSERT_POSITIONS.has(value);
+}
+
+export function computeInsertLine(startLine, endLine, position) {
+  return position === 'before' ? startLine : endLine + 1;
+}
+
+export function buildInsertWrapperLines({ id, count, indent, commentSyntax, isJsx }) {
+  const styleContents = isJsx ? 'style={{ display: "contents" }}' : 'style="display: contents"';
+  const attrs =
+    'data-impeccable-variants="' + id + '" ' +
+    'data-impeccable-mode="insert" ' +
+    'data-impeccable-variant-count="' + count + '" ' +
+    styleContents;
+
+  if (isJsx) {
+    return [
+      indent + '<div ' + attrs + '>',
+      indent + '  ' + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+      indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+      indent + '  ' + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+      indent + '</div>',
+    ];
+  }
+
+  return [
+    indent + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+    indent + '<div ' + attrs + '>',
+    indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+    indent + '</div>',
+    indent + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+  ];
+}
+
+function argVal(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+function resolveElementMatch({ lines, queries, tag, text }) {
+  if (text) {
+    const candidates = [];
+    for (const q of queries) {
+      const all = findAllElements(lines, q, tag);
+      for (const c of all) {
+        if (!candidates.some((x) => x.startLine === c.startLine)) candidates.push(c);
+      }
+      if (candidates.length === 1) break;
+    }
+    if (candidates.length === 0) return { error: 'element_not_found' };
+    if (candidates.length === 1) return { match: candidates[0] };
+    const filtered = filterByText(candidates, lines, text);
+    if (filtered.length === 1) return { match: filtered[0] };
+    if (filtered.length === 0) return { match: candidates[0] };
+    return { error: 'element_ambiguous', candidates: filtered };
+  }
+
+  for (const q of queries) {
+    const match = findElement(lines, q, tag);
+    if (match) return { match };
+  }
+  return { error: 'element_not_found' };
+}
+
+export async function insertCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: node live-insert.mjs [options]
+
+Find an anchor element in source and splice an insert-variant wrapper.
+
+Required:
+  --id ID            Session ID for the variant wrapper
+  --count N          Number of expected variants (1-8)
+  --position POS     before | after (relative to the anchor element)
+
+Element identification (at least one required):
+  --element-id ID    HTML id attribute of the anchor element
+  --classes A,B,C    Comma-separated CSS class names
+  --tag TAG          Tag name (div, section, etc.)
+  --query TEXT       Fallback: raw text to search for
+
+Optional:
+  --file PATH        Source file to search in (skips auto-detection)
+  --text TEXT        Anchor textContent for disambiguation (~80 chars)
+
+Output (JSON):
+  { mode: "insert", file, position, insertLine, commentSyntax, styleMode, styleTag, cssAuthoring }`);
+    process.exit(0);
+  }
+
+  const id = argVal(args, '--id');
+  const count = parseInt(argVal(args, '--count') || '3', 10);
+  const position = argVal(args, '--position');
+  const elementId = argVal(args, '--element-id');
+  const classes = argVal(args, '--classes');
+  const tag = argVal(args, '--tag');
+  const query = argVal(args, '--query');
+  const filePath = argVal(args, '--file');
+  const text = argVal(args, '--text');
+
+  if (!id) { console.error('Missing --id'); process.exit(1); }
+  if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
+  if (!isInsertPosition(position)) { console.error('Invalid --position: ' + position); process.exit(1); }
+  if (!elementId && !classes && !query) {
+    console.error('Need at least one of: --element-id, --classes, --query');
+    process.exit(1);
+  }
+
+  const queries = buildSearchQueries(elementId, classes, tag, query);
+  const genOpts = { cwd: process.cwd() };
+
+  let targetFile = filePath;
+  if (!targetFile) {
+    for (const q of queries) {
+      targetFile = findFileWithQuery(q, process.cwd(), genOpts);
+      if (targetFile) break;
+    }
+    if (!targetFile) {
+      let generatedHit = null;
+      for (const q of queries) {
+        generatedHit = findFileWithQuery(q, process.cwd(), { ...genOpts, includeGenerated: true });
+        if (generatedHit) break;
+      }
+      console.error(JSON.stringify({
+        error: generatedHit ? 'element_not_in_source' : 'element_not_found',
+        fallback: 'agent-driven',
+        hint: 'See "Handle fallback" in live.md.',
+      }));
+      process.exit(1);
+    }
+  } else if (isGeneratedFile(targetFile, genOpts)) {
+    console.error(JSON.stringify({
+      error: 'file_is_generated',
+      fallback: 'agent-driven',
+      file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)),
+    }));
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(targetFile, 'utf-8');
+  const lines = content.split('\n');
+  const resolved = resolveElementMatch({ lines, queries, tag, text });
+
+  if (resolved.error === 'element_ambiguous') {
+    console.error(JSON.stringify({
+      error: 'element_ambiguous',
+      fallback: 'agent-driven',
+      file: path.relative(process.cwd(), targetFile),
+      candidates: resolved.candidates.map((c) => ({
+        startLine: c.startLine + 1,
+        endLine: c.endLine + 1,
+      })),
+    }));
+    process.exit(1);
+  }
+  if (!resolved.match) {
+    console.error(JSON.stringify({ error: 'element_not_found', fallback: 'agent-driven' }));
+    process.exit(1);
+  }
+
+  const { startLine, endLine } = resolved.match;
+  const commentSyntax = detectCommentSyntax(targetFile);
+  const styleMode = detectStyleMode(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  const spliceIndex = computeInsertLine(startLine, endLine, position);
+  const indent = lines[spliceIndex]?.match(/^(\s*)/)?.[1]
+    ?? lines[startLine]?.match(/^(\s*)/)?.[1]
+    ?? '';
+
+  const wrapperLines = buildInsertWrapperLines({
+    id,
+    count,
+    indent,
+    commentSyntax,
+    isJsx,
+  });
+
+  const newLines = [
+    ...lines.slice(0, spliceIndex),
+    ...wrapperLines,
+    ...lines.slice(spliceIndex),
+  ];
+  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+  const insertLine = spliceIndex + 3;
+
+  console.log(JSON.stringify({
+    mode: 'insert',
+    position,
+    file: path.relative(process.cwd(), targetFile),
+    insertLine: insertLine + 1,
+    commentSyntax,
+    styleMode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    cssSelectorPrefixExamples: buildCssSelectorPrefixExamples(styleMode.mode, count),
+    cssAuthoring: buildCssAuthoring(styleMode, count),
+  }));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
+  insertCli();
+}
@@ -3,6 +3,7 @@
 *
 * Usage:
 *   npx impeccable poll                         # Block until browser event, print JSON
+ *   npx impeccable poll --stream                # Experimental: keep polling; one JSON line per event
 *   npx impeccable poll --timeout=600000        # Custom timeout (ms); default is long-poll friendly
 *   npx impeccable poll --reply <id> done       # Reply "done" to event <id>
 *   npx impeccable poll --reply <id> error "msg" # Reply with error
@@ -18,7 +19,9 @@ import { readLiveServerInfo } from './impeccable-paths.mjs';
 // timeout that can't be lowered per-request. We cap each request below
 // that ceiling and loop in `pollOnce` to synthesize a long poll without
 // depending on the standalone undici package.
-const PER_REQUEST_TIMEOUT_MS = 270_000;
+export const PER_REQUEST_TIMEOUT_MS = 270_000;
+
+const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer']);

 function readServerInfo() {
  const record = readLiveServerInfo(process.cwd());
@@ -33,7 +36,11 @@ export function buildPollReplyPayload(token, { id, type, message, file, data })
  return { token, id, type, message, file, data };
 }

-async function postReply(base, token, reply) {
+export function requiresAgentReply(event) {
+  return EVENT_TYPES_NEEDING_AGENT_REPLY.has(event?.type);
+}
+
+export async function postReply(base, token, reply) {
  const res = await fetch(`${base}/poll`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
@@ -45,6 +52,178 @@ async function postReply(base, token, reply) {
  }
 }

+export async function fetchServerStatus(base, token) {
+  const res = await fetch(`${base}/status?token=${token}`);
+  if (res.status === 401) {
+    const err = new Error('Authentication failed. The server token may have changed.');
+    err.code = 'AUTH_FAILED';
+    throw err;
+  }
+  if (!res.ok) {
+    throw new Error(`Status failed: ${res.status} ${res.statusText}`);
+  }
+  return res.json();
+}
+
+export function isEventPending(status, eventId) {
+  return (status.pendingEvents || []).some((entry) => entry.id === eventId);
+}
+
+export async function waitForEventAck(base, token, eventId, {
+  pollIntervalMs = 400,
+  maxWaitMs = 600_000,
+} = {}) {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    const status = await fetchServerStatus(base, token);
+    if (!isEventPending(status, eventId)) return true;
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+  return false;
+}
+
+export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
+  while (true) {
+    if (totalDeadline && Date.now() >= totalDeadline) {
+      return { type: 'timeout' };
+    }
+
+    const remaining = totalDeadline
+      ? totalDeadline - Date.now()
+      : PER_REQUEST_TIMEOUT_MS;
+    const slice = Math.min(Math.max(remaining, 1000), PER_REQUEST_TIMEOUT_MS);
+    const res = await fetch(`${base}/poll?token=${token}&timeout=${slice}`);
+
+    if (res.status === 401) {
+      const err = new Error('Authentication failed. The server token may have changed.');
+      err.code = 'AUTH_FAILED';
+      throw err;
+    }
+
+    if (!res.ok) {
+      throw new Error(`Poll failed: ${res.status} ${res.statusText}`);
+    }
+
+    const next = await res.json();
+    if (next?.type === 'timeout') {
+      if (totalDeadline && Date.now() < totalDeadline) continue;
+      if (!totalDeadline) continue;
+      return next;
+    }
+    return next;
+  }
+}
+
+export async function augmentEventWithAcceptHandling(event, base, token) {
+  if (event.type !== 'accept' && event.type !== 'discard') return event;
+
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const acceptScript = path.join(__dirname, 'live-accept.mjs');
+  const scriptArgs = event.type === 'discard'
+    ? ['--id', event.id, '--discard']
+    : ['--id', event.id, '--variant', event.variantId];
+  if (event.type === 'accept' && event.paramValues && Object.keys(event.paramValues).length > 0) {
+    scriptArgs.push('--param-values', JSON.stringify(event.paramValues));
+  }
+
+  try {
+    const out = execFileSync(
+      'node',
+      [acceptScript, ...scriptArgs],
+      { encoding: 'utf-8', cwd: process.cwd(), timeout: 30_000 },
+    );
+    event._acceptResult = JSON.parse(out.trim());
+  } catch (err) {
+    event._acceptResult = { handled: false, mode: 'error', error: err.message };
+  }
+
+  const completionType = completionTypeForAcceptResult(event.type, event._acceptResult);
+  try {
+    await postReply(base, token, {
+      id: event.id,
+      type: completionType,
+      message: event._acceptResult?.error,
+      file: event._acceptResult?.file,
+      data: event._acceptResult?.carbonize === true ? { carbonize: true } : undefined,
+    });
+  } catch (err) {
+    event._completionAck = { ok: false, error: err.message };
+  }
+  if (!event._completionAck) {
+    event._completionAck = completionAckForAcceptResult(event.id, completionType, event._acceptResult);
+  }
+
+  return event;
+}
+
+export function writeCarbonizeBanner(event) {
+  if (event._acceptResult?.carbonize === true) {
+    process.stderr.write('\n⚠ Carbonize cleanup REQUIRED before next poll. After cleanup, run live-complete.mjs --id ' + event.id + '. See reference/live.md "Required after accept".\n\n');
+  }
+}
+
+export function printPollEvent(event) {
+  console.log(JSON.stringify(event));
+}
+
+export async function runPollOnce(base, token, { totalTimeout = 600_000 } = {}) {
+  const deadline = Date.now() + totalTimeout;
+  const event = await fetchNextEvent(base, token, { totalDeadline: deadline });
+  await augmentEventWithAcceptHandling(event, base, token);
+  writeCarbonizeBanner(event);
+  printPollEvent(event);
+  return event;
+}
+
+export async function runPollStream(base, token, {
+  ackTimeoutMs = 600_000,
+  ackPollIntervalMs = 400,
+  shouldContinue = () => true,
+} = {}) {
+  process.stderr.write('[impeccable-poll] stream mode: one JSON object per line on stdout; use --reply while this process stays running\n');
+
+  while (shouldContinue()) {
+    const event = await fetchNextEvent(base, token);
+    await augmentEventWithAcceptHandling(event, base, token);
+    writeCarbonizeBanner(event);
+    printPollEvent(event);
+
+    if (event.type === 'exit') return event;
+
+    if (requiresAgentReply(event)) {
+      const acked = await waitForEventAck(base, token, event.id, {
+        pollIntervalMs: ackPollIntervalMs,
+        maxWaitMs: ackTimeoutMs,
+      });
+      if (!acked) {
+        const err = new Error(`Timed out waiting for --reply on event ${event.id}`);
+        err.code = 'ACK_TIMEOUT';
+        throw err;
+      }
+    }
+  }
+
+  return null;
+}
+
+function handlePollError(err) {
+  if (err.code === 'AUTH_FAILED') {
+    console.error(err.message);
+    console.error('Try restarting: npx impeccable live stop && npx impeccable live');
+    process.exit(1);
+  }
+  if (err.cause?.code === 'ECONNREFUSED') {
+    console.error('Live server not running. Start one with: npx impeccable live');
+    process.exit(1);
+  }
+  if (err.code === 'ACK_TIMEOUT') {
+    console.error(err.message);
+    process.exit(1);
+  }
+  console.error('Poll failed:', err.message);
+  process.exit(1);
+}
+
 export async function pollCli() {
  const args = process.argv.slice(2);

@@ -54,13 +233,20 @@ export async function pollCli() {
 Wait for a browser event from the live variant server, or reply to one.

 Modes:
-  poll                             Block until a browser event arrives, print JSON
-  poll --reply <id> done           Reply "done" to event <id>
+  poll                             Block until a browser event arrives, print JSON, exit
+  poll --stream                    Keep polling; print one JSON line per event (see live.md)
+  poll --reply <id> done           Reply "done" to event <id> (replace or insert generate)
+  poll --reply <id> steer_done     Reply after handling a steer event (unlocks Steer bar)
  poll --reply <id> error "msg"    Reply with an error message

 Options:
-  --timeout=MS   Long-poll timeout in ms (default: 600000). Use the default unless the user asked to pause live; never use a short timeout to end the chat turn
-  --help         Show this help message`);
+  --timeout=MS        One-shot poll timeout in ms (default: 600000). Ignored in --stream mode
+  --ack-timeout=MS    Stream mode: max wait for --reply after generate/steer (default: 600000)
+  --help              Show this help message
+
+Harness note:
+  Default one-shot mode is the portable contract for Claude Code, Codex, and Cursor.
+  --stream is experimental for harnesses with fast incremental stdout; do not use on Cursor.`);
    process.exit(0);
  }

@@ -74,7 +260,6 @@ Options:
    const status = args[replyIdx + 2] || 'done';
    const fileIdx = args.indexOf('--file');
    const filePath = fileIdx !== -1 && fileIdx + 1 < args.length ? args[fileIdx + 1] : undefined;
-    // Message is any remaining positional arg that isn't a flag
    const message = args.find((a, i) => i > replyIdx + 2 && !a.startsWith('--') && i !== fileIdx + 1) || undefined;

    if (!id) {
@@ -84,8 +269,6 @@ Options:

    try {
      await postReply(base, info.token, { id, type: status, message, file: filePath });
-
-      // Success — silent exit (agent doesn't need output for replies)
    } catch (err) {
      if (err.cause?.code === 'ECONNREFUSED') {
        console.error('Live server not running. Start one with: npx impeccable live');
@@ -97,99 +280,21 @@ Options:
    return;
  }

-  // Poll mode: block until browser event. Default 10 min. Node's built-in
-  // fetch enforces a 300s headers timeout, so we loop in slices under that
-  // ceiling and keep re-polling until we get a real event or the user's
-  // total timeout runs out.
-  const timeoutArg = args.find(a => a.startsWith('--timeout='));
-  const totalTimeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 600000;
+  const streamMode = args.includes('--stream');
+  const ackTimeoutArg = args.find((a) => a.startsWith('--ack-timeout='));
+  const ackTimeoutMs = ackTimeoutArg ? parseInt(ackTimeoutArg.split('=')[1], 10) : 600_000;

-  const deadline = Date.now() + totalTimeout;
-  let event;
  try {
-    while (true) {
-      const remaining = deadline - Date.now();
-      if (remaining <= 0) {
-        event = { type: 'timeout' };
-        break;
-      }
-      const slice = Math.min(remaining, PER_REQUEST_TIMEOUT_MS);
-      const res = await fetch(`${base}/poll?token=${info.token}&timeout=${slice}`);
-
-      if (res.status === 401) {
-        console.error('Authentication failed. The server token may have changed.');
-        console.error('Try restarting: npx impeccable live stop && npx impeccable live');
-        process.exit(1);
-      }
-
-      if (!res.ok) {
-        console.error(`Poll failed: ${res.status} ${res.statusText}`);
-        process.exit(1);
-      }
-
-      const next = await res.json();
-      // Server-side timeout means no browser event arrived in this slice.
-      // Loop and re-poll until we get a real event or we hit the user's
-      // total deadline.
-      if (next?.type === 'timeout' && Date.now() < deadline) continue;
-      event = next;
-      break;
+    if (streamMode) {
+      await runPollStream(base, info.token, { ackTimeoutMs });
+      return;
    }

-    // Auto-handle accept/discard via deterministic script
-    if (event.type === 'accept' || event.type === 'discard') {
-      const __dirname = path.dirname(fileURLToPath(import.meta.url));
-      const acceptScript = path.join(__dirname, 'live-accept.mjs');
-      const scriptArgs = event.type === 'discard'
-        ? ['--id', event.id, '--discard']
-        : ['--id', event.id, '--variant', event.variantId];
-      if (event.type === 'accept' && event.paramValues && Object.keys(event.paramValues).length > 0) {
-        scriptArgs.push('--param-values', JSON.stringify(event.paramValues));
-      }
-      try {
-        const out = execFileSync(
-          'node',
-          [acceptScript, ...scriptArgs],
-          { encoding: 'utf-8', cwd: process.cwd(), timeout: 30_000 }
-        );
-        event._acceptResult = JSON.parse(out.trim());
-      } catch (err) {
-        event._acceptResult = { handled: false, mode: 'error', error: err.message };
-      }
-
-      const completionType = completionTypeForAcceptResult(event.type, event._acceptResult);
-      try {
-        await postReply(base, info.token, {
-          id: event.id,
-          type: completionType,
-          message: event._acceptResult?.error,
-          file: event._acceptResult?.file,
-          data: event._acceptResult?.carbonize === true ? { carbonize: true } : undefined,
-        });
-      } catch (err) {
-        event._completionAck = { ok: false, error: err.message };
-      }
-      if (!event._completionAck) {
-        event._completionAck = completionAckForAcceptResult(event.id, completionType, event._acceptResult);
-      }
-    }
-
-    // Second signal path: stderr banner in case the agent parses stdout
-    // JSON but skips nested fields. One line is enough — the full checklist
-    // is in reference/live.md.
-    if (event._acceptResult?.carbonize === true) {
-      process.stderr.write('\n⚠ Carbonize cleanup REQUIRED before next poll. After cleanup, run live-complete.mjs --id ' + event.id + '. See reference/live.md "Required after accept".\n\n');
-    }
-
-    // Print the event as JSON — the agent reads this from stdout
-    console.log(JSON.stringify(event));
+    const timeoutArg = args.find((a) => a.startsWith('--timeout='));
+    const totalTimeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 600_000;
+    await runPollOnce(base, info.token, { totalTimeout });
  } catch (err) {
-    if (err.cause?.code === 'ECONNREFUSED') {
-      console.error('Live server not running. Start one with: npx impeccable live');
-    } else {
-      console.error('Poll failed:', err.message);
-    }
-    process.exit(1);
+    handlePollError(err);
  }
 }

@@ -21,8 +21,9 @@ import path from 'node:path';
 import net from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { parseDesignMd } from './design-parser.mjs';
-import { resolveContextDir } from './load-context.mjs';
+import { resolveContextDir } from './context.mjs';
 import { createLiveSessionStore } from './live-session-store.mjs';
+import { validateEvent } from './live-event-validation.mjs';
 import {
  getDesignSidecarPath,
  getLiveAnnotationsDir,
@@ -33,7 +34,7 @@ import {
 } from './impeccable-paths.mjs';

 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// PRODUCT.md / DESIGN.md live wherever load-context.mjs resolves. The generated
+// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
 // DESIGN sidecar is project-local at .impeccable/design.json, with legacy
 // DESIGN.json fallback for existing projects.
 const CONTEXT_DIR = resolveContextDir(process.cwd());
@@ -65,6 +66,7 @@ const state = {
  sseClients: new Set(),   // SSE response objects (server→browser push)
  pendingEvents: [],        // browser events waiting for agent ack ({ event, leaseUntil })
  pendingPolls: [],         // agent poll callbacks waiting for browser events
+  lastAgentPollingBroadcast: null,
  exitTimer: null,
  sessionDir: null,         // per-session tmp dir for annotation screenshots
  sessionStore: null,
@@ -130,16 +132,31 @@ function scheduleLeaseFlush() {
 }

 function flushPendingPolls() {
+  let changed = false;
  while (state.pendingPolls.length > 0) {
    const entry = findAvailablePendingEvent();
    if (!entry) {
      scheduleLeaseFlush();
+      broadcastAgentPollingIfChanged();
      return;
    }
    const poll = state.pendingPolls.shift();
    poll.resolve(leaseEvent(entry, poll.leaseMs));
+    changed = true;
  }
  scheduleLeaseFlush();
+  if (changed) broadcastAgentPollingIfChanged();
+}
+
+function agentPollingConnected() {
+  return state.pendingPolls.length > 0;
+}
+
+function broadcastAgentPollingIfChanged() {
+  const connected = agentPollingConnected();
+  if (state.lastAgentPollingBroadcast === connected) return;
+  state.lastAgentPollingBroadcast = connected;
+  broadcast({ type: 'agent_polling', connected });
 }

 /** Push a message to all connected SSE clients. */
@@ -187,8 +204,7 @@ function loadBrowserScripts() {
 function hasProjectContext() {
  // PRODUCT.md carries brand voice / anti-references — that's what determines
  // whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
-  // concern, surfaced by the design panel's own empty state. Legacy
-  // .impeccable.md is auto-migrated to PRODUCT.md by load-context.mjs.
+  // concern, surfaced by the design panel's own empty state.
  try {
    fs.accessSync(path.join(CONTEXT_DIR, 'PRODUCT.md'), fs.constants.R_OK);
    return true;
@@ -199,66 +215,6 @@ function statOrNull(filePath) {
  try { return fs.statSync(filePath); } catch { return null; }
 }

-// ---------------------------------------------------------------------------
-// Validation (inline — no external import needed for self-contained script)
-// ---------------------------------------------------------------------------
-
-const VISUAL_ACTIONS = [
-  'impeccable', 'bolder', 'quieter', 'distill', 'polish', 'typeset',
-  'colorize', 'layout', 'adapt', 'animate', 'delight', 'overdrive',
-];
-
-// Browser generates ids via crypto.randomUUID().slice(0, 8) (8 hex chars)
-// and variantIds via String(small integer). Restrict to those shapes so
-// any value that reaches a downstream child_process or DOM selector is
-// inert by construction.
-const ID_PATTERN = /^[0-9a-f]{8}$/;
-const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
-
-function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
-function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
-
-function validateEvent(msg) {
-  if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
-  switch (msg.type) {
-    case 'generate':
-      if (!isValidId(msg.id)) return 'generate: missing or malformed id';
-      if (!msg.action || !VISUAL_ACTIONS.includes(msg.action)) return 'generate: invalid action';
-      if (!Number.isInteger(msg.count) || msg.count < 1 || msg.count > 8) return 'generate: count must be 1-8';
-      if (!msg.element || !msg.element.outerHTML) return 'generate: missing element context';
-      // Optional annotation fields (all-or-nothing: if any present, all must be well-formed).
-      if (msg.screenshotPath !== undefined && typeof msg.screenshotPath !== 'string') return 'generate: screenshotPath must be string';
-      if (msg.comments !== undefined && !Array.isArray(msg.comments)) return 'generate: comments must be array';
-      if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) return 'generate: strokes must be array';
-      return null;
-    case 'accept':
-      if (!isValidId(msg.id)) return 'accept: missing or malformed id';
-      if (!isValidVariantId(msg.variantId)) return 'accept: missing or malformed variantId';
-      if (msg.paramValues !== undefined) {
-        if (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues)) {
-          return 'accept: paramValues must be an object';
-        }
-      }
-      return null;
-    case 'discard':
-      return isValidId(msg.id) ? null : 'discard: missing or malformed id';
-    case 'checkpoint':
-      if (!isValidId(msg.id)) return 'checkpoint: missing or malformed id';
-      if (!Number.isInteger(msg.revision) || msg.revision < 0) return 'checkpoint: revision must be a non-negative integer';
-      if (msg.paramValues !== undefined && (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues))) {
-        return 'checkpoint: paramValues must be an object';
-      }
-      return null;
-    case 'exit':
-      return null;
-    case 'prefetch':
-      if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return 'prefetch: missing pageUrl';
-      return null;
-    default:
-      return 'Unknown event type: ' + msg.type;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // HTTP request handler
 // ---------------------------------------------------------------------------
@@ -396,6 +352,7 @@ function createRequestHandler({ detectScript, sessionPath, livePath }) {
        status: 'ok',
        port: state.port,
        connectedClients: state.sseClients.size,
+        agentPolling: agentPollingConnected(),
        pendingEvents: state.pendingEvents.map((entry) => ({
          id: entry.event?.id,
          type: entry.event?.type,
@@ -506,6 +463,7 @@ function createRequestHandler({ detectScript, sessionPath, livePath }) {
      res.write('data: ' + JSON.stringify({
        type: 'connected',
        hasProjectContext: hasProjectContext(),
+        agentPolling: agentPollingConnected(),
      }) + '\n\n');

      state.sseClients.add(res);
@@ -614,6 +572,7 @@ function handlePollGet(req, res, url) {
  const timer = setTimeout(() => {
    const idx = state.pendingPolls.indexOf(poll);
    if (idx !== -1) state.pendingPolls.splice(idx, 1);
+    broadcastAgentPollingIfChanged();
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ type: 'timeout' }));
  }, timeout);
@@ -623,11 +582,13 @@ function handlePollGet(req, res, url) {
    res.end(JSON.stringify(event));
  }
  state.pendingPolls.push(poll);
+  broadcastAgentPollingIfChanged();
  scheduleLeaseFlush();
  req.on('close', () => {
    clearTimeout(timer);
    const idx = state.pendingPolls.indexOf(poll);
    if (idx !== -1) state.pendingPolls.splice(idx, 1);
+    broadcastAgentPollingIfChanged();
  });
 }

@@ -649,13 +610,15 @@ function handlePollPost(req, res) {
    acknowledgePendingEvent(msg.id);
    if (state.sessionStore && msg.id) {
      try {
-        const eventType = msg.type === 'discard' || msg.type === 'discarded'
-          ? 'discarded'
-          : msg.type === 'complete'
-            ? 'complete'
-            : msg.type === 'error'
-              ? 'agent_error'
-              : 'agent_done';
+        const eventType = msg.type === 'steer_done'
+          ? 'steer_done'
+          : msg.type === 'discard' || msg.type === 'discarded'
+            ? 'discarded'
+            : msg.type === 'complete'
+              ? 'complete'
+              : msg.type === 'error'
+                ? 'agent_error'
+                : 'agent_done';
        state.sessionStore.appendEvent({
          type: eventType,
          id: msg.id,
@@ -209,6 +209,17 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
+    case 'steer':
+      next.phase = 'steer_requested';
+      next.pageUrl = event.pageUrl ?? next.pageUrl;
+      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
+      next.pendingEvent = toPendingEvent(event);
+      break;
+    case 'steer_done':
+      next.phase = 'steer_done';
+      next.pendingEventSeq = null;
+      next.pendingEvent = null;
+      break;
    case 'discard':
      next.phase = 'discard_requested';
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
@@ -31,6 +31,7 @@ export async function statusCli() {
      status: server.status,
      port: server.port,
      connectedClients: server.connectedClients,
+      agentPolling: server.agentPolling,
      pendingEvents: server.pendingEvents,
    } : null,
    activeSessions: server?.activeSessions || activeSessions,
@@ -370,11 +370,14 @@ function buildCssAuthoring(styleMode, count) {
      selectorExamples: variantNumbers.map((n) => `[data-impeccable-variant="${n}"] > .variant-class`),
      requirements: [
        'Use the styleTag exactly; the is:inline attribute is required for this file.',
+        'Put raw CSS directly between the styleTag opening and a plain </style> close.',
        'Prefix every preview selector with the matching [data-impeccable-variant="N"] selector.',
        'Keep selectors anchored to the generated variant wrapper; do not rely on component CSS scoping for preview rules.',
      ],
      forbidden: [
        'Do not use @scope for this styleMode.',
+        'Do not wrap style content in a JSX/TSX template literal ({` ... `}); that syntax is for .tsx/.jsx only.',
+        'Do not put { immediately after the style opening tag; Astro parses { as expression syntax.',
      ],
    };
  }
@@ -629,4 +632,15 @@ if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/'))
 }

 // Test exports (used by tests/live-wrap.test.mjs)
-export { buildSearchQueries, findElement, findClosingLine, detectCommentSyntax };
+export {
+  buildSearchQueries,
+  findElement,
+  findClosingLine,
+  detectCommentSyntax,
+  findAllElements,
+  filterByText,
+  findFileWithQuery,
+  detectStyleMode,
+  buildCssAuthoring,
+  buildCssSelectorPrefixExamples,
+};
@@ -21,7 +21,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadContext } from './load-context.mjs';
+import { loadContext } from './context.mjs';
 import { resolveFiles } from './live-inject.mjs';
 import { readLiveServerInfo } from './impeccable-paths.mjs';

@@ -80,7 +80,7 @@ The agent should then:
    process.exit(1);
  }

-  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  // 4. Load PRODUCT.md + DESIGN.md context.
  const ctx = loadContext(process.cwd());

  // 5. Compute drift-heal: compare resolved inject targets against the
@@ -102,7 +102,6 @@ The agent should then:
    hasDesign: ctx.hasDesign,
    design: ctx.design,
    designPath: ctx.designPath,
-    migrated: ctx.migrated,
  }, null, 2));
 }

@@ -1,141 +0,0 @@
-/**
- * Shared context loader for every impeccable command that needs to know
- * "who is this for" and "what does this look like".
- *
- * Input: project root (process.cwd()).
- *
- * Output (JSON to stdout):
- *   {
- *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
- *     product: string | null,     // PRODUCT.md contents
- *     productPath: string | null, // relative path
- *     hasDesign: boolean,         // DESIGN.md found
- *     design: string | null,      // DESIGN.md contents
- *     designPath: string | null,
- *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
- *     contextDir: string,         // absolute path of the directory the files were found in
- *   }
- *
- * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
- * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
- * lowercase variants are also matched so users don't get punished for case.
- *
- * Lookup directory resolution (first match wins):
- *   1. process.env.IMPECCABLE_CONTEXT_DIR (absolute or relative to cwd)
- *   2. cwd, if PRODUCT.md / DESIGN.md / .impeccable.md is there (back-compat)
- *   3. Auto-fallback subdirectories of cwd: .agents/context/, then docs/
- *   4. cwd as a default "no context found" location
- *
- * Legacy `.impeccable.md` -> PRODUCT.md migration only fires at cwd root;
- * fallback directories are read-only as far as auto-rename is concerned.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
-const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
-const LEGACY_NAMES = ['.impeccable.md'];
-const FALLBACK_DIRS = ['.agents/context', 'docs'];
-
-/**
- * Resolve the directory that holds PRODUCT.md / DESIGN.md for
- * this project. Exported so other scripts (e.g. live-server.mjs) can read the
- * design files from the same location the loader uses.
- */
-export function resolveContextDir(cwd = process.cwd()) {
-  // 1. Explicit override
-  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
-  if (envDir && envDir.trim()) {
-    const trimmed = envDir.trim();
-    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  }
-
-  // 2. cwd wins if any canonical or legacy file is there. We check legacy too
-  //    so the auto-migration path in loadContext stays predictable.
-  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES, ...LEGACY_NAMES])) {
-    return cwd;
-  }
-
-  // 3. Auto-fallback subdirs. Match if PRODUCT.md or DESIGN.md is present;
-  //    legacy `.impeccable.md` does not pull the lookup into a fallback dir.
-  for (const rel of FALLBACK_DIRS) {
-    const candidate = path.resolve(cwd, rel);
-    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-      return candidate;
-    }
-  }
-
-  // 4. Nothing found — keep the historical "default to cwd" behaviour so the
-  //    caller's `hasProduct === false` branch still fires the same way.
-  return cwd;
-}
-
-export function loadContext(cwd = process.cwd()) {
-  let migrated = false;
-  const contextDir = resolveContextDir(cwd);
-
-  // 1. Look for PRODUCT.md (case-insensitive) in the resolved dir
-  let productPath = firstExisting(contextDir, PRODUCT_NAMES);
-
-  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists at cwd root, rename
-  //    it in place. We only migrate at the root — fallback dirs are read-only
-  //    so we don't surprise users by mutating files under docs/ or .agents/.
-  if (!productPath && contextDir === cwd) {
-    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
-    if (legacyPath) {
-      const newPath = path.join(cwd, 'PRODUCT.md');
-      try {
-        fs.renameSync(legacyPath, newPath);
-        productPath = newPath;
-        migrated = true;
-      } catch {
-        // Rename failed (permissions, etc.) — fall back to reading legacy in place
-        productPath = legacyPath;
-      }
-    }
-  }
-
-  // 3. DESIGN.md (case-insensitive)
-  const designPath = firstExisting(contextDir, DESIGN_NAMES);
-
-  const product = productPath ? safeRead(productPath) : null;
-  const design = designPath ? safeRead(designPath) : null;
-
-  return {
-    hasProduct: !!product,
-    product,
-    productPath: productPath ? path.relative(cwd, productPath) : null,
-    hasDesign: !!design,
-    design,
-    designPath: designPath ? path.relative(cwd, designPath) : null,
-    migrated,
-    contextDir,
-  };
-}
-
-function firstExisting(dir, names) {
-  for (const name of names) {
-    const abs = path.join(dir, name);
-    if (fs.existsSync(abs)) return abs;
-  }
-  return null;
-}
-
-function safeRead(p) {
-  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
-}
-
-// ---------------------------------------------------------------------------
-// CLI mode — print the context as JSON
-// ---------------------------------------------------------------------------
-
-function cli() {
-  const result = loadContext(process.cwd());
-  console.log(JSON.stringify(result, null, 2));
-}
-
-const _running = process.argv[1];
-if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
-  cli();
-}
@@ -0,0 +1,633 @@
+#!/usr/bin/env node
+/**
+ * Brand-seed picker. Returns one OKLCH seed color + the mood it most
+ * naturally evokes, and teaches the model how to compose a full palette
+ * around it.
+ *
+ * The seed is the brand's anchor color. The 5-role palette (bg, surface,
+ * ink, accent, muted) is composed by the caller at runtime using their
+ * judgment + the brief (PRODUCT.md / DESIGN.md / user prompt), NOT picked
+ * from a frozen 4-color preset.
+ *
+ * Why: 4-color frozen palettes drift toward safe defaults (warm-cream bg,
+ * complementary accent on near-white) regardless of brief. A single seed +
+ * the model's own composition lets the same seed produce a dark-mode jazz
+ * club or a light-mode hospitality brand depending on what the brief calls
+ * for. Tested empirically against curated 4-color palettes; seed approach
+ * wins on mood-fit in 3 of 5 cases and ties on the rest.
+ *
+ * Usage:
+ *   node scripts/palette.mjs                  # pick at random
+ *   node scripts/palette.mjs --id seed-021    # pick a specific seed
+ *   node scripts/palette.mjs --from <key>     # hash <key> to a seed (deterministic)
+ *
+ * Env vars:
+ *   IMPECCABLE_PALETTE_SEED — same as --from; useful for the eval harness
+ *     to make runs reproducible.
+ */
+
+import crypto from 'node:crypto';
+
+// Seeds are inlined (129 entries, hand-curated via a tinder review of
+// ~400 candidates from ColorHunt + synthesis + Radix/brand/Pantone anchors).
+// Each carries a mood + strategy the judging model produced — surfaced as
+// hints, not commands; the brief still drives composition.
+const SEEDS = [
+  { id: "seed-200", oklch: [0.360, 0.137, 0.0],
+    mood: "Aesop apothecary shelf — oxblood bottle glass against linen, considered and unhurried",
+    strategy: "Seed is a deep desaturated red-brown that reads as brand ink itself; I push primary darker toward bottle-glass oxblood, pair with a pure white surface so the red does the work, and use a clear pale-blush accent that can carry dark text in pills." },
+  { id: "seed-000", oklch: [0.400, 0.130, 0.0],
+    mood: "oxblood leather banquette in a 1940s steakhouse — low lamplight on dark wood and burgundy",
+    strategy: "Near-black bg with the faintest red undertone lets the oxblood primary glow like lamplit leather; warm cream ink and a brass accent complete the chophouse register." },
+  { id: "seed-002", oklch: [0.450, 0.150, 0.0],
+    mood: "darkroom red light — analog photography, blood-warm safelight glow on chemical trays",
+    strategy: "Near-black surface with a deep oxblood primary lets the seed function like a safelight in a darkroom — the bg disappears so the red becomes the only emotional signal." },
+  { id: "seed-003", oklch: [0.500, 0.194, 0.0],
+    mood: "darkroom safelight — the deep oxblood glow of analog photography, chemical and contemplative",
+    strategy: "Anchored the seed as primary against pure near-black so the red reads like a single illuminated bulb in a developing room, with cool desaturated ink to evoke silver gelatin print tones." },
+  { id: "seed-004", oklch: [0.546, 0.204, 3.4],
+    mood: "midnight boudoir — velvet rose under low lamplight, perfumed and intimate",
+    strategy: "Near-black surface lets the rose seed glow like silk in shadow; a warm champagne accent provides the candle-flame counterpoint without breaking the hush." },
+  { id: "seed-005", oklch: [0.550, 0.180, 0.0],
+    mood: "smoldering vermillion at dusk — the last red ember in a blacksmith's forge, iron-rich and quietly violent",
+    strategy: "Near-black gallery surround lets the seed read as glowing forged metal; ink stays warm-off-white, accent shifts to a hotter ember orange so the primary feels like cooling steel against a fresh strike." },
+  { id: "seed-201", oklch: [0.647, 0.262, 0.3],
+    mood: "Figma plugin marketplace red — confident product-brand crimson, the kind a modern dev tool uses for a 'live' indicator or a primary CTA on a pristine docs page",
+    strategy: "Pure white surface lets a high-chroma crimson primary do all the brand work, paired with a hue-shifted warm coral accent for hierarchy without competing saturation" },
+  { id: "seed-006", oklch: [0.650, 0.160, 0.0],
+    mood: "1960s Italian cinema — Technicolor lipstick red against a darkened theater",
+    strategy: "Pure near-black surface lets a saturated cinematic red and its warm peach accent perform like film light projected in a dark room — the brand colors carry the drama, the bg disappears." },
+  { id: "seed-008", oklch: [0.520, 0.200, 10.4],
+    mood: "Negroni hour at a Milanese bar — bittersweet crimson, vermouth and amaro under low tungsten",
+    strategy: "Seed is a saturated red-crimson with cinematic weight, so I sit it on near-black to let the primary glow like backlit liquor, with a warmer amber accent acting as the citrus twist against the bitter red." },
+  { id: "seed-010", oklch: [0.563, 0.223, 11.0],
+    mood: "Negroni hour on a Milan rooftop — bittersweet crimson, aperitivo light, polished restraint",
+    strategy: "Seed is a vivid carmine-red with strong chroma, so the surface gets out of the way (pure white) and lets the primary do the aperitivo work, with a cooled garnet accent for tension." },
+  { id: "seed-202", oklch: [0.643, 0.247, 7.0],
+    mood: "Glossier brand pink — modern beauty editorial, confident and current",
+    strategy: "Pure white bg lets a saturated rose-red primary do all the brand work, paired with a deeper crimson accent for hierarchy — the Stripe/Glossier move where the color carries the mood." },
+  { id: "seed-013", oklch: [0.400, 0.130, 20.0],
+    mood: "Tuscan cellar at dusk — aged terracotta, oxidized iron, the deep red of decanted Sangiovese",
+    strategy: "Black surface lets the oxblood seed and copper accent glow like firelight on cellar stone; brand colors carry all the warmth while the room recedes." },
+  { id: "seed-014", oklch: [0.450, 0.150, 20.0],
+    mood: "smoldering tannery — oxblood leather, cured under low workshop light",
+    strategy: "Anchor the deep oxblood seed as primary against a near-black architectural ground, then lift with a single warm ember accent so the leather reads burnished rather than bloody." },
+  { id: "seed-016", oklch: [0.550, 0.180, 20.0],
+    mood: "Negroni hour on a Roman terrace — bitter campari red, vermouth, late golden light spilling on white linen",
+    strategy: "Pure white surface lets the campari-red primary do all the emotional work, paired with a deeper oxblood accent for bittersweet depth — Italian aperitivo restraint, not warmth-washed." },
+  { id: "seed-205", oklch: [0.634, 0.254, 17.6],
+    mood: "Aesop apothecary bottle — considered red-coral on a clinical white surface, the kind of brand restraint where one saturated object does all the work",
+    strategy: "Default A pure white surface lets a single coral-red primary carry the entire brand voice; accent shifts to a deeper oxblood for hierarchy without competing chroma." },
+  { id: "seed-011", oklch: [0.639, 0.207, 13.5],
+    mood: "Aperitivo hour in Milan — Campari glow on a white marble bar, crisp and effervescent",
+    strategy: "Pure white gallery backdrop lets the Campari-red primary ring like a single bitter note; ink is near-black with a whisper of warmth, accent shifts to a deeper oxblood for hierarchy without competing hues." },
+  { id: "seed-015", oklch: [0.527, 0.202, 22.7],
+    mood: "Negroni hour on a Milanese terrace — bittersweet vermillion, aperitivo glassware catching low sun",
+    strategy: "Seed becomes a saturated aperitivo-red primary against pure white so the color carries the bittersweet warmth alone, paired with a deep oxblood accent for typographic gravitas." },
+  { id: "seed-023", oklch: [0.427, 0.175, 29.2],
+    mood: "blacksmith's forge at dusk — iron heated to ember red, the deep glow of oxidized metal and quenching oil",
+    strategy: "Pure black bg lets the seed's ember-red glow radiate like hot iron in a dark forge; accent shifts to a copper-amber to suggest scaling metal and sparks, while ink stays near-white for tool-precise legibility." },
+  { id: "seed-206", oklch: [0.614, 0.234, 28.2],
+    mood: "Aesop apothecary bottle — considered red-orange on lab-white, calm utility with a single confident pigment",
+    strategy: "Pure white surface lets a saturated vermilion primary do all the brand work, paired with a deep oxblood accent for hierarchy without introducing a second hue family" },
+  { id: "seed-029", oklch: [0.665, 0.222, 25.7],
+    mood: "Negroni hour at a Milanese bar — bittersweet orange-red liqueur catching late afternoon light on polished marble",
+    strategy: "Pure white surface lets the seed's vermilion read like Campari in a glass; a deeper oxblood accent provides the bitter depth, with neutral graphite ink keeping the editorial restraint of Italian design." },
+  { id: "seed-022", oklch: [0.418, 0.155, 27.2],
+    mood: "Pompeiian red fresco — oxidized cinnabar on a museum wall, archaeological gravity",
+    strategy: "Pure black gallery surface lets the seed's iron-oxide red read as a lit artifact; accent shifts to an aged terracotta amber, so primary and accent form a fired-clay duet against neutral void." },
+  { id: "seed-024", oklch: [0.464, 0.169, 26.9],
+    mood: "Mid-century darkroom under the safelight — developer trays, oxblood leather, the quiet patience of a print emerging",
+    strategy: "Seed becomes a deep oxblood primary; surface stays pure black so the red glows like a safelight, with a warmer ember accent for hierarchy" },
+  { id: "seed-026", oklch: [0.489, 0.190, 28.3],
+    mood: "smoldering ember in a blacksmith's forge — iron-hot rust, soot, and controlled fire",
+    strategy: "Near-black soot background lets the seed's red-orange glow like heated metal; ink is bone-white, accent is a cooler tempered-steel orange that creates internal heat gradient with the primary." },
+  { id: "seed-027", oklch: [0.568, 0.208, 27.1],
+    mood: "Sicilian blood orange at golden hour — citrus rind, terracotta, sun on stucco",
+    strategy: "Seed reads as vivid blood-orange — picked pure white surface so the citrus-red primary and a deep oxblood accent do all the emotional work, like a Loro Piana editorial spread." },
+  { id: "seed-028", oklch: [0.591, 0.172, 24.0],
+    mood: "Sienna-fired ceramic studio at dusk — terracotta cooling on a wheel, hands still dusted with slip",
+    strategy: "Pure black stage lets the fired-clay primary glow like a kiln ember, with a deeper oxblood accent providing tonal weight rather than hue contrast — a monochrome warm-axis play." },
+  { id: "seed-033", oklch: [0.544, 0.169, 31.3],
+    mood: "1960s Italian terracotta workshop — fired clay, espresso, late-afternoon Mediterranean dust",
+    strategy: "Pure black ground lets the seed's burnt-sienna primary glow like a lit kiln, with a deeper oxblood accent for restrained warmth tension — the brand carries the heat, the surface stays out." },
+  { id: "seed-207", oklch: [0.564, 0.231, 29.1],
+    mood: "Aesop apothecary bottle — considered red oxide, the calm authority of a well-made object on a white shelf",
+    strategy: "Seed becomes the singular brand voice against pure white, with a deeper oxblood accent for hierarchy — the surface disappears so the red does all the speaking." },
+  { id: "seed-035", oklch: [0.663, 0.153, 32.1],
+    mood: "Aesop apothecary bottle — clay-fired warmth, considered retail",
+    strategy: "Pure white surface lets the terracotta primary do the brand work, paired with a deep umber ink and a cooler clay accent for editorial tension." },
+  { id: "seed-037", oklch: [0.590, 0.188, 35.8],
+    mood: "Aesop apothecary bottle — considered terracotta, herbalist restraint, the warmth comes from the glass not the room",
+    strategy: "Seed becomes a muted terracotta primary against pure white so the brand's warmth carries entirely through the color itself; accent shifts to a deeper umber for quiet hierarchy." },
+  { id: "seed-038", oklch: [0.652, 0.229, 34.8],
+    mood: "blown-glass furnace at dusk — molten orange iron pulled from the kiln, a craftsman's signature heat",
+    strategy: "Pure black stage so the seed reads as live ember; primary holds the seed's heat, accent shifts to a brass-amber a hue-step away for a 1.7+ contrast pairing without leaving the fire." },
+  { id: "seed-039", oklch: [0.653, 0.185, 33.5],
+    mood: "Aesop apothecary bottle — considered terracotta, quiet retail craft",
+    strategy: "Seed becomes a grounded clay primary against pure white, paired with a deeper umber accent so the warmth lives entirely in the brand marks, not the surface." },
+  { id: "seed-167", oklch: [0.495, 0.134, 36.0],
+    mood: "Aesop apothecary shelf — burnished terracotta on clinical white, considered craft pharmacy",
+    strategy: "Treat the seed as a brand-carrying burnt-sienna against a pure paper-white surface so the warmth lives entirely in the primary, with a deep umber accent pulled along the same warm axis for typographic gravity." },
+  { id: "seed-147", oklch: [0.500, 0.151, 40.0],
+    mood: "Aesop apothecary shelf — considered terracotta, pharmacy restraint, the brand color does the work against clinical white",
+    strategy: "Anchor the seed's burnt-sienna primary against a pure white surface so the rust speaks alone, with a deep umber ink and a cooler clay accent to give the palette product-brand discipline rather than environmental warmth." },
+  { id: "seed-040", oklch: [0.660, 0.201, 40.0],
+    mood: "Aesop apothecary bottle — amber glass on a clean dispensary shelf, considered and clinical-warm",
+    strategy: "Seed becomes a burnt-amber primary against pure white so the bottle-glass color does the emotional work; accent shifts to a deep olive-bronze for the apothecary-label pairing." },
+  { id: "seed-041", oklch: [0.673, 0.217, 38.6],
+    mood: "Aesop apothecary shelf — considered orange glass, clinical retail restraint",
+    strategy: "Pure white surface lets the burnt-orange primary do all the brand work, with a deep ink-brown for editorial gravity and a muted clay accent that reads as a sibling, not a contrast." },
+  { id: "seed-042", oklch: [0.688, 0.133, 35.8],
+    mood: "Aesop apothecary shelf — terracotta glass, considered retail",
+    strategy: "Seed becomes a warm clay primary against pure white so the bottle-on-marble retail feel comes from the brand color alone; a deeper umber accent gives the label-print contrast." },
+  { id: "seed-043", oklch: [0.781, 0.119, 38.1],
+    mood: "Aesop apothecary catalogue — considered terracotta, dermatological restraint, the warm color doing all the work against clinical white",
+    strategy: "Pure white surface lets the seed's warm clay tone read as the entire brand voice, paired with a deeper umber accent for hierarchy without competing with the primary's warmth." },
+  { id: "seed-168", oklch: [0.400, 0.103, 50.0],
+    mood: "Aesop apothecary bottle — amber glass on a clinical white shelf, considered and pharmaceutical",
+    strategy: "Pure white surface lets the deep amber primary act like tinted glass against a clean shelf; accent is a muted clay that complements without competing, keeping the brand quiet and product-led." },
+  { id: "seed-044", oklch: [0.568, 0.149, 45.9],
+    mood: "1970s desert highway at golden hour — sun-faded terracotta, denim dust, the warmth of a Polaroid pulled from a glovebox",
+    strategy: "Seed becomes a burnt-sienna primary against pure white so the terracotta does all the emotional work; a deep indigo accent acts as the denim shadow opposing the sun, creating the era's signature warm/cool tension without tinting the page." },
+  { id: "seed-045", oklch: [0.607, 0.163, 47.7],
+    mood: "Aesop apothecary shelf — considered amber glass, clinical restraint, craft pharmacy",
+    strategy: "Pure white bg lets the burnt-amber primary do the apothecary work alone, paired with a deeper umber accent and graphite ink for editorial calm." },
+  { id: "seed-046", oklch: [0.653, 0.175, 45.0],
+    mood: "Aesop apothecary shelf — considered amber glass, quiet luxury, restrained craft",
+    strategy: "Pure black backdrop lets the warm amber primary glow like backlit apothecary glass, with a deeper rust accent providing tonal depth in the same hue family — monochromatic warm against neutral void." },
+  { id: "seed-047", oklch: [0.695, 0.205, 43.2],
+    mood: "Aesop apothecary label — sun-warmed amber glass on a clinical countertop, restrained botanical pharmacy",
+    strategy: "Pure white surface lets the burnt-amber primary and a deeper sienna accent do all the brand work, like an apothecary bottle photographed under daylight." },
+  { id: "seed-051", oklch: [0.704, 0.189, 49.0],
+    mood: "blacksmith's forge at dusk — glowing iron, hammered copper, ember light against cooling steel",
+    strategy: "Pure near-black surface lets the seed's molten orange burn like heated metal; accent shifts to a deeper amber-red to suggest the cooling end of the same iron, while ink stays a clean off-white so type reads like chalk on slate." },
+  { id: "seed-171", oklch: [0.550, 0.124, 60.0],
+    mood: "Klim Type Foundry specimen page — considered ochre on paper, design-school-honest",
+    strategy: "Seed becomes a muted ochre primary on pure white; accent is a deep ink-navy pulled across the wheel for editorial contrast without warmth-pooling in the bg" },
+  { id: "seed-148", oklch: [0.650, 0.146, 60.0],
+    mood: "Klim-style editorial gold — late-afternoon paper light on a serif specimen sheet, considered and dry",
+    strategy: "Hold the seed's amber as primary on a pure white page so the gold reads as ink rather than atmosphere, and pair with a deep aubergine accent for typographic contrast." },
+  { id: "seed-052", oklch: [0.700, 0.130, 60.0],
+    mood: "late-afternoon terracotta studio — sun-warmed clay, hands-on craft, the hour before dusk",
+    strategy: "Seed is a saturated amber-ochre with strong environmental association (ceramics, adobe, sunlit plaster), so I lean into Exception (a) with a faintly warm bone surface that reads as lime-washed wall, then deepen the seed slightly for primary and pair it with a fired-clay rust accent for hand-thrown warmth." },
+  { id: "seed-053", oklch: [0.773, 0.157, 56.6],
+    mood: "late-summer apricot orchard at golden hour — sun-warmed fruit, considered Californian craft",
+    strategy: "Seed is a juicy mid-warm orange at daylight luminance — leaning optimistic/editorial, so pure white surface lets the apricot primary glow without muddying it; a deep wine accent provides the bite." },
+  { id: "seed-149", oklch: [0.600, 0.124, 70.0],
+    mood: "1970s desert highway — late-afternoon amber light on chrome and asphalt",
+    strategy: "Anchor the amber seed as primary against pure black so the warm hue reads as headlight glow against night; a cooler dusk-mauve accent provides the complementary tension of horizon vs. sun." },
+  { id: "seed-054", oklch: [0.740, 0.162, 68.1],
+    mood: "late-afternoon honey on terracotta — Mediterranean stucco at golden hour, sun-baked amber",
+    strategy: "Seed is a saturated honey-amber at high lightness; pairing it with pure black lets the warmth read as luminous gold against gravity, like lamplight in a dark room." },
+  { id: "seed-055", oklch: [0.774, 0.174, 65.1],
+    mood: "late-summer honey hour — amber light slanting through a west-facing window, optimistic and golden",
+    strategy: "Anchor a saturated honey-amber primary on pure white so the warmth radiates from the brand itself, then pair with a deep teak accent for grounded contrast rather than tinting the canvas." },
+  { id: "seed-056", oklch: [0.691, 0.146, 74.6],
+    mood: "Klim-style modern publishing house — late-afternoon paper warmth, considered editorial gold",
+    strategy: "Pure white surface so the amber seed becomes the brand voice; ink stays near-black neutral and accent shifts to a deep ink-blue to give the gold something structural to lean on." },
+  { id: "seed-150", oklch: [0.750, 0.148, 80.0],
+    mood: "Klim Type Foundry specimen page — late-summer editorial gold, considered and grown-up",
+    strategy: "Pure white surface lets a single restrained ochre primary do all the brand work, paired with a deep ink-blue accent for typographic contrast in the Klim/Commercial Type tradition." },
+  { id: "seed-058", oklch: [0.764, 0.120, 77.1],
+    mood: "Klim Type Foundry specimen page — late-afternoon ochre, considered editorial typography",
+    strategy: "Pure white surface lets the ochre primary do the brand work, paired with a deep ink-blue accent for editorial contrast — the type-foundry move where one warm hue carries the whole feeling against neutral paper." },
+  { id: "seed-059", oklch: [0.784, 0.144, 79.8],
+    mood: "late afternoon in a Tuscan limonaia — sun-cured amber on whitewashed plaster",
+    strategy: "Pure white surface lets the saffron-amber primary and a deep olive accent carry the Mediterranean warmth, with split-complementary tension between gold and a quiet evergreen." },
+  { id: "seed-061", oklch: [0.817, 0.161, 75.1],
+    mood: "late-afternoon honey on Tuscan limestone — golden hour, slow and luminous",
+    strategy: "Pure white surface lets the amber primary glow like sunlight on a wall, paired with a deep terracotta accent for warm tonal contrast within the same hue family." },
+  { id: "seed-063", oklch: [0.842, 0.165, 91.3],
+    mood: "late-afternoon Tuscan sun on limestone — golden hour, considered, optimistic",
+    strategy: "Pure white surface lets the amber-gold primary radiate as the mood-carrier, with a deep aubergine accent providing the long shadow that golden light needs to feel three-dimensional." },
+  { id: "seed-174", oklch: [0.350, 0.075, 110.0],
+    mood: "olive grove at late afternoon — sun-cured leaves, dust, and quiet Mediterranean weight",
+    strategy: "Pure white surface lets a deep, sun-cured olive primary do the emotional work, with a burnt-terracotta accent providing the warm-earth counterpoint olive groves are known for." },
+  { id: "seed-117", oklch: [0.650, 0.100, 110.0],
+    mood: "Klim-style editorial sage — late-summer foundry catalogue, considered olive-yellow on paper",
+    strategy: "Seed sits at olive-chartreuse; treating it as a quiet typographic primary on pure paper, with a deeper bronze-olive accent for hierarchy — the color does the work, the page disappears." },
+  { id: "seed-118", oklch: [0.750, 0.090, 110.0],
+    mood: "Klim Type Foundry specimen page — late-summer olive light on a working specimen, the honesty of a type designer showing their work",
+    strategy: "Pure white bg lets a desaturated olive-yellow primary do the editorial work, with a deeper olive-bronze accent providing typographic emphasis the way a specimen uses one heavy weight against the body roman." },
+  { id: "seed-065", oklch: [0.797, 0.166, 113.1],
+    mood: "late-summer olive grove at noon — sun-bleached leaves, dry stone, Mediterranean glare",
+    strategy: "Hold the seed as a luminous chartreuse-olive primary against pure white so the color reads as sunlit foliage, pairing it with a deep umber accent for the dry-stone contrast." },
+  { id: "seed-176", oklch: [0.300, 0.071, 120.0],
+    mood: "moss-darkened apothecary jar — herbal, shadowed, mid-19th-century botanical study",
+    strategy: "Seed is a deep desaturated olive-green that reads as preserved botanical pigment; I anchor it on pure white so the dim moss-green primary feels like ink on a herbarium page, with a warm ochre accent supplying the aged-paper counterpoint." },
+  { id: "seed-155", oklch: [0.550, 0.142, 130.0],
+    mood: "moss-bed forest floor at noon — chlorophyll, lichen, sunlit fern",
+    strategy: "Seed is a confident mid-olive green with strong chroma; mood is daylight botanical, so I let the brand greens do the work on a pure paper-white bg and pair with a warm umber accent for fern-against-bark contrast." },
+  { id: "seed-119", oklch: [0.600, 0.154, 130.0],
+    mood: "moss garden at Saihō-ji — damp stone, filtered green light through old cedar",
+    strategy: "Pure near-black bg lets the seed's mossy green glow like wet lichen under low light; accent shifts to a pale ochre-gold like sun catching through canopy." },
+  { id: "seed-179", oklch: [0.300, 0.096, 140.0],
+    mood: "moss on wet stone — forest floor at dusk, deep botanical hush",
+    strategy: "Kept the seed's deep moss green as primary against a near-black surface so the green reads as living shadow, with a pale lichen accent providing the single point of light." },
+  { id: "seed-180", oklch: [0.350, 0.110, 140.0],
+    mood: "moss-darkened apothecary — herbal tinctures in amber glass, pressed botanicals, the deep green of a conservatory at dusk",
+    strategy: "Near-black bg with a whisper of green undertone lets the seed's deep moss read as luminous foliage; a warm parchment accent provides the apothecary-label counterpoint without breaking the herbal register." },
+  { id: "seed-120", oklch: [0.650, 0.100, 140.0],
+    mood: "moss on weathered stone — quiet botanical garden conservatory at midday",
+    strategy: "Pure white bg lets the muted sage-green primary read as a considered botanical mark, with a deeper terracotta accent providing earthen counterpoint without breaking the gallery-like restraint." },
+  { id: "seed-121", oklch: [0.750, 0.090, 140.0],
+    mood: "moss garden at Saihō-ji — diffuse green light filtered through wet stone and lichen",
+    strategy: "Pure near-black bg lets the muted sage-green primary glow like lichen under low light; a warm pale-bone accent acts as the single ray of sun cutting through canopy." },
+  { id: "seed-182", oklch: [0.400, 0.106, 150.0],
+    mood: "moss garden at Saiho-ji — deep cultivated green under wet stone shadow, contemplative and damp",
+    strategy: "Near-black bg with the faintest cool-green undertone evokes shaded stone; primary holds the seed's moss tone while accent shifts to a lichen-yellow for organic counterpoint without breaking the hush." },
+  { id: "seed-157", oklch: [0.550, 0.145, 150.0],
+    mood: "moss garden at Saiho-ji — damp stone, filtered green light through cedar canopy",
+    strategy: "Near-black bg with a faint green undertone evokes deep forest shadow; primary holds the seed's verdant register while accent shifts to a pale lichen-cream to mimic light catching moss." },
+  { id: "seed-122", oklch: [0.600, 0.158, 150.0],
+    mood: "forest floor at first light — moss, lichen, and clean morning air",
+    strategy: "Seed reads as a living, daylight green; surface stays pure white so the green carries the freshness, with a cool teal accent pulling it toward dew rather than earth." },
+  { id: "seed-195", oklch: [0.650, 0.150, 145.0],
+    mood: "Considered horticulture brand — botanical research lab, the green of a healthy stem photographed in clean daylight",
+    strategy: "Pure white surface lets the seed's vegetal green carry the entire brand voice, paired with a deep forest ink and a warm clay accent for editorial contrast." },
+  { id: "seed-183", oklch: [0.350, 0.077, 160.0],
+    mood: "moss-stained apothecary — deep forest glass, herbal tinctures shelved in low candlelight",
+    strategy: "Anchored the seed as primary and built a near-black dark surface with whisper-tinted green to evoke aged apothecary glass, letting the green glow rather than shout." },
+  { id: "seed-184", oklch: [0.400, 0.087, 160.0],
+    mood: "deep forest apothecary — moss, bottle glass, and herbal tincture under afternoon light",
+    strategy: "Seed becomes a botanical-bottle-green primary on pure white, paired with a warm clove-amber accent to evoke herbal pharmacy contrast without tinting the surface." },
+  { id: "seed-158", oklch: [0.550, 0.119, 160.0],
+    mood: "moss on wet stone — forest floor after rain, mineral and quiet",
+    strategy: "Pure white surface lets the deep mossy green carry the entire mood; accent shifts to a damp slate-teal to sit beside primary like lichen on stone without competing." },
+  { id: "seed-159", oklch: [0.600, 0.130, 160.0],
+    mood: "moss-covered forest apothecary — herbal tinctures in amber glass, eucalyptus shadow",
+    strategy: "Anchored the green seed in a near-black backdrop so it reads like botanical glassware lit from within, with a warm amber accent pulled across the wheel to evoke tincture bottles against dark wood." },
+  { id: "seed-185", oklch: [0.450, 0.086, 170.0],
+    mood: "weathered copper patina on a Pacific Northwest greenhouse — oxidized teal, glass light, botanical hush",
+    strategy: "Seed sits as a deep oxidized-teal primary against pure white so the patina reads as pigment, not atmosphere; a rust-copper accent completes the verdigris/oxidation story across the warm-cool axis." },
+  { id: "seed-124", oklch: [0.750, 0.080, 170.0],
+    mood: "sea-glass on a foggy Pacific shoreline — weathered, mineral, quietly oxidized",
+    strategy: "Seed is a soft desaturated teal-green; pairing it on pure white lets the mineral primary read as patinated copper-glass, with a deeper kelp-toned primary and a rusted coral accent to spark the muted teal against its complement." },
+  { id: "seed-160", oklch: [0.550, 0.095, 180.0],
+    mood: "weathered copper patina on a museum bronze — oxidized teal, conservatorial quiet",
+    strategy: "Pure near-black gallery surround lets the patina-teal primary glow like a lit artifact, with a warm verdigris-adjacent accent providing the oxidation contrast against the cool seed." },
+  { id: "seed-161", oklch: [0.720, 0.100, 188.0],
+    mood: "climate-tech dashboard — calm verdigris on plain paper, the quiet confidence of an instrument that just works",
+    strategy: "Seed teal carries the entire mood as a single considered brand color on pure white, with a desaturated copper accent providing warm signal against the cool primary without competing for attention." },
+  { id: "seed-186", oklch: [0.450, 0.074, 200.0],
+    mood: "deep hydrothermal vent — mineral teal under pressure, the cold blue-green of oxidized copper in submerged light",
+    strategy: "Near-black surface lets the mineral teal glow as if lit from within; accent shifts toward verdigris-copper to suggest patina on submerged metal, while ink stays cool-neutral to keep the register austere rather than aquatic-cute." },
+  { id: "seed-125", oklch: [0.650, 0.100, 200.0],
+    mood: "climate-tech dashboard — calm operational teal, the color of clean water data and atmospheric sensors",
+    strategy: "Pure white surface lets a single muted-teal primary do all the brand work, with a deeper marine accent providing hierarchy without competing chroma." },
+  { id: "seed-126", oklch: [0.750, 0.080, 200.0],
+    mood: "climate-tech product brand — quiet competence, dashboards for hard infrastructure problems",
+    strategy: "Hold the seed's muted teal as primary, pair with a sharper cyan-leaning accent for interactive lift, and let a pure white surface do the disappearing act so the brand reads as a tool, not an atmosphere." },
+  { id: "seed-162", oklch: [0.550, 0.091, 210.0],
+    mood: "weathered nautical instrument — patinated brass on oxidized steel, the cool blue-grey of a ship's chronometer at dawn",
+    strategy: "Pure white surface lets the muted teal-steel primary read as a precise instrument mark, with a warm brass accent providing the single point of patina against clinical white." },
+  { id: "seed-163", oklch: [0.450, 0.086, 230.0],
+    mood: "deep harbor at dusk — weathered nautical instruments, brass dials on oxidized steel",
+    strategy: "Near-black background with subtle cool tint evokes the marine dusk; primary holds the seed's teal-blue while a warm brass accent creates the instrument-on-steel tension." },
+  { id: "seed-164", oklch: [0.550, 0.105, 230.0],
+    mood: "deep harbor at dawn — cold steel water, fog-muted light, the quiet before the boats leave",
+    strategy: "Pure near-black bg lets the seed's cold marine blue read as a luminous beacon, while a pale frost-cyan accent evokes diffused dawn light cutting through fog." },
+  { id: "seed-127", oklch: [0.650, 0.100, 230.0],
+    mood: "climate-tech dashboard — atmospheric sensor blue, calm operational clarity",
+    strategy: "Anchor the seed as a confident mid-blue primary on pure white so the brand color carries all the atmospheric feeling, with a deep navy accent for hierarchy and a soft slate muted for body text." },
+  { id: "seed-128", oklch: [0.750, 0.080, 230.0],
+    mood: "climate-tech dashboard — calm atmospheric data, considered sky-blue",
+    strategy: "Pure white surface lets the muted sky-blue primary carry the meteorological calm, with a deep-navy accent providing readable weight against the soft primary." },
+  { id: "seed-187", oklch: [0.350, 0.078, 240.0],
+    mood: "deep harbor at blue hour — wet stone, cold steel, the quiet before night fully lands",
+    strategy: "Near-black architectural bg with a hint of marine chroma lets the seed read as ambient atmosphere rather than UI chrome; a cooler steel accent sits opposite the warmer-shifted primary for navigational clarity." },
+  { id: "seed-077", oklch: [0.578, 0.130, 241.7],
+    mood: "pre-dawn signal tower — cold blue solitude, instruments glowing against the dark",
+    strategy: "Pure near-black bg lets the seed's cold tower-light blue glow as the sole emotional source, with a frost-cyan accent acting as a secondary indicator light." },
+  { id: "seed-188", oklch: [0.400, 0.110, 250.0],
+    mood: "Linear's considered indigo — the calm authority of a well-built developer tool, blueprint ink on a clean page",
+    strategy: "Held the seed as a deep indigo primary against pure white so the brand color carries all the gravity; accent shifts to a cooler, brighter cyan-blue to create a crisp hierarchy pair without warming the surface." },
+  { id: "seed-165", oklch: [0.450, 0.123, 250.0],
+    mood: "blueprint room at dusk — drafting table, graphite, civic-engineering blue",
+    strategy: "Seed is a mid-deep architectural blue with real chroma and no environmental cue, so I stay out of the way with a pure white surface and let the primary do all the talking, pairing it with a burnt-ochre accent for drafting-pencil contrast." },
+  { id: "seed-079", oklch: [0.478, 0.136, 251.8],
+    mood: "twilight cartography — the blue of deep dusk over open water, precise and navigational",
+    strategy: "Pure white surface lets the seed's oceanic blue act as a single navigational anchor, with a warm amber accent struck across it like a lighthouse beam at dusk." },
+  { id: "seed-080", oklch: [0.541, 0.122, 248.2],
+    mood: "Linear-style considered tool blue — the calm, exact register of a modern engineering app where every pixel is intentional",
+    strategy: "Pure white surface lets the considered indigo-blue primary carry the entire brand; a deeper navy accent provides hierarchy without warmth, keeping the palette in a single cool family for that focused-software feel" },
+  { id: "seed-166", oklch: [0.550, 0.149, 250.0],
+    mood: "pre-dawn flight deck — instrument glow against deep cobalt sky, precise and quietly intense",
+    strategy: "Near-black bg with the faintest cool tint reads like a darkened cockpit; the seed becomes a luminous instrument-blue primary, paired with a warm amber accent that mimics avionics readouts for unmistakable signal contrast." },
+  { id: "seed-081", oklch: [0.650, 0.160, 250.0],
+    mood: "deep-sea research vessel at dawn — instrument glow against cold steel light",
+    strategy: "Pure near-white bg keeps the palette technical and instrument-like; the seed blue holds as primary while a desaturated steel-cyan accent reads like signal readouts on glass." },
+  { id: "seed-082", oklch: [0.742, 0.140, 247.4],
+    mood: "high-altitude flight deck at dawn — cold cabin instruments glowing against a sky still holding night",
+    strategy: "Near-black cockpit ground with a faint blue cast lets the seed read as an illuminated instrument; primary holds the seed, accent shifts to cyan for signal/indicator contrast." },
+  { id: "seed-210", oklch: [0.360, 0.140, 260.0],
+    mood: "Linear-style considered tool indigo — late-night focused work, the deep blue of a code editor at 2am where everything else falls away",
+    strategy: "Pure black bg lets the indigo primary carry all the cognitive-focus weight, with a slightly brighter periwinkle accent for interactive lift — the surface disappears so the tool feels weightless." },
+  { id: "seed-189", oklch: [0.400, 0.130, 260.0],
+    mood: "pre-dawn observatory — cold instrument blue, star-chart precision",
+    strategy: "Seed becomes the primary on pure black so the deep instrument-blue glows like a calibration light, with a faint cyan accent reading as starlight against the void." },
+  { id: "seed-211", oklch: [0.420, 0.161, 260.0],
+    mood: "Linear's considered indigo — the tool-for-thought blue of focused product work, calm authority without coldness",
+    strategy: "Hold the seed as a deep indigo primary against pure white, then pair with a slightly warmer, lighter periwinkle accent to create gentle hue separation without breaking the disciplined tool-brand register." },
+  { id: "seed-129", oklch: [0.450, 0.150, 260.0],
+    mood: "pre-dawn observatory — deep cobalt sky just before astronomical twilight, instruments cool to the touch",
+    strategy: "Near-black surface lets the cobalt seed read as luminous starlight; a single warm amber accent acts as the calibration lamp against the cold blue field." },
+  { id: "seed-084", oklch: [0.476, 0.207, 261.2],
+    mood: "pre-dawn flight deck — instrument glow against deep cobalt sky, precise and awake",
+    strategy: "Default B black bg lets the cobalt primary read as a luminous instrument signal, with a cyan accent striking the analogous 'cockpit display' relationship." },
+  { id: "seed-085", oklch: [0.681, 0.132, 258.4],
+    mood: "pre-dawn flight deck — instrument glow against deep cobalt sky",
+    strategy: "Anchored the seed as a luminous primary against a near-black architectural ground, with a warm amber accent acting as the single instrument light cutting through cold blue." },
+  { id: "seed-086", oklch: [0.767, 0.106, 255.9],
+    mood: "Scandinavian winter morning — quiet light through frost, pale sky over snow",
+    strategy: "Anchored a pure white editorial stage so the seed's cool sky-blue reads as crisp polar light, with a deeper navy primary providing the only saturated weight — like a single dark pine against snow." },
+  { id: "seed-083", oklch: [0.340, 0.159, 262.4],
+    mood: "deep cobalt twilight — the moment after sunset when the sky goes electric blue and city windows start to glow",
+    strategy: "Pure black stage lets the cobalt seed act as a luminous neon-window glow, with a warm amber accent across the wheel for the lit-window contrast." },
+  { id: "seed-212", oklch: [0.360, 0.219, 270.0],
+    mood: "Linear-grade tooling indigo — considered software for people who care about craft",
+    strategy: "Anchored the deep indigo seed as primary on a pure white surface so the brand color carries all the weight, with a slightly cooler violet-blue accent for hierarchy without competing chroma." },
+  { id: "seed-130", oklch: [0.400, 0.150, 270.0],
+    mood: "Linear-grade indigo — considered productivity tool, ink on paper, no theatrics",
+    strategy: "Pure white surface lets a deep cool indigo carry all the brand weight, paired with a slightly warmer violet-blue accent for hierarchy without acid." },
+  { id: "seed-213", oklch: [0.411, 0.241, 267.9],
+    mood: "Linear-style indigo — considered tool surface, the kind of blue-violet that sits behind a developer's keyboard at 11pm without shouting",
+    strategy: "Pure black canvas lets a saturated indigo primary do all the brand work, with a cooler cyan-violet accent providing UI signal without competing." },
+  { id: "seed-131", oklch: [0.450, 0.180, 270.0],
+    mood: "monastic indigo dusk — vespers light through stained glass, contemplative and severe",
+    strategy: "Seed becomes a deep indigo primary against pure near-black so the violet reads as luminous stained-glass against architectural shadow, with a cooler iris accent for tonal lift." },
+  { id: "seed-088", oklch: [0.476, 0.158, 268.5],
+    mood: "pre-dawn astronomer's notebook — deep indigo sky just before the stars fade, ink and graphite",
+    strategy: "Near-black bg with the faintest cool tint to evoke night sky without theatrics; primary holds the seed's indigo, accent shifts to a paler periwinkle for stellar contrast, keeping the palette monochromatic-cool and observational." },
+  { id: "seed-196", oklch: [0.530, 0.130, 268.0],
+    mood: "Linear-style considered tool indigo — the deep-focus blue-violet of a thoughtfully built productivity surface, the color of a well-typeset keyboard shortcut",
+    strategy: "Pure white bg lets the indigo seed do all the brand work as primary, with a slightly darker, more saturated violet-shifted accent for hierarchy and interactive states — the surface disappears so the brand color reads as the entire identity." },
+  { id: "seed-132", oklch: [0.700, 0.120, 270.0],
+    mood: "Linear-style considered tool indigo — the quiet violet of a focused product workspace, late-afternoon thinking",
+    strategy: "Pure white surface lets a muted indigo-violet primary and a slightly cooler accent do all the brand work, keeping the register calm and software-like rather than theatrical." },
+  { id: "seed-090", oklch: [0.445, 0.206, 279.1],
+    mood: "Linear-style considered tool indigo — the violet of a focused product surface, not a nightclub",
+    strategy: "Anchor the seed as a confident product primary on pure white, with a cooler indigo-shift accent that reads as a sibling tool color, so the brand violet does all the emotional work." },
+  { id: "seed-133", oklch: [0.500, 0.160, 280.0],
+    mood: "Linear-adjacent indigo — considered productivity tool, the violet of a thinking workspace",
+    strategy: "Seed becomes a measured indigo primary on pure white; accent shifts to a cooler blue-violet to create hierarchy without nightclub saturation, letting the brand color do all the emotional work." },
+  { id: "seed-094", oklch: [0.533, 0.125, 294.3],
+    mood: "Linear-style considered tool indigo — the violet of a focused product surface, calm authority for a creative workspace",
+    strategy: "Pure white canvas lets the indigo-violet primary carry the entire brand voice; accent shifts hue slightly toward blue for a cool, tool-like duotone rather than warm decorative pairing." },
+  { id: "seed-137", oklch: [0.700, 0.120, 290.0],
+    mood: "Linear-adjacent indigo — the considered tool, late-evening focus mode, software made for people who care about craft",
+    strategy: "Pure black surface lets a single restrained indigo-violet carry the brand, with a cooler periwinkle accent providing UI hierarchy without competing — Vercel/Linear dark-mode discipline." },
+  { id: "seed-100", oklch: [0.450, 0.150, 330.0],
+    mood: "velvet boudoir at last call — bruised orchid and lipstick traces under low lamplight",
+    strategy: "Pure near-black surface lets a deep magenta-rose primary smolder while a warm peach accent acts like skin-lit lamplight — drama lives in the brand pair, not the room." },
+  { id: "seed-103", oklch: [0.650, 0.160, 330.0],
+    mood: "1980s Memphis boudoir — powder-pink neon humming against lacquered black, lipstick and lacquer",
+    strategy: "Near-black gallery surface lets the magenta-pink seed read as lit neon; accent shifts to warm coral to create cinematic dichromatic tension without competing chroma." },
+  { id: "seed-228", oklch: [0.360, 0.147, 340.0],
+    mood: "Figma-era creative tool plum — considered productivity software for designers, the inky violet of a serif wordmark on a marketing site",
+    strategy: "Held the seed as a deep plum primary against pure white so the brand color does the emotional work; paired with a muted rose accent for warmth without breaking the productivity-tool restraint." },
+  { id: "seed-107", oklch: [0.500, 0.200, 340.0],
+    mood: "Figma plum — creative-tool confidence, considered magenta for a modern design product",
+    strategy: "Pure white surface lets a saturated magenta-plum primary carry all the brand voice, paired with a cooler violet-leaning accent for hierarchy without competing." },
+  { id: "seed-198", oklch: [0.600, 0.210, 340.0],
+    mood: "Figma-era creative tool plum — confident, considered, made for makers",
+    strategy: "Anchor a saturated plum primary against pure white so the brand color does all the emotional work, with a deeper magenta-rose accent for hierarchy." },
+  { id: "seed-112", oklch: [0.754, 0.193, 343.4],
+    mood: "Figma-era creative tool — confident pink primary doing the brand work on a clean canvas, the way Linear uses indigo or Stripe uses violet",
+    strategy: "Anchor the seed pink as a saturated brand primary on pure white so the color carries all the personality; pair with a cooler plum accent to give the pink something to push against without competing." },
+  { id: "seed-229", oklch: [0.420, 0.163, 350.0],
+    mood: "considered fintech rose — the deep magenta of a modern product brand (think Stripe-adjacent, but rotated toward berry), confident and current",
+    strategy: "pure white surface lets a single deep berry-rose primary do all the brand work, paired with a cooler indigo accent for the contrast move you see in modern product marketing" },
+  { id: "seed-113", oklch: [0.470, 0.173, 354.8],
+    mood: "1960s velvet rope nightclub — crushed magenta, low light, cigarette smoke catching a spotlight",
+    strategy: "Pure black stage so the seed's smoky magenta reads as a single hot spotlight, paired with a cooler violet accent for the second light cue." },
+  { id: "seed-114", oklch: [0.570, 0.158, 353.3],
+    mood: "fin-de-siècle Parisian rose — velvet curtain, theatre program, lipstick blotted on linen",
+    strategy: "Drop bg to true black so the dusty-rose primary reads as stage-lit silk; accent shifts to a warmer coral-mauve at higher lightness to create gentle hue rotation without breaking the romance." },
+  { id: "seed-199", oklch: [0.650, 0.180, 350.0],
+    mood: "modern fintech rose — the considered pink of a Series B brand mark, confident and current without nostalgia",
+    strategy: "Pure white surface lets a saturated rose primary do the brand work, paired with a deep plum accent for hierarchy — the Stripe move applied to a pink hue." },
+  { id: "seed-115", oklch: [0.636, 0.218, 355.3],
+    mood: "backstage at a cabaret — velvet rope, lipstick mark on a champagne glass",
+    strategy: "Seed reads as a saturated stage-light magenta-red; I push it into pure black so the primary glows like a neon sign and the accent (a cold pearl-pink) acts as the spotlight rim — the room is dark, the color does the singing." },
+  { id: "seed-230", oklch: [0.650, 0.249, 354.5],
+    mood: "Modern fintech rose — the considered pink of a contemporary payments brand: confident, alive, and clear-headed",
+    strategy: "Pure white bg lets a saturated rose-magenta primary carry all the brand energy, paired with a cooler indigo accent for trustworthy contrast — the Stripe move applied to a pink hue." },
+  { id: "seed-231", oklch: [0.682, 0.241, 353.2],
+    mood: "Figma-era creative tool — a confident pink-magenta product brand, the kind a modern design platform uses to feel alive without shouting",
+    strategy: "Default A pure white bg lets the saturated pink-magenta primary do all the brand work, with a near-complementary cool teal accent for tool-like clarity and a neutral ink for editorial calm" },
+  { id: "seed-116", oklch: [0.734, 0.183, 356.8],
+    mood: "modern beauty brand DTC — Glossier-adjacent pink, confident and current without being saccharine",
+    strategy: "Pure white surface so the rose-pink primary carries all the brand warmth, paired with a near-black ink and a desaturated mauve accent for editorial restraint." },
+];
+
+function parseArgs(argv) {
+  const args = { id: null, from: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--id' && argv[i + 1]) { args.id = argv[++i]; }
+    else if (a === '--from' && argv[i + 1]) { args.from = argv[++i]; }
+  }
+  return args;
+}
+
+// Hash a key into a stable float in [0, 1) for deterministic weighted picks.
+function hashUnit(key) {
+  const h = crypto.createHash('sha256').update(key).digest();
+  return h.readUInt32BE(0) / 0x100000000;
+}
+
+// The curated library is hue-skewed (more reds/oranges than teals/magentas)
+// because that's where the source material + taste landed. Left uniform, a
+// random pick would land on red ~1/3 of the time. Inverse-frequency weighting
+// gives each seed a weight of 1/(count in its 30° hue bucket), so each hue
+// ZONE is roughly equally likely to be chosen regardless of how many seeds it
+// holds — fair rainbow exposure across runs without pruning the library.
+function buildWeights(seeds) {
+  const bucketCount = {};
+  const bucketOf = (s) => Math.floor(((s.oklch[2] % 360) + 360) % 360 / 30);
+  for (const s of seeds) { const b = bucketOf(s); bucketCount[b] = (bucketCount[b] || 0) + 1; }
+  const weights = seeds.map((s) => 1 / bucketCount[bucketOf(s)]);
+  const total = weights.reduce((a, b) => a + b, 0);
+  return { weights, total };
+}
+
+function weightedPick(seeds, unit) {
+  const { weights, total } = buildWeights(seeds);
+  let target = unit * total;
+  for (let i = 0; i < seeds.length; i++) {
+    target -= weights[i];
+    if (target < 0) return seeds[i];
+  }
+  return seeds[seeds.length - 1];
+}
+
+function pickSeed(seeds, { id, from }) {
+  if (id) {
+    const found = seeds.find(s => s.id === id);
+    if (!found) { console.error(`no seed with id "${id}"`); process.exit(2); }
+    return found;
+  }
+  const envFrom = process.env.IMPECCABLE_PALETTE_SEED;
+  const key = from || envFrom;
+  const unit = key ? hashUnit(key) : Math.random();
+  return weightedPick(seeds, unit);
+}
+
+function fmtOklch([L, C, H]) {
+  return `oklch(${L.toFixed(3)} ${C.toFixed(3)} ${H.toFixed(1)})`;
+}
+
+function hueWord(H) {
+  if (H < 15 || H >= 345) return 'pure red';
+  if (H < 35)  return 'warm red / crimson';
+  if (H < 55)  return 'warm coral / burnt orange';
+  if (H < 80)  return 'orange / honey';
+  if (H < 105) return 'warm amber / honey-gold';
+  if (H < 135) return 'yellow-green / olive';
+  if (H < 170) return 'green';
+  if (H < 200) return 'teal';
+  if (H < 230) return 'sky blue';
+  if (H < 265) return 'cobalt / indigo';
+  if (H < 295) return 'violet / purple';
+  if (H < 330) return 'magenta / pink';
+  return 'deep pink / rose';
+}
+
+// ---------------------------------------------------------------
+
+const args = parseArgs(process.argv.slice(2));
+const seed = pickSeed(SEEDS, args);
+const [L, C, H] = seed.oklch;
+
+// The mood + strategy on each seed were derived by the model that
+// originally judged it. We surface them as *hints*, not commands —
+// the brief should still drive what the seed becomes.
+const moodHint = seed.mood ? ` (one read: "${seed.mood}")` : '';
+const strategyHint = seed.strategy ? `\n  - one example strategy: ${seed.strategy}` : '';
+
+// ---------------------------------------------------------------
+// Fat tool-exit response — what the model sees on stdout.
+// ---------------------------------------------------------------
+
+process.stdout.write(`BRAND SEED · ${seed.id}
+
+Seed color (anchor for your primary brand color):
+  ${fmtOklch(seed.oklch)} — ${hueWord(H)}${moodHint}
+
+This is the brand's anchor — a single beautiful color. Compose the rest of
+the palette around it using YOUR judgment, the brief (PRODUCT.md /
+DESIGN.md / the user's prompt), and the color-strategy guidance already in
+SKILL.md.
+
+How to use:
+
+1. Read the brief. Write one specific phrase describing the mood this
+   product calls for. Be granular. Good: "1970s travel poster — sun-baked
+   warmth, considered", "midnight jazz club — smoky brass, saxophone
+   light", "Scandinavian winter morning — quiet light through frost". Bad:
+   "modern and clean", "warm and inviting". The first lets you compose; the
+   second is generic and will produce generic palettes.
+
+2. The seed's hue (${H.toFixed(0)}°) anchors your primary brand color. You
+   choose L and C to match the mood. The same hue can be deep-and-velvet,
+   bright-and-confident, or pale-and-faded — pick the one the mood demands.
+   Primary's hue should stay within ±10° of the seed.${strategyHint}
+
+3. Now compose the full palette in OKLCH (5 more roles):
+     • bg       — the most important architectural choice.
+                  CORE PRINCIPLE: the mood lives in the BRAND COLORS
+                  (primary + accent) and typography, NOT in the surface.
+                  Stripe is warm — its purple does that, bg is pure
+                  white. Linear is cool — its blue does that, bg is
+                  pure. Notion is warm — its accents do that, bg is
+                  near-pure-white. Putting warmth in BOTH primary AND
+                  bg is the AI cliché.
+
+                  DEFAULT A — PURE white: exactly oklch(1.000 0.000 0).
+                    Not 0.99, not chroma 0.002. Stripe / Notion / Apple
+                    use literal #ffffff. Don't add hidden warmth.
+                    Refs: Stripe, Notion, Linear (light), Apple.com,
+                    Vercel docs, Figma marketing, Loom, Substack.
+
+                  DEFAULT B — PURE black/near-black: L 0.04-0.12,
+                    chroma exactly 0.000. No hue tint. Vercel is
+                    roughly oklch(0.08 0 0). Pick L for mood; C is 0.
+                    Refs: Vercel, A24, Acne, Apple dark, MUBI.
+
+                  ALT 2 — TINTED: chroma 0.015-0.05.
+                    Use ONLY when:
+                    (a) the mood is EXPLICITLY environmental — the surface
+                        IS part of the brand (1920s lacquered interior,
+                        leather library, ceramic studio, hotel lobby), or
+                    (b) the seed itself is desaturated (chroma < 0.10) and
+                        needs a tinted surface to read as a brand.
+                    NOT for "feels warm" / "modern + warm" / "moody". If
+                    your mood says "warm" but doesn't name a specific
+                    environment, use PURE white and let primary carry
+                    the warmth.
+
+                  HEURISTIC: if seed chroma > 0.10 AND mood is product-
+                  focused (not environment-focused), it's almost always
+                  PURE white. Target distribution across many palettes:
+                  ~50% pure white, ~25% pure black, ~25% tinted.
+     • surface  — bg pulled slightly toward ink (10-15% mix). Same hue
+                  family as bg. Used for cards, panels, sections.
+     • ink      — body text color. Must reach ≥7:1 contrast vs bg.
+                  Can carry the brand hue at low chroma in light mode
+                  (slight warmth or coolness toward the brand).
+     • accent   — a SECOND brand color, distinct from primary in BOTH
+                  hue AND lightness. Picked to complement the mood (not
+                  default-complementary across the wheel). Used for
+                  badges, status pills, links, accent rules.
+     • muted    — secondary text. Ink pulled 40% toward bg, keeping ink's
+                  hue. Must reach ≥3.5:1 contrast vs bg.
+
+4. Pick a color STRATEGY (the four steps from SKILL.md):
+     • Restrained: tinted neutrals + accent ≤10% — product default
+     • Committed: one saturated color carries 30-60% — identity-driven
+     • Full palette: 3-4 named roles each used deliberately — brand work
+     • Drenched: the surface IS the color — campaign, hero, statement
+   The brief picks the strategy. A startup dashboard ≠ a perfume brand.
+
+Hard rules (already in SKILL.md, recapped because the seed step is where
+they actually bite):
+
+  - OKLCH only — never hex. Never #RRGGBB.
+  - ink-vs-bg WCAG contrast ≥ 7 (body text must be readable)
+  - primary chroma ≤ 0.23 (above this, primary glows perceptually and
+    no text on it is readable — acid-bright is a UI failure)
+  - if primary L > 0.78, primary chroma ≤ 0.18 (the fluorescent zone)
+  - primary-vs-accent contrast ≥ 1.7 (they must be visually distinct,
+    not two variants of the same hue at similar lightness)
+  - accent must carry readable text on a filled badge/pill: EITHER
+    saturated (chroma ≥ 0.10) OR clearly light (L ≥ 0.85) OR clearly
+    dark (L ≤ 0.30). Never a muddy mid-tone (L 0.45-0.72 + chroma < 0.10)
+    — taupe/mushroom/dusty-grey accents read as weak and can't hold text
+    either way. Saturate it or push its lightness to a clear light/dark.
+  - avoid the saturated AI attractor zones: claude-beige (warm-cream bg
+    + dusty brown primary), forest-green-on-cream, AI-purple-on-white,
+    navy-cream-with-orange-accent
+
+TEXT-ON-COLOR FILLS — pick by perceptual contrast, not just WCAG. The
+rule applies to ANY element where text sits on a saturated color fill:
+primary buttons, accent buttons, badges, status pills, tag highlights,
+filled callouts. Don't only think "primary button" — apply consistently.
+
+For any saturated mid-luminance color (L between 0.42 and 0.78, chroma ≥
+0.08), use WHITE text (or near-white from your bg), not dark text — even
+if WCAG says dark technically passes. The Helmholtz-Kohlrausch effect
+makes saturated colors appear brighter than their luminance suggests,
+and dark text on a warm-or-cool-saturated fill reads as muddy.
+
+Convention: Stripe orange CTAs, McDonald's red, every fintech orange
+button, Vercel's filled badges, Linear's status pills — all use white
+text on saturated bg fills.
+
+Dark text is correct only on PALE fills (L > 0.85) or PURE-NEUTRAL fills
+(chroma near 0). Everything else: white text.
+
+Return your composed palette in CSS custom properties using OKLCH, then
+build with it. The seed is the start, not the recipe.
+`);
@@ -27,7 +27,7 @@ const HARNESS_DIRS = [

 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'document', 'shape',
+  'craft', 'init', 'extract', 'document', 'shape',
  'critique', 'audit',
  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',