chore(cli): bump to v2.1.9 + changelog

Patch bump. Detector adds the body-text-viewport-edge rule (29 total)
and fixes a class of false positives in modern token-based codebases
(OKLCH and var() resolution, anchor inheritance). Live screenshot
overlay no longer flashes solid black during loading.

The "live mode survives disconnects" CLI work and the italic-serif /
hero-eyebrow-chip rules from PR #129 already shipped in the v3.0.7
skill release notes, so they're not re-announced here.

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

.agents/skills/impeccable/SKILL.md

@@ -5,35 +5,22 @@ description: Use when the user wants to design, redesign, shape, critique, audit
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
 
-## Setup (non-optional)
+## Setup
 
-Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+Before any design work or file edits:
 
-| Gate | Required check | If fail |
-|---|---|---|
-| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .agents/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. |
-| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `$impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. |
-| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. |
-| Craft | `$impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `$impeccable shape` and wait for explicit brief confirmation. |
-| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. |
-| Mutation | All active gates above pass. | Do not edit project files yet. |
+1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
+2. Identify the register and load the matching register reference (brand.md or product.md).
+3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects.
 
-Codex-style agents must state this before editing files:
-
-```text
-IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
-```
-
-For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.
-
-Other harnesses should follow the same checklist when they can expose this state.
+Skipping these produces generic output that ignores the project.
 
 ### 1. Context gathering
 
-Two files at the project root, case-insensitive:
+Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
 
-- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
-- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components.
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
 
 Load both in one call:
 
@@ -41,11 +28,11 @@ Load both in one call:
 node .agents/skills/impeccable/scripts/load-context.mjs
 ```
 
-Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`.
+Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
 
 If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one.
 
-`$impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session.
+`$impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session.
 
 If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work.
 
@@ -53,7 +40,7 @@ If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` fo
 
 ### 2. Register
 
-Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product).
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
 
 Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
 
@@ -63,24 +50,24 @@ Load the matching reference: [reference/brand.md](reference/brand.md) or [refere
 
 ## Shared design laws
 
-Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work — don't hold back.
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work. Don't hold back.
 
 ### Color
 
-- Use OKLCH. Reduce chroma as lightness approaches 0 or 100 — high chroma at extremes looks garish.
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
 - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
 - Pick a **color strategy** before picking colors. Four steps on the commitment axis:
-  - **Restrained** — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
-  - **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
-  - **Full palette** — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
-  - **Drenched** — the surface IS the color. Brand heroes, campaign pages.
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
 - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
 
 ### Theme
 
 Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
 
-Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
 
 "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
 
@@ -120,7 +107,10 @@ Match-and-refuse. If you're about to write any of these, rewrite the element wit
 
 If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
 
-**Category-reflex check.** If someone could guess the theme and palette from the category name alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the training-data reflex. Rework the scene sentence and color strategy until the answer is no longer obvious from the domain.
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
 
 ## Commands
 
@@ -150,13 +140,13 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
 | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
 
-Plus two management commands — `pin <command>` and `unpin <command>`, detailed below.
+Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
 
 ### Routing rules
 
-1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
-2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target.
-3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
 
@@ -170,4 +160,4 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
 node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
 ```
 
-Valid `<command>` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.

.agents/skills/impeccable/reference/adapt.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: target platforms/devices and usage contexts.
 
-Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.
+Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
 
 ---
@@ -27,7 +27,7 @@ Understand what needs adaptation and why:
    - What won't work? (Hover states on touch, tiny touch targets)
    - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
 
-**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context.
+**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels.
 
 ## Plan Adaptation Strategy
 
@@ -164,7 +164,7 @@ Choose appropriate breakpoints:
 - Persistent side navigation on desktop
 - Breadcrumbs on smaller screens for context
 
-**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.
+**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect.
 
 **NEVER**:
 - Hide core functionality on mobile (if it matters, make it work)
@@ -187,4 +187,4 @@ Test thoroughly across contexts:
 - **Edge cases**: Very small screens (320px), very large screens (4K)
 - **Slow connections**: Test on throttled network
 
-Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
+When the adaptation feels native to each context, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/animate.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: performance constraints.
 
-Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
+Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut motion that exists only for decoration. Animation fatigue is a real cost; spend the budget on the moments that need it.
 
 ---
 
@@ -8,7 +8,7 @@ Analyze a feature and strategically add animations and micro-interactions that e
 
 Brand: orchestrated page-load sequences, staggered reveals, scroll-driven animation. Motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions.
 
-Product: 150–250 ms on most transitions. Motion conveys state — feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
+Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
 ---
 
@@ -105,12 +105,12 @@ Use appropriate techniques for each animation:
 
 **Easing curves (use these, not CSS defaults):**
 ```css
-/* Recommended - natural deceleration */
---ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
+/* Recommended: natural deceleration */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth */
 --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
 --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
 
-/* AVOID - feel dated and tacky */
+/* AVOID: feel dated and tacky */
 /* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
 /* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
 ```
@@ -153,12 +153,12 @@ Use appropriate techniques for each animation:
 ```
 
 **NEVER**:
-- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
+- Use bounce or elastic easing curves; they feel dated and draw attention to the animation itself
 - Animate layout properties casually (`width`, `height`, `top`, `left`, margins) when transform, FLIP, or grid-based techniques would work
-- Use durations over 500ms for feedback—it feels laggy
-- Animate without purpose—every animation needs a reason
-- Ignore `prefers-reduced-motion`—this is an accessibility violation
-- Animate everything—animation fatigue makes interfaces feel exhausting
+- Use durations over 500ms for feedback (it feels laggy)
+- Animate without purpose (every animation needs a reason)
+- Ignore `prefers-reduced-motion` (this is an accessibility violation)
+- Animate everything (animation fatigue makes interfaces feel exhausting)
 - Block interaction during animations unless intentional
 
 ## Verify Quality
@@ -172,4 +172,4 @@ Test animations thoroughly:
 - **Doesn't block**: Users can interact during/after animations
 - **Adds value**: Makes interface clearer or more delightful
 
-Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.
+When the motion clarifies state instead of decorating it, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/audit.md

@@ -1,4 +1,4 @@
-Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address.
+Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
 
 This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
 
@@ -83,10 +83,10 @@ Check against ALL the **DON'T** guidelines from the parent impeccable skill (alr
 ### Detailed Findings by Severity
 
 Tag every issue with **P0-P3 severity**:
-- **P0 Blocking**: Prevents task completion — fix immediately
-- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release
-- **P2 Minor**: Annoyance, workaround exists — fix in next pass
-- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or WCAG AA violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
 
 For each issue, document:
 - **[P?] Issue name**
@@ -105,14 +105,14 @@ Identify recurring problems that indicate systemic gaps rather than one-off mist
 
 ### Positive Findings
 
-Note what's working well — good practices to maintain and replicate.
+Note what's working well: good practices to maintain and replicate.
 
 ## Recommended Actions
 
 List recommended commands in priority order (P0 first, then P1, then P2):
 
-1. **[P?] `$command-name`** — Brief description (specific context from audit findings)
-2. **[P?] `$command-name`** — Brief description (specific context)
+1. **[P?] `$command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `$command-name`**: Brief description (specific context)
 
 **Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended.
 
@@ -131,4 +131,3 @@ After presenting the summary, tell the user:
 - Forget to prioritize (everything can't be P0)
 - Report false positives without verification
 
-Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.

.agents/skills/impeccable/reference/bolder.md

@@ -1,4 +1,4 @@
-Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
+When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type.
 
 ---
 
@@ -6,7 +6,7 @@ Increase visual impact and personality in designs that are too safe, generic, or
 
 Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV.
 
-Product: "bolder" rarely means theatrics — those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
+Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
 
 ---
 
@@ -32,7 +32,7 @@ If any of these are unclear from the codebase, STOP and use Codex's structured u
 
 **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
 
-**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold. They're generic. Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
+**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
 
 ## Plan Amplification
 
@@ -57,7 +57,7 @@ Systematically increase impact across these dimensions:
 
 ### Color Intensification
 - **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
-- **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop
+- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop
 - **Dominant color strategy**: Let one bold color own 60% of the design
 - **Sharp accents**: High-contrast accent colors that pop
 - **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
@@ -73,7 +73,7 @@ Systematically increase impact across these dimensions:
 ### Visual Effects
 - **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
 - **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
-- **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop)
+- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop)
 - **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
 - **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
 
@@ -81,7 +81,7 @@ Systematically increase impact across these dimensions:
 - **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays
 - **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences
 - **Micro-interactions**: Satisfying hover effects, click feedback, state changes
-- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect)
+- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect)
 
 ### Composition Boldness
 - **Hero moments**: Create clear focal points with dramatic treatment
@@ -92,7 +92,7 @@ Systematically increase impact across these dimensions:
 **NEVER**:
 - Add effects randomly without purpose (chaos ≠ bold)
 - Sacrifice readability for aesthetics (body text must be readable)
-- Make everything bold (then nothing is bold - need contrast)
+- Make everything bold (then nothing is bold; you need contrast)
 - Ignore accessibility (bold design must still meet WCAG standards)
 - Overwhelm with motion (animation fatigue is real)
 - Copy trendy aesthetics blindly (bold means distinctive, not derivative)
@@ -110,4 +110,4 @@ Ensure amplification maintains usability and coherence:
 
 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
 
-Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.
+When the result feels right, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/brand.md

@@ -1,42 +1,54 @@
 # Brand register
 
-When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself — a visitor's impression is the thing being made.
+When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself; a visitor's impression is the thing being made.
 
-The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance — *communicate, not transact* — and diverge wildly in aesthetic. Don't collapse them into a single look.
+The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance (*communicate, not transact*) and diverge wildly in aesthetic. Don't collapse them into a single look.
 
 ## The brand slop test
 
-If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness — a visitor should ask "how was this made?", not "which AI made this?"
+If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness; a visitor should ask "how was this made?", not "which AI made this?"
 
 Brand isn't a neutral register. AI-generated landing pages have flooded the internet, and average is no longer findable. Restraint without intent now reads as mediocre, not refined. Brand surfaces need a POV, a specific audience, a willingness to risk strangeness. Go big or go home.
 
 **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register.
 
+Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart.
+
 ## Typography
 
 ### Font selection procedure
 
 Every project. Never skip.
 
-1. Read the brief. Write three concrete brand-voice words — not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
-2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them — they are training-data defaults and they create monoculture.
-3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object* — a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
+1. Read the brief. Write three concrete brand-voice words. Not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
+2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them; they are training-data defaults and they create monoculture.
+3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object*: a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
 4. Cross-check. "Elegant" is not necessarily serif. "Technical" is not necessarily sans. "Warm" is not Fraunces. If the final pick lines up with the original reflex, start over.
 
 ### Reflex-reject list
 
-Training-data defaults. Ban list — look further:
+Training-data defaults. Ban list. Look further:
 
 Fraunces · Newsreader · Lora · Crimson · Crimson Pro · Crimson Text · Playfair Display · Cormorant · Cormorant Garamond · Syne · IBM Plex Mono · IBM Plex Sans · IBM Plex Serif · Space Mono · Space Grotesk · Inter · DM Sans · DM Serif Display · DM Serif Text · Outfit · Plus Jakarta Sans · Instrument Sans · Instrument Serif
 
+### Reflex-reject aesthetic lanes
+
+Parallel to the font list. Currently saturated aesthetic families that have flooded brand surfaces. If a brief lands in one of these lanes without a register reason that *requires* it (a literal magazine, a literal terminal, a literal industrial signage system), it's the second-order training reflex: the trap one tier deeper than picking a Fraunces font. Look further.
+
+- **Editorial-typographic.** Display serif (often italic) + small mono labels + ruled separators + monochromatic restraint. Klim-influenced, magazine-cover affectation. By 2026, every Stripe-adjacent and Notion-adjacent brand has landed here. The fingerprint: three rule-separated columns, an italic Fraunces / Recoleta / Newsreader headline, lowercase track-spaced metadata, no imagery.
+
+(More entries land here on the same cadence the font list updates. Brutalist-utility and acid-maximalism may join when they saturate. Removing entries when they fall back below saturation is also fine.)
+
+The reflex-reject lists apply to **new design choices**. When the existing brand has already committed to a font or a lane as part of its identity, identity-preservation wins; variants on an existing surface don't second-guess what's already shipping. The reflex-reject lists are for greenfield decisions and for departure-mode variants in [live.md](live.md).
+
 ### Pairing and voice
 
-Distinctive + refined is the goal — the specific shape depends on the brand:
+Distinctive + refined is the goal. The specific shape depends on the brand:
 
 - **Editorial / long-form / luxury**: display serif + sans body (a magazine shape).
 - **Tech / dev tools / fintech**: one committed sans, usually; custom-tight tracking, strong weight contrast inside a single family.
 - **Consumer / food / travel**: warmer pairings, often a humanist sans plus a script or display serif.
-- **Creative studios / agencies**: rule-breaking welcome — mono-only, or display-only, or custom-drawn type as voice.
+- **Creative studios / agencies**: rule-breaking welcome. Mono-only, or display-only, or custom-drawn type as voice.
 
 Two families minimum is the rule *only* when the voice needs it. A single well-chosen family with committed weight/size contrast is stronger than a timid display+body pair.
 
@@ -50,37 +62,38 @@ Light text on dark backgrounds: add 0.05–0.1 to line-height. Light type reads
 
 ## Color
 
-Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess — it's voice. A beige-and-muted-slate landing page ignores the register.
+Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess; it's voice. A beige-and-muted-slate landing page ignores the register.
 
 - Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
 - Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
-- When the strategy is Committed or Drenched, the color is load-bearing. Don't hedge with neutrals around the edges — commit.
+- When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit.
 - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not.
+- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette.
 
 ## Layout
 
 - Asymmetric compositions are one option. Break the grid intentionally for emphasis.
-- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm — generous separations, tight groupings.
-- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed" — the failure mode is splitting the difference into a generic centered stack.
+- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm: generous separations, tight groupings.
+- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed"; the failure mode is splitting the difference into a generic centered stack.
 - Don't default to centering everything. Left-aligned with asymmetric layouts feels more designed; a strict grid reads as confident structure. A centered-stack hero with icon-title-subtitle cards reads as template.
-- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` — breakpoint-free responsiveness.
+- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` for breakpoint-free responsiveness.
 
 ## Imagery
 
 Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
 
-**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse.
+**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
 
-- **For greenfield work without local assets, use stock imagery** — Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `<div>` placeholders.
+- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `<div>` placeholders.
 - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".
 - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one.
 - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish".
 
-Tech / dev-tool brands are the exception where zero imagery can be correct — a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on.
+"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode.
 
 ## Motion
 
-- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions — when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
+- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions, when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
 - For collapsing/expanding sections, transition `grid-template-rows` rather than `height`.
 
 ## Brand bans (on top of the shared absolute bans)
@@ -92,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct — a
 - Timid palettes and average layouts. Safe = invisible.
 - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs.
 - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic.
+- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system.
 
 ## Brand permissions
 
@@ -100,5 +114,5 @@ Brand can afford things product can't. Take them.
 - Ambitious first-load motion. Reveals, scroll-triggered transitions, typographic choreography.
 - Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing.
 - Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero.
-- Unexpected color strategies. Palette IS voice — a calm brand and a restless brand should not share palette mechanics.
+- Unexpected color strategies. Palette IS voice; a calm brand and a restless brand should not share palette mechanics.
 - Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment.

.agents/skills/impeccable/reference/clarify.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: audience technical level and users' mental state in context.
 
-Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
+Find the unclear, confusing, or poorly written interface text and rewrite it. Vague copy creates support tickets and abandonment; specific copy gets users through the task.
 
 
 ---
@@ -146,7 +146,7 @@ Every piece of copy should follow these rules:
 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
 3. **Be active**: "Save changes" not "Changes will be saved"
 4. **Be human**: "Oops, something went wrong" not "System error encountered"
-5. **Be helpful**: Tell users what to do, not just what happened
+5. **Tell users what to do**, not just what happened
 6. **Be consistent**: Use same terms throughout (don't vary for variety)
 
 **NEVER**:
@@ -171,4 +171,4 @@ Test that copy improvements work:
 - **Consistency**: Does it match terminology elsewhere?
 - **Tone**: Is it appropriate for the situation?
 
-Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
+When the copy reads cleanly, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/codex.md

@@ -0,0 +1,92 @@
+# Codex: Visual Direction & Asset Production
+
+This file is loaded by `$impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose.
+
+Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief.
+
+## Step A: Explore Directions with the User
+
+Before generating anything, run a brief direction conversation grounded in the shape brief.
+
+Ask **2-3 targeted questions** about visual lane, color strategy, atmosphere, and named anchor references. Don't enumerate generic menus; tie each question to the shape brief's answers. Example shape-grounded questions:
+
+- "Brief says 'editorial restraint, Klim-adjacent.' Are we closer to a quiet specimen page or a magazine-spread feel with hero imagery?"
+- "Palette strategy from shape was 'Committed.' Want it warm-grounded (deep oxblood + cream) or cool-grounded (slate + paper white)?"
+
+Stop and wait for answers. These pin the palette before any pixel gets generated.
+
+## Step B: Generate the Brand Palette First
+
+Generate **one** palette artifact before any mocks. This is a small, focused image: typography pairing on the chosen background, primary + accent color swatches, one signature ornament or motif. Single image, single pass.
+
+Why palette first: mocks generated against a vague color sense produce noise that drowns out the structural decisions. A confirmed palette is the first concrete contract for everything downstream.
+
+Show the palette to the user. Ask one question: "This is the palette I'm locking in for the mocks. Confirm, or call out what to shift?"
+
+Wait for confirmation. Do not generate mocks against an unconfirmed palette.
+
+## Step C: Generate 1-3 Visual Mocks Against the Palette
+
+Once the palette is confirmed, generate **1 to 3** high-fidelity north-star comps. Each mock must use the confirmed palette and typography. Mocks differ in *structural* direction (hierarchy, topology, density, composition), not in color or motif.
+
+- Brand work: push visual identity, composition, mood, and signature motifs.
+- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure.
+- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero.
+
+Use the `image_gen` tool directly (or via the imagegen skill when available). Don't ask the user to install anything.
+
+## Step D: Approval Loop
+
+Show the comps. Ask what carries forward. Iterate until **one direction is approved** or the user explicitly delegates.
+
+If the user delegates, pick the strongest direction and explain it from the brief, not personal taste.
+
+Before moving to assets, summarize what to carry into code and what *not* to literalize from the mock. This is the handoff between visual exploration and semantic implementation.
+
+## Step E: Mock Fidelity Inventory
+
+Inventory the approved mock's major visible ingredients. For each, decide implementation: semantic HTML/CSS/SVG, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission.
+
+Common ingredients to inventory:
+
+- Hero silhouette and dominant composition
+- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.)
+- Nav and primary CTA treatment
+- Section sequence, especially the second fold
+- Image-native content the concept depends on
+- Typography, density, color/material treatment, motion cues
+
+Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong.
+
+If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, bullets, or copy, stop and fix it. That's a broken implementation, not a harmless interpretation.
+
+Don't substitute a different hero composition or visual driver post-approval without user sign-off.
+
+## Step F: Asset Slicing via the Asset Producer
+
+Raster ingredients identified in Step E need clean production assets. Use the bundled `impeccable_asset_producer` subagent rather than producing inline.
+
+Spawn it as a scoped subagent. If you do not have explicit permission to use agents, stop and ask:
+
+```text
+Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step?
+```
+
+Pass to the agent:
+
+- Approved mock path or screenshot reference
+- Crop paths or a contact sheet with crop ids
+- Output directory
+- Required dimensions, format, transparency needs
+- Avoid list
+- Notes on what should remain semantic HTML/CSS/SVG instead of raster
+
+Attach image generation capability to the spawned agent when the harness supports it. Do **not** load image-generation reference material into the parent thread.
+
+Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode.
+
+Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; reach for real, generated, or stock imagery when the mock or subject matter calls for actual visual content.
+
+## After This File
+
+Once Steps A through F are complete, return to `craft.md` Step 5 (Build to Production Quality). The implementation builds against the confirmed palette, approved mock, and the assets the producer wrote.

.agents/skills/impeccable/reference/cognitive-load.md

@@ -6,17 +6,17 @@ Cognitive load is the total mental effort required to use an interface. Overload
 
 ## Three Types of Cognitive Load
 
-### Intrinsic Load — The Task Itself
+### Intrinsic Load: The Task Itself
 Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it.
 
 **Manage it by**:
 - Breaking complex tasks into discrete steps
 - Providing scaffolding (templates, defaults, examples)
-- Progressive disclosure — show what's needed now, hide the rest
+- Progressive disclosure: show what's needed now, hide the rest
 - Grouping related decisions together
 
-### Extraneous Load — Bad Design
-Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste.
+### Extraneous Load: Bad Design
+Mental effort caused by poor design choices. **Eliminate this ruthlessly.** It's pure waste.
 
 **Common sources**:
 - Confusing navigation that requires mental mapping
@@ -25,8 +25,8 @@ Mental effort caused by poor design choices. **Eliminate this ruthlessly** — i
 - Inconsistent patterns that prevent learning
 - Unnecessary steps between user intent and result
 
-### Germane Load — Learning Effort
-Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery.
+### Germane Load: Learning Effort
+Mental effort spent building understanding. This is *good* cognitive load; it leads to mastery.
 
 **Support it by**:
 - Progressive disclosure that reveals complexity gradually
@@ -58,9 +58,9 @@ Evaluate the interface against these 8 items:
 **Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001).
 
 At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider:
-- **≤4 items**: Within working memory limits — manageable
-- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure
-- **8+ items**: Overloaded — users will skip, misclick, or abandon
+- **≤4 items**: Within working memory limits, manageable
+- **5–7 items**: Pushing the boundary; consider grouping or progressive disclosure
+- **8+ items**: Overloaded; users will skip, misclick, or abandon
 
 **Practical applications**:
 - Navigation menus: ≤5 top-level items (group the rest under clear categories)
@@ -90,7 +90,7 @@ At any decision point, count the number of distinct options, actions, or pieces
 **Fix**: Use plain language. If domain terms are unavoidable, define them inline.
 
 ### 5. The Visual Noise Floor
-**Problem**: Every element has the same visual weight — nothing stands out.
+**Problem**: Every element has the same visual weight; nothing stands out.
 **Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted.
 
 ### 6. The Inconsistent Pattern

.agents/skills/impeccable/reference/color-and-contrast.md

@@ -2,11 +2,11 @@
 
 ## Color Spaces: Use OKLCH
 
-**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
 
-The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness — but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
+The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness, but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
 
-The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex — those are the dominant AI-design defaults, not the right answer for any specific brand.
+The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex; those are the dominant AI-design defaults, not the right answer for any specific brand.
 
 ## Building Functional Palettes
 
@@ -36,8 +36,8 @@ A complete system needs:
 This rule is about **visual weight**, not pixel count:
 
 - **60%**: Neutral backgrounds, white space, base surfaces
-- **30%**: Secondary colors—text, borders, inactive states
-- **10%**: Accent—CTAs, highlights, focus states
+- **30%**: Secondary colors: text, borders, inactive states
+- **10%**: Accent: CTAs, highlights, focus states
 
 The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
 
@@ -59,15 +59,15 @@ The common mistake: using the accent color everywhere because it's "the brand co
 These commonly fail contrast or cause readability issues:
 
 - Light gray text on white (the #1 accessibility fail)
-- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
-- Red text on green background (or vice versa)—8% of men can't distinguish these
+- **Gray text on any colored background**: gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
+- Red text on green background (or vice versa): 8% of men can't distinguish these
 - Blue text on red background (vibrates visually)
 - Yellow text on white (almost always fails)
 - Thin light text on images (unpredictable contrast)
 
 ### Never Use Pure Gray or Pure Black
 
-Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature; real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
 
 ### Testing
 
@@ -88,13 +88,13 @@ You can't just swap colors. Dark mode requires different design decisions:
 | Shadows for depth | Lighter surfaces for depth (no shadows) |
 | Dark text on light | Light text on dark (reduce font weight) |
 | Vibrant accents | Desaturate accents slightly |
-| White backgrounds | Never pure black—use dark gray (oklch 12-18%) |
+| White backgrounds | Never pure black; use dark gray (oklch 12-18%) |
 
-In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project — do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
+In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project; do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
 
 ### Token Hierarchy
 
-Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same.
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer; primitives stay the same.
 
 ## Alpha Is A Design Smell
 

.agents/skills/impeccable/reference/colorize.md

@@ -1,14 +1,14 @@
 > **Additional context needed**: existing brand colors.
 
-Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
+Replace timid grayscale or single-accent designs with a strategic palette: pick a color strategy, choose a hue family that fits the brand, then apply color with intent. More color ≠ better. Strategic color beats rainbow vomit.
 
 ---
 
 ## Register
 
-Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule — that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule; that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
 
-Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators — not decoration. Every color has a consistent meaning across every screen.
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators. Not decoration. Every color has a consistent meaning across every screen.
 
 ---
 
@@ -81,13 +81,13 @@ Add color systematically across these dimensions:
 - **Comparison**: Color coding for different datasets or timeframes
 
 ### Borders & Accents
-- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`)
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes; see the absolute ban on `border-left/right > 1px`)
 - **Underlines**: Color underlines for emphasis or active states
 - **Dividers**: Subtle colored dividers instead of gray lines
 - **Focus rings**: Colored focus indicators matching brand
 - **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
 
-**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe.
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix. Not a side stripe.
 
 ### Typography Color
 - **Colored headings**: Use brand colors for section headings (maintain contrast)
@@ -123,8 +123,8 @@ Ensure color addition improves rather than overwhelms:
 **NEVER**:
 - Use every color in the rainbow (choose 2-4 colors beyond neutrals)
 - Apply color randomly without semantic meaning
-- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead
-- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication
+- Put gray text on colored backgrounds. It looks washed out; use a darker shade of the background color or transparency instead
+- Use pure gray for neutrals. Add subtle color tint (warm or cool) for depth
 - Use pure black (`#000`) or pure white (`#fff`) for large areas
 - Violate WCAG contrast requirements
 - Use color as the only indicator (accessibility issue)
@@ -141,11 +141,11 @@ Test that colorization improves the experience:
 - **Still accessible**: Do all color combinations meet WCAG standards?
 - **Not overwhelming**: Is color balanced and purposeful?
 
-Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
+When the palette earns its place, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params
 
-When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)` — typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)`, typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
 
 ```json
 {"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}

.agents/skills/impeccable/reference/craft.md

@@ -1,43 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar.
+Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar.
 
-## Build Gate
+Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief.
 
-Craft cannot build until all of these are true:
+Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong.
 
-1. PRODUCT context is valid and current.
-2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief.
-3. Implementation references from the brief are loaded.
-4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved.
-5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable.
+## Step 0: Project Foundation
 
-PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user.
+Before shape, before code: figure out what kind of project you're working in.
 
-Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets.
+Look at the working directory. Run `ls`. Check for:
 
-## Craft Contract
+- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it.
+- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it.
+- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set.
 
-Craft is not a first pass. It is a loop with these required artifacts:
+If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief:
 
-1. Confirmed design brief from `shape`.
-2. Approved visual direction, from generated probes / mocks when image generation is available.
-3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code.
-4. Semantic, functional implementation using the project's real stack and conventions.
-5. Browser evidence across relevant viewports.
-6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects.
+```text
+What should this be built on?
+  - Astro (default for content-led brand sites, landing pages, marketing surfaces)
+  - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity)
+  - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment)
+```
 
-Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood."
+Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task.
 
 ## Step 1: Shape the Design
 
-Run $impeccable shape, passing along whatever feature description the user provided.
+Run $impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction.
 
-Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code.
 
-If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation.
+If the user already supplied a confirmed brief or ran shape separately, use it and skip this step.
 
-If the user has already run $impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
+When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient.
 
 ## Step 2: Load References
 
@@ -53,134 +51,51 @@ Then add references based on the brief's needs:
 - Responsive requirements? Consult [responsive-design.md](responsive-design.md)
 - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md)
 
-## Step 3: Land the Visual Direction (Capability-Gated)
+## Step 3: Visual Direction & Assets (Harness-Gated)
 
-Before implementation, generate high-fidelity visual comps when all of these are true:
+If the harness has **native image generation** (currently Codex via `image_gen`), this step is mandatory. **Stop and load [codex.md](codex.md)**. It covers palette generation, mock exploration, the approval loop, mock-fidelity inventory, and asset slicing via the `impeccable_asset_producer` subagent. Follow Steps A-F in that file, then return here for Step 4.
 
-- The work is **net-new** or visually open-ended enough that composition exploration will improve the build.
-- The brief's scope is **mid-fi, high-fi, or production-ready**.
-- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+If the harness lacks native image generation, **state in one line that the visual-direction-by-generation step is being skipped because the harness lacks native image generation, then proceed**. The one-line announcement is required; it forces a conscious decision instead of letting the step quietly evaporate. The brief is your only visual reference. Implement directly from it, treating any named anchor references and the brief's "Design Direction" as the contract.
 
-When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+Whether you generated mocks or not: don't replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. Image-led briefs (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product) need real or sourced imagery in the build, not CSS scenery.
 
-Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
-
-### Purpose
-
-Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone.
-
-### What to generate
-
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration.
-
-- For brand work, push visual identity, composition, and mood aggressively.
-- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states.
-- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero.
-
-The comps must be genuinely different in primary visual direction, not just color variants.
-
-### Approval loop
-
-Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice.
-
-If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste.
-
-Before moving to implementation, summarize:
-
-- What to carry into code
-- What **not** to literalize from the mock
-
-This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
-
-### Mock fidelity inventory
-
-Before building, inventory the approved mock's major visible ingredients:
-
-- Hero silhouette and dominant composition.
-- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects.
-- Nav and primary CTA treatment.
-- Section sequence visible in the mock, especially the second fold.
-- Image-native content the concept depends on.
-- Typography, density, color/material treatment, and motion cues.
-
-For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change.
-
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong.
-
-## Step 4: Asset Extraction (Need-Gated)
-
-If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building.
-
-Good candidates:
-
-- stickers
-- badges
-- seals
-- tickets
-- graphic labels
-- textures
-- abstract objects
-- decorative marks
-- non-semantic scene elements
-
-For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes.
-
-Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code.
-
-Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional.
-
-## Step 5: Build to Production Quality
+## Step 4: Build to Production Quality
 
 Implement the feature following the design brief. Build in passes so structure, visual system, states, motion/media, and responsive behavior each get deliberate attention. The list below is the definition of done, not inspiration.
 
 ### Production bar
 
-- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting.
-- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change.
-- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed.
-- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
-- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes.
-- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant.
-- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality.
-- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles.
-- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace.
-- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.
-- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists.
-- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path.
-- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing.
+- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time.
+- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change.
+- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed.
+- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
+- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width.
+- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run.
+- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality.
+- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix.
+- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve.
+- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about.
+- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace.
+- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.
+- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists.
+- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths.
+- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess.
 
-## Step 6: Browser-Based Iteration
+## Step 5: Iterate Visually
 
-**This step is critical.** Do not stop after the first implementation pass.
+Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation.
 
-Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output.
+If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count.
 
-### Required viewport pass
+For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects.
 
-Check the experience at the viewports that matter for the brief. Default minimum:
+After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix.
 
-- Mobile narrow
-- Tablet or small laptop
-- Desktop wide
+Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review.
 
-For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow.
+Detector or QA output is defect evidence only; never proof the work is finished.
 
-### Critique and fix loop
-
-After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist:
-
-1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies.
-2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects.
-3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention.
-4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink.
-7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment.
-8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason.
-
-The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review.
-
-## Step 7: Present
+## Step 6: Present
 
 Present the result to the user:
 - Show the feature in its primary state
@@ -189,5 +104,3 @@ Present the result to the user:
 - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients.
 - Note any remaining limitations or follow-up risks honestly
 - Ask: "What's working? What isn't?"
-
-Iterate based on feedback. Good design is rarely right on the first pass.

.agents/skills/impeccable/reference/critique.md

@@ -1,8 +1,26 @@
 > **Additional context needed**: what the interface is trying to accomplish.
 
+### Setup: Resolve Target and Load Ignore List
+
+Before gathering assessments, do two small bookkeeping steps. They cost almost nothing and they're what makes critique iterative across runs.
+
+1. **Resolve the primary artifact.** The user's phrasing ("the homepage", "the pricing flow") is not stable enough to track across runs. Resolve it to a concrete file path or URL: the same one you'd already need to scan code or open in a browser. Examples:
+   - "the homepage" → `site/pages/index.astro` (or `http://localhost:3000/` if you're inspecting live)
+   - "the settings modal" → the primary component file (e.g., `src/components/Settings.tsx`)
+   - "this page" → the URL or the page's source file
+   Prefer the source file path over the dev-server URL when both exist; ports drift between runs (`bun dev` vs `bun preview`), file paths don't.
+
+2. **Compute the slug.** Run:
+   ```bash
+   node .agents/skills/impeccable/scripts/critique-storage.mjs slug "<resolved-path-or-url>"
+   ```
+   Keep the printed slug. It identifies this target's stream across runs. If the command exits non-zero ("no stable slug for input"), skip persistence for this run and tell the user; the trend won't update but the critique still goes ahead.
+
+3. **Read the ignore list** at `.impeccable/critique/ignore.md` if it exists. Plain markdown; each non-empty, non-comment line is something the user has marked as "do not re-raise" (deferred tradeoffs, designer-intended deviations, detector false-positives the user accepts). When a finding's text matches a line here (case-insensitive substring against rule name or snippet), **drop it silently**. Do not mention it in the report. This is the ONLY input critique consumes from prior runs; anchoring on prior findings would defeat the point of independent assessment.
+
 ### Gather Assessments
 
-Launch two independent assessments. **Neither may see the other's output** — this isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
+Launch two independent assessments. **Neither may see the other's output.** This isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
 
 Delegate each assessment to a separate sub-agent (Claude Code's `Agent` tool, Codex's subagent spawning, etc.). Each returns structured findings as text. Do NOT output findings to the user yet.
 
@@ -39,11 +57,11 @@ Return structured findings covering: AI slop verdict, heuristic scores, cognitiv
 
 #### Assessment B: Automated Detection
 
-Run the bundled deterministic detector, which flags 25 specific patterns (AI slop tells + general design quality).
+Run the bundled deterministic detector, which flags 27 specific patterns (AI slop tells + general design quality).
 
 **CLI scan**:
 ```bash
-npx impeccable --json [--fast] [target]
+npx impeccable detect --json [--fast] [target]
 ```
 
 - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files.
@@ -52,7 +70,7 @@ npx impeccable --json [--fast] [target]
 - For 500+ files, narrow scope or ask the user
 - Exit code 0 = clean, 2 = findings
 
-**Browser visualization** — **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
+**Browser visualization**: **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
 
 The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically.
 
@@ -160,10 +178,40 @@ Provocative questions that might unlock better solutions:
 - Be direct. Vague feedback wastes everyone's time.
 - Be specific. "The submit button," not "some elements."
 - Say what's wrong AND why it matters to users.
-- Give concrete suggestions, not just "consider exploring..."
+- Give concrete suggestions. Cut "consider exploring..." entirely.
 - Prioritize ruthlessly. If everything is important, nothing is.
 - Don't soften criticism. Developers need honest feedback to ship great design.
 
+### Persist the Snapshot
+
+Once the report above is finalized, write it to `.impeccable/critique/` so the user can refer back, and so `$impeccable polish` can pick up the priority issues without a copy-paste.
+
+Skip this step if the Setup slug was null (vague or root-level target).
+
+1. **Write the body to a temp file** so you can pipe it to the helper. Use the full report (heuristic table, anti-patterns verdict, priority issues, persona red flags) but stop before the "Ask the User" / "Recommended Actions" sections that come later.
+
+2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command:
+   ```bash
+   IMPECCABLE_CRITIQUE_META='{"target":"<user phrasing>","total_score":<n>,"p0_count":<n>,"p1_count":<n>}' \
+     node .agents/skills/impeccable/scripts/critique-storage.mjs write <slug> <body-file>
+   ```
+   The helper prints the absolute path it wrote.
+
+3. **Read the trend** for context:
+   ```bash
+   node .agents/skills/impeccable/scripts/critique-storage.mjs trend <slug> 5
+   ```
+   This returns a JSON array of the last 5 frontmatter entries (including the one you just wrote).
+
+4. **Append a single line to the user-visible output**, after the report and before the questions:
+
+   > **Trend for `<slug>` (last 5 runs): 24 → 28 → 32 → 29 → 32**
+   > Wrote `.impeccable/critique/<filename>`.
+
+   If this is the first run for the slug, the trend is just one score; say so: "First run for this target, no trend yet."
+
+This is fire-and-forget. Do not show the user the helper's JSON output; only the human-readable trend line and the written path. Failures here should not block the rest of the flow; print the error and move on.
+
 ### Ask the User
 
 **After presenting findings**, use targeted questions based on what was actually found. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. These answers will shape the action plan.

.agents/skills/impeccable/reference/delight.md

@@ -1,12 +1,12 @@
 > **Additional context needed**: what's appropriate for the domain (playful vs professional vs quirky vs elegant).
 
-Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
+Find the moments where personality and unexpected polish would turn a functional interface into one users remember and tell other people about. Add only where the moment earns it; delight everywhere reads as noise.
 
 ---
 
 ## Register
 
-Brand: delight can be distributed — copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface.
+Brand: delight can be distributed across copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface.
 
 Product: delight at specific moments, not pages. Completion, first-time actions, error recovery, milestone crossings. Reliability and consistency carry the rest of the experience; delight pushed everywhere reads as noise.
 
@@ -236,14 +236,14 @@ Add personality and joy through these methods:
 - Countdown with encouraging messages
 
 ```
-Loading messages — write ones specific to your product, not generic AI filler:
+Loading messages: write ones specific to your product, not generic AI filler:
 - "Crunching your latest numbers..."
 - "Syncing with your team's changes..."
 - "Preparing your dashboard..."
 - "Checking for updates since yesterday..."
 ```
 
-**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.
+**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy, instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.
 
 ### Celebration Moments
 
@@ -299,4 +299,4 @@ Test that delight actually delights:
 - **Appropriate**: Matches brand and context
 - **Accessible**: Works with reduced motion, screen readers
 
-Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.
+When the moments feel earned, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/distill.md

@@ -1,4 +1,4 @@
-Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
+Strip a design to its essence. Remove anything that doesn't earn its place: redundant elements, repeated information, decorative noise, cosmetic complexity.
 
 
 ---
@@ -23,7 +23,7 @@ Analyze what makes the design feel complex or cluttered:
 
 If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
 
-**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.
+**CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence.
 
 ## Plan Simplification
 
@@ -51,7 +51,7 @@ Systematically remove complexity across these dimensions:
 - **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
 - **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights
 - **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function
-- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards
+- **Flatten structure**: Reduce nesting, remove unnecessary containers; never nest cards inside cards
 - **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead
 - **Consistent spacing**: Use one spacing scale, remove arbitrary gaps
 
@@ -108,4 +108,4 @@ If you removed features or options:
 - Consider if they need alternative access points
 - Note any user feedback to monitor
 
-Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
+When the cuts feel right, hand off to `$impeccable polish` for the final pass. As Antoine de Saint-Exupéry put it: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

.agents/skills/impeccable/reference/document.md

@@ -44,7 +44,7 @@ Rules that matter:
 
 - **Token refs** use `{path.to.token}` (e.g. `{colors.primary}`, `{rounded.md}`). Components may reference primitives; primitives may not reference each other.
 - **Stitch validates colors as hex sRGB only** (`#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`); OKLCH/HSL/P3 trigger a linter warning, not a hard error. YAML accepts the string either way and our own parser is format-agnostic. Choose based on project posture: (a) if the project has an "OKLCH-only" doctrine or uses Display-P3 values that don't round-trip through sRGB, put OKLCH directly in the frontmatter and accept the Stitch linter warning; (b) if the project wants strict Stitch compliance or plans to use their Tailwind/DTCG export pipeline, put hex in the frontmatter and keep OKLCH in prose as the canonical reference. Never split the source of truth without explicit reason.
-- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter — none of those fit. Carry them in the sidecar (Step 4b).
+- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter: none of those fit. Carry them in the sidecar (Step 4b).
 - **Scale keys are open-ended.** Use whatever names the project already uses (`warm-ash-cream`, `surface-container-low`). Don't rename to Material defaults.
 - **Variants are naming convention, not schema.** `button-primary` / `button-primary-hover` / `button-primary-active` as sibling keys.
 
@@ -57,7 +57,7 @@ Rules that matter:
 5. `## Components`
 6. `## Do's and Don'ts`
 
-Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
+Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` (Stitch's own outputs do this), but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
 
 ## When to run
 
@@ -73,7 +73,7 @@ If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user
 - **Scan mode** (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there's code to analyze.
 - **Seed mode**: the project is pre-implementation (fresh teach, nothing built yet). Interview for five high-level answers, write a minimal DESIGN.md marked `<!-- SEED -->`. Re-run in scan mode once there's code.
 
-Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode — don't silently switch. `$impeccable document --seed` forces seed mode regardless of code presence.
+Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode; don't silently switch. `$impeccable document --seed` forces seed mode regardless of code presence.
 
 ## Scan mode (approach C: auto-extract, then confirm descriptive language)
 
@@ -81,29 +81,29 @@ Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no com
 
 Search the codebase in priority order:
 
-1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
-2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
-3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
-4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
-5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
-6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
-7. **Visible rendered output** — if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
+1. **CSS custom properties**: grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
+2. **Tailwind config**: if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
+3. **CSS-in-JS theme files**: styled-components, emotion, vanilla-extract, stitches; look for `theme.ts`, `tokens.ts`, or equivalent.
+4. **Design token files**: `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
+5. **Component library**: scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
+6. **Global stylesheet**: the root CSS file usually has the base typography and color assignments.
+7. **Visible rendered output**: if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
 
 ### Step 2: Auto-extract what can be auto-extracted
 
 Build a structured draft from the discovered tokens. For each token class:
 
-- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
+- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral; omit Secondary and Tertiary rather than inventing them.
 - **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
-- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
+- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer; state it explicitly.
 - **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
 - **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
 
 ### Step 2b: Stage the frontmatter
 
-From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer — what the live panel and Stitch's linter consume.
+From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer: what the live panel and Stitch's linter consume.
 
-- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex — see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
+- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex; see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
 - **Typography**: one entry per role (`display`, `headline`, `title`, `body`, `label`). Typography is an object; include only the props that are real for the project (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`).
 - **Rounded / Spacing**: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (`sm` / `md` / `lg`, or `surface-sm`, or numeric steps).
 - **Components**: one entry per variant (`button-primary`, `button-primary-hover`, `button-ghost`). Reference primitives via `{colors.X}`, `{rounded.Y}`. If a variant needs a property Stitch's 8-prop set doesn't cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead.
@@ -149,7 +149,7 @@ colors:
 ### Primary
 - **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
 
-### Secondary (optional — omit if the project has only one accent)
+### Secondary (optional; omit if the project has only one accent)
 - **[Descriptive Name]** (#HEX): [Role.]
 
 ### Tertiary (optional)
@@ -160,7 +160,7 @@ colors:
 - [...]
 
 ### Named Rules (optional, powerful)
-**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
+**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine, e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
 
 ## 3. Typography
 
@@ -171,7 +171,7 @@ colors:
 **Character:** [1-2 sentence personality description of the pairing.]
 
 ### Hierarchy
-- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
+- **Display** ([weight], [size/clamp], [line-height]): [Purpose; where it appears.]
 - **Headline** ([weight], [size], [line-height]): [Purpose.]
 - **Title** ([weight], [size], [line-height]): [Purpose.]
 - **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
@@ -214,34 +214,34 @@ For each component, lead with a short character line, then specify shape, color
 
 ### Inputs / Fields
 - **Style:** [stroke, background, radius]
-- **Focus:** [treatment — glow, border shift, etc.]
+- **Focus:** [treatment, e.g. glow, border shift, etc.]
 - **Error / Disabled:** [if applicable]
 
 ### Navigation
 - **Style, typography, default/hover/active states, mobile treatment.**
 
-### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
+### [Signature Component] (optional; if the project has a distinctive custom component worth documenting)
 [Description.]
 
 ## 6. Do's and Don'ts
 
-Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name.
+Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific: include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name.
 
 ### Do:
 - **Do** [specific prescription with exact values / named rule].
 - **Do** [...]
 
 ### Don't:
-- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
+- **Don't** [specific prohibition, e.g. "use border-left greater than 1px as a colored stripe"].
 - **Don't** [...]
 - **Don't** [...]
 ```
 
-### Step 4b: Write DESIGN.json sidecar (extensions only)
+### Step 4b: Write .impeccable/design.json sidecar (extensions only)
 
-The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `DESIGN.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
+The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `.impeccable/design.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
 
-Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve DESIGN.md and write only DESIGN.json.
+Regenerate the sidecar whenever you regenerate root `DESIGN.md`. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve `DESIGN.md` and write only `.impeccable/design.json`.
 
 #### Schema
 
@@ -280,7 +280,7 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks
   ],
   "narrative": {
     "northStar": "The Editorial Sanctuary",
-    "overview": "2-3 paragraphs of the philosophy — pulled from DESIGN.md Overview section.",
+    "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.",
     "keyCharacteristics": ["...", "..."],
     "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
     "dos":   ["Do use ..."],
@@ -289,14 +289,14 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks
 }
 ```
 
-**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter — tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints — keyed by the frontmatter token name (`colorMeta.<token-name>`, `typographyMeta.<token-name>`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
+**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter (tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints), keyed by the frontmatter token name (`colorMeta.<token-name>`, `typographyMeta.<token-name>`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
 
 #### Component translation rules
 
-The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly — no post-processing, no framework runtime.
+The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly: no post-processing, no framework runtime.
 
 1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained.
-2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)` — they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
+2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)`; they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
 3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or `<img src="...">`. A typical icon is 16-24px; copy the SVG path data directly.
 4. **States.** Include `:hover`, `:focus-visible`, and (if meaningful) `:active` rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive.
 5. **Reset bloat.** Extract only the component's *distinctive* CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (`box-sizing: border-box`, `line-height: inherit`, `-webkit-font-smoothing`). The panel already has a neutral canvas; don't re-ship resets.
@@ -308,13 +308,13 @@ Aim for a tight set of **5-10 components** that best represent the visual system
 
 - **Canonical primitives (always include if the project has them):** button (each variant as a separate component entry), input/text field, navigation, chip/tag, card.
 - **Signature components (include if distinctive):** hero CTA, featured card, filter pill, any custom pattern the user mentioned as important in PRODUCT.md.
-- **Skip the rest.** Utility components, form building blocks, wrapper layouts — not worth documenting unless visually distinctive.
+- **Skip the rest.** Utility components, form building blocks, wrapper layouts: not worth documenting unless visually distinctive.
 
-If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every DESIGN.json has *something* to render, even on day zero.
+If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every `.impeccable/design.json` has *something* to render, even on day zero.
 
 #### Tonal ramps
 
-For each color token, generate an 8-step `tonalRamp` array — dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
+For each color token, generate an 8-step `tonalRamp` array: dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
 
 #### Narrative mapping
 
@@ -331,7 +331,7 @@ Do not reword. The panel shows these as secondary collapsible context; the same
 ### Step 5: Confirm, refine, and refresh session cache
 
 1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules).
-2. Mention that `DESIGN.json` was also written alongside — the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
+2. Mention that `.impeccable/design.json` was also written alongside; the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
 3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
 4. **Refresh the session cache.** Run `node .agents/skills/impeccable/scripts/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading.
 
@@ -350,24 +350,24 @@ If the user prefers to skip, stop. No file.
 Group into one `AskUserQuestion` interaction. Options must be concrete.
 
 1. **Color strategy.** Pick one:
-   - Restrained — tinted neutrals + one accent ≤10%
-   - Committed — one saturated color carries 30–60% of the surface
-   - Full palette — 3–4 named color roles, each deliberate
-   - Drenched — the surface IS the color
+   - Restrained: tinted neutrals + one accent ≤10%
+   - Committed: one saturated color carries 30–60% of the surface
+   - Full palette: 3–4 named color roles, each deliberate
+   - Drenched: the surface IS the color
    
    Then: one hue family or anchor reference ("deep teal", "mustard", "Klim #ff4500 orange").
 
 2. **Typography direction.** Pick one (specific fonts come later):
    - Serif display + sans body
-   - Single sans (warm / technical / geometric / humanist — pick a feel)
+   - Single sans (warm / technical / geometric / humanist; pick a feel)
    - Display + mono
    - Mono-forward
    - Editorial script + sans
 
 3. **Motion energy.** Pick one:
-   - Restrained — state changes only
-   - Responsive — feedback + transitions, no choreography
-   - Choreographed — orchestrated entrances, scroll-driven sequences
+   - Restrained: state changes only
+   - Responsive: feedback + transitions, no choreography
+   - Choreographed: orchestrated entrances, scroll-driven sequences
 
 4. **Three named references.** Brands, products, printed objects. Not adjectives.
 
@@ -380,19 +380,19 @@ Use the six-section spec from Scan mode. Populate what the interview answers; le
 Lead the file with:
 
 ```markdown
-<!-- SEED — re-run $impeccable document once there's code to capture the actual tokens and components. -->
+<!-- SEED: re-run $impeccable document once there's code to capture the actual tokens and components. -->
 ```
 
 Per-section guidance in seed mode:
 
 - **Overview**: Creative North Star and philosophy phrased from the answers (color strategy + motion energy + references). Reference the user's anti-reference directly.
-- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values — mark as `[to be resolved during implementation]`.
-- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet — `[font pairing to be chosen at implementation]`.
+- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values; mark as `[to be resolved during implementation]`.
+- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet: `[font pairing to be chosen at implementation]`.
 - **Elevation**: inferred from motion energy. Restrained/Responsive → flat by default; Choreographed → layered. One sentence.
-- **Components**: omit entirely — no components exist yet.
+- **Components**: omit entirely; no components exist yet.
 - **Do's and Don'ts**: carry PRODUCT.md's anti-references directly plus the anti-reference named in Q5.
 
-Seed mode writes a minimal frontmatter with `name` and `description` only — no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `DESIGN.json` sidecar in seed mode for the same reason: nothing to render.
+Seed mode writes a minimal frontmatter with `name` and `description` only; no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `.impeccable/design.json` sidecar in seed mode for the same reason: nothing to render.
 
 ### Step 4: Confirm and refresh session cache
 
@@ -402,14 +402,14 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no
 
 ## Style guidelines
 
-- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places — the frontmatter is normative.
+- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places; the frontmatter is normative.
 - **Cite PRODUCT.md anti-references by name** in the Do's and Don'ts section. If PRODUCT.md lists "SaaS landing-page clichés" or "generic AI tool marketing" as anti-references, the DESIGN.md Don'ts should repeat those phrases verbatim so the visual spec enforces the strategic line.
 - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
 - **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
 - **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
-- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
+- **Exact values in parens**: hex codes, px/rem values, font weights; always the number in parens alongside the description.
 - **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
-- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
+- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always", not "consider", "might", "prefer". Match PRODUCT.md's tone.
 - **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
 - **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
 - **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
@@ -417,7 +417,7 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no
 ## Pitfalls
 
 - Don't paste raw CSS class names. Translate to descriptive language.
-- Don't extract every token. Stop at what's actually reused — one-offs pollute the system.
+- Don't extract every token. Stop at what's actually reused; one-offs pollute the system.
 - Don't invent components that don't exist. If the project only has buttons and cards, only document those.
 - Don't overwrite an existing DESIGN.md without asking.
 - Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.

.agents/skills/impeccable/reference/extract.md

@@ -67,4 +67,3 @@ Update design system documentation:
 - Create tokens for every single value (tokens should have semantic meaning)
 - Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate)
 
-Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.

.agents/skills/impeccable/reference/harden.md

@@ -1,4 +1,4 @@
-Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.
+Designs that only work with perfect data aren't production-ready. Harden the interface against the inputs, errors, languages, and network conditions that real users will throw at it.
 
 ## Assess Hardening Needs
 
@@ -344,4 +344,4 @@ Test thoroughly with edge cases:
 - **Errors**: Force API errors, test all error states
 - **Empty**: Remove all data, test empty states
 
-Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
+When edge cases are covered, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/heuristics-scoring.md

@@ -1,6 +1,6 @@
 # Heuristics Scoring Guide
 
-Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough."
+Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest: a 4 means genuinely excellent, not "good enough."
 
 ## Nielsen's 10 Heuristics
 
@@ -18,11 +18,11 @@ Keep users informed about what's happening through timely, appropriate feedback.
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | No feedback — user is guessing what happened |
-| 1 | Rare feedback — most actions produce no visible response |
-| 2 | Partial — some states communicated, major gaps remain |
-| 3 | Good — most operations give clear feedback, minor gaps |
-| 4 | Excellent — every action confirms, progress is always visible |
+| 0 | No feedback; user is guessing what happened |
+| 1 | Rare feedback; most actions produce no visible response |
+| 2 | Partial; some states communicated, major gaps remain |
+| 3 | Good; most operations give clear feedback, minor gaps |
+| 4 | Excellent; every action confirms, progress is always visible |
 
 ### 2. Match Between System and Real World
 
@@ -39,9 +39,9 @@ Speak the user's language. Follow real-world conventions. Information appears in
 | Score | Criteria |
 |-------|----------|
 | 0 | Pure tech jargon, alien to users |
-| 1 | Mostly confusing — requires domain expertise to navigate |
-| 2 | Mixed — some plain language, some jargon leaks through |
-| 3 | Mostly natural — occasional term needs context |
+| 1 | Mostly confusing; requires domain expertise to navigate |
+| 2 | Mixed; some plain language, some jargon leaks through |
+| 3 | Mostly natural; occasional term needs context |
 | 4 | Speaks the user's language fluently throughout |
 
 ### 3. User Control and Freedom
@@ -58,11 +58,11 @@ Users need a clear "emergency exit" from unwanted states without extended dialog
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Users get trapped — no way out without refreshing |
-| 1 | Difficult exits — must find obscure paths to escape |
-| 2 | Some exits — main flows have escape, edge cases don't |
-| 3 | Good control — users can exit and undo most actions |
-| 4 | Full control — undo, cancel, back, and escape everywhere |
+| 0 | Users get trapped; no way out without refreshing |
+| 1 | Difficult exits; must find obscure paths to escape |
+| 2 | Some exits; main flows have escape, edge cases don't |
+| 3 | Good control; users can exit and undo most actions |
+| 4 | Full control; undo, cancel, back, and escape everywhere |
 
 ### 4. Consistency and Standards
 
@@ -78,11 +78,11 @@ Users shouldn't wonder whether different words, situations, or actions mean the
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Inconsistent everywhere — feels like different products stitched together |
-| 1 | Many inconsistencies — similar things look/behave differently |
-| 2 | Partially consistent — main flows match, details diverge |
-| 3 | Mostly consistent — occasional deviation, nothing confusing |
-| 4 | Fully consistent — cohesive system, predictable behavior |
+| 0 | Inconsistent everywhere; feels like different products stitched together |
+| 1 | Many inconsistencies; similar things look/behave differently |
+| 2 | Partially consistent; main flows match, details diverge |
+| 3 | Mostly consistent; occasional deviation, nothing confusing |
+| 4 | Fully consistent; cohesive system, predictable behavior |
 
 ### 5. Error Prevention
 
@@ -98,11 +98,11 @@ Better than good error messages is a design that prevents problems in the first
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Errors easy to make — no guardrails anywhere |
-| 1 | Few safeguards — some inputs validated, most aren't |
-| 2 | Partial prevention — common errors caught, edge cases slip |
-| 3 | Good prevention — most error paths blocked proactively |
-| 4 | Excellent — errors nearly impossible through smart constraints |
+| 0 | Errors easy to make; no guardrails anywhere |
+| 1 | Few safeguards; some inputs validated, most aren't |
+| 2 | Partial prevention; common errors caught, edge cases slip |
+| 3 | Good prevention; most error paths blocked proactively |
+| 4 | Excellent; errors nearly impossible through smart constraints |
 
 ### 6. Recognition Rather Than Recall
 
@@ -118,15 +118,15 @@ Minimize memory load. Make objects, actions, and options visible or easily retri
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Heavy memorization — users must remember paths and commands |
-| 1 | Mostly recall — many hidden features, few visible cues |
-| 2 | Some aids — main actions visible, secondary features hidden |
-| 3 | Good recognition — most things discoverable, few memory demands |
-| 4 | Everything discoverable — users never need to memorize |
+| 0 | Heavy memorization; users must remember paths and commands |
+| 1 | Mostly recall; many hidden features, few visible cues |
+| 2 | Some aids; main actions visible, secondary features hidden |
+| 3 | Good recognition; most things discoverable, few memory demands |
+| 4 | Everything discoverable; users never need to memorize |
 
 ### 7. Flexibility and Efficiency of Use
 
-Accelerators — invisible to novices — speed up expert interaction.
+Accelerators, invisible to novices, speed up expert interaction.
 
 **Check for**:
 - Keyboard shortcuts for common actions
@@ -138,11 +138,11 @@ Accelerators — invisible to novices — speed up expert interaction.
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | One rigid path — no shortcuts or alternatives |
-| 1 | Limited flexibility — few alternatives to the main path |
-| 2 | Some shortcuts — basic keyboard support, limited bulk actions |
-| 3 | Good accelerators — keyboard nav, some customization |
-| 4 | Highly flexible — multiple paths, power features, customizable |
+| 0 | One rigid path; no shortcuts or alternatives |
+| 1 | Limited flexibility; few alternatives to the main path |
+| 2 | Some shortcuts; basic keyboard support, limited bulk actions |
+| 3 | Good accelerators; keyboard nav, some customization |
+| 4 | Highly flexible; multiple paths, power features, customizable |
 
 ### 8. Aesthetic and Minimalist Design
 
@@ -158,11 +158,11 @@ Interfaces should not contain irrelevant or rarely needed information. Every ele
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Overwhelming — everything competes for attention equally |
-| 1 | Cluttered — too much noise, hard to find what matters |
-| 2 | Some clutter — main content clear, periphery noisy |
-| 3 | Mostly clean — focused design, minor visual noise |
-| 4 | Perfectly minimal — every element earns its pixel |
+| 0 | Overwhelming; everything competes for attention equally |
+| 1 | Cluttered; too much noise, hard to find what matters |
+| 2 | Some clutter; main content clear, periphery noisy |
+| 3 | Mostly clean; focused design, minor visual noise |
+| 4 | Perfectly minimal; every element earns its pixel |
 
 ### 9. Help Users Recognize, Diagnose, and Recover from Errors
 
@@ -178,11 +178,11 @@ Error messages should use plain language, precisely indicate the problem, and co
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Cryptic errors — codes, jargon, or no message at all |
-| 1 | Vague errors — "Something went wrong" with no guidance |
-| 2 | Clear but unhelpful — names the problem but not the fix |
-| 3 | Clear with suggestions — identifies problem and offers next steps |
-| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work |
+| 0 | Cryptic errors; codes, jargon, or no message at all |
+| 1 | Vague errors; "Something went wrong" with no guidance |
+| 2 | Clear but unhelpful; names the problem but not the fix |
+| 3 | Clear with suggestions; identifies problem and offers next steps |
+| 4 | Perfect recovery; pinpoints issue, suggests fix, preserves user work |
 
 ### 10. Help and Documentation
 
@@ -200,9 +200,9 @@ Even if the system is usable without docs, help should be easy to find, task-foc
 |-------|----------|
 | 0 | No help available anywhere |
 | 1 | Help exists but hard to find or irrelevant |
-| 2 | Basic help — FAQ or docs exist, not contextual |
-| 3 | Good documentation — searchable, mostly task-focused |
-| 4 | Excellent contextual help — right info at the right moment |
+| 2 | Basic help; FAQ or docs exist, not contextual |
+| 3 | Good documentation; searchable, mostly task-focused |
+| 4 | Excellent contextual help; right info at the right moment |
 
 ---
 
@@ -212,11 +212,11 @@ Even if the system is usable without docs, help should be easy to find, task-foc
 
 | Score Range | Rating | What It Means |
 |-------------|--------|---------------|
-| 36–40 | Excellent | Minor polish only — ship it |
+| 36–40 | Excellent | Minor polish only; ship it |
 | 28–35 | Good | Address weak areas, solid foundation |
 | 20–27 | Acceptable | Significant improvements needed before users are happy |
-| 12–19 | Poor | Major UX overhaul required — core experience broken |
-| 0–11 | Critical | Redesign needed — unusable in current state |
+| 12–19 | Poor | Major UX overhaul required; core experience broken |
+| 0–11 | Critical | Redesign needed; unusable in current state |
 
 ---
 
@@ -226,7 +226,7 @@ Tag each individual issue found during scoring with a priority level:
 
 | Priority | Name | Description | Action |
 |----------|------|-------------|--------|
-| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper |
+| **P0** | Blocking | Prevents task completion entirely | Fix immediately; this is a showstopper |
 | **P1** | Major | Causes significant difficulty or confusion | Fix before release |
 | **P2** | Minor | Annoyance, but workaround exists | Fix in next pass |
 | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits |

.agents/skills/impeccable/reference/interaction-design.md

@@ -42,11 +42,11 @@ button:focus-visible {
 
 ## Form Design: The Non-Obvious
 
-**Placeholders aren't labels**—they disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
+**Placeholders aren't labels.** They disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
 
 ## Loading States
 
-**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**—they preview content shape and feel faster than generic spinners.
+**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**: they preview content shape and feel faster than generic spinners.
 
 ## Modals: The Inert Approach
 
@@ -158,7 +158,7 @@ Check viewport boundaries before rendering. If the dropdown would overflow the b
 
 ## Destructive Actions: Undo > Confirm
 
-**Undo is better than confirmation dialogs**—users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
+**Undo is better than confirmation dialogs.** Users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
 
 ## Keyboard Navigation Patterns
 

.agents/skills/impeccable/reference/layout.md

@@ -1,10 +1,10 @@
-Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+Space is the most underused design tool. Find the layout's actual problem (monotone spacing, weak hierarchy, identical card grids, the centered-stack default) and fix the structure, not the surface.
 
 ---
 
 ## Register
 
-Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast — tight groupings paired with generous separations.
+Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast: tight groupings paired with generous separations.
 
 Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
 
@@ -20,8 +20,8 @@ Analyze what's weak about the current spatial design:
    - Are related elements grouped tightly, with generous space between groups?
 
 2. **Visual hierarchy**:
-   - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
-   - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+   - Apply the squint test: blur your (metaphorical) eyes. Can you still identify the most important element, second most important, and clear groupings?
+   - Is hierarchy achieved effectively? (Space and weight alone can be enough; is the current approach working?)
    - Does whitespace guide the eye to what matters?
 
 3. **Grid & structure**:
@@ -39,7 +39,7 @@ Analyze what's weak about the current spatial design:
    - Is the layout too sparse? (Excessive whitespace without purpose)
    - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
 
-**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material; use it with intention.
 
 ## Plan Layout Improvements
 
@@ -47,7 +47,7 @@ Consult the [spatial design reference](spatial-design.md) for detailed guidance
 
 Create a systematic plan:
 
-- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Spacing system**: Use a consistent scale (a framework's built-in scale like Tailwind's, rem-based tokens, or a custom system). The specific values matter less than consistency.
 - **Hierarchy strategy**: How will space communicate importance?
 - **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
 - **Rhythm**: Where should spacing be tight vs generous?
@@ -56,17 +56,17 @@ Create a systematic plan:
 
 ### Establish a Spacing System
 
-- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Use a consistent spacing scale (framework scales like Tailwind, rem-based tokens, or a custom scale all work). What matters is that values come from a defined set, not arbitrary numbers.
 - Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
-- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Use `gap` for sibling spacing instead of margins; eliminates margin collapse hacks
 - Apply `clamp()` for fluid spacing that breathes on larger screens
 
 ### Create Visual Rhythm
 
 - **Tight grouping** for related elements (8-12px between siblings)
 - **Generous separation** between distinct sections (48-96px)
-- **Varied spacing** within sections — not every row needs the same gap
-- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+- **Varied spacing** within sections (not every row needs the same gap)
+- **Asymmetric compositions**: break the predictable centered-content pattern when it makes sense
 
 ### Choose the Right Layout Tool
 
@@ -74,40 +74,40 @@ Create a systematic plan:
 - **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
 - **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
 - Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
-- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts; redefine at breakpoints.
 
 ### Break Card Grid Monotony
 
-- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
-- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Don't default to card grids for everything; spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable. Never nest cards inside cards
 - Vary card sizes, span columns, or mix cards with non-card content to break repetition
 
 ### Strengthen Visual Hierarchy
 
-- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
-- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough; generous whitespace around an element draws the eye. Some of the most polished designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow: in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
 - Create clear content groupings through proximity and separation.
 
 ### Manage Depth & Elevation
 
 - Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
-- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Build a consistent shadow scale (sm → md → lg → xl); shadows should be subtle
 - Use elevation to reinforce hierarchy, not as decoration
 
 ### Optical Adjustments
 
-- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+- If an icon looks visually off-center despite being geometrically centered, nudge it. But only if you're confident it actually looks wrong. Don't adjust speculatively.
 
 **NEVER**:
 - Use arbitrary spacing values outside your scale
-- Make all spacing equal — variety creates hierarchy
-- Wrap everything in cards — not everything needs a container
-- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Make all spacing equal (variety creates hierarchy)
+- Wrap everything in cards (not everything needs a container)
+- Nest cards inside cards (use spacing and dividers for hierarchy within)
 - Use identical card grids everywhere (icon + heading + text, repeated)
-- Center everything — left-aligned with asymmetry feels more designed
-- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
-- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
-- Use arbitrary z-index values (999, 9999) — build a semantic scale
+- Center everything (left-aligned with asymmetry feels more designed)
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work, but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler; use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999); build a semantic scale
 
 ## Verify Layout Improvements
 
@@ -118,11 +118,11 @@ Create a systematic plan:
 - **Consistency**: Is the spacing system applied uniformly?
 - **Responsiveness**: Does the layout adapt gracefully across screen sizes?
 
-Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
+When the rhythm and hierarchy land, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params
 
-Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * <base>)` — paddings, gaps, column widths. Users slide from airy to packed and see layout re-breathe with no regeneration.
+Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * <base>)`: paddings, gaps, column widths. Users slide from airy to packed and see layout re-breathe with no regeneration.
 
 ```json
 {"id":"density","kind":"range","min":0.6,"max":1.4,"step":0.05,"default":1,"label":"Density"}

.agents/skills/impeccable/reference/live.md

@@ -8,17 +8,18 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR
 
 Execute in order. No step skipped, no step reordered.
 
-1. `live.mjs` — boot.
-2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app.
+1. `live.mjs`: boot.
+2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL; it's the helper, not the app.
 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
-4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again.
-5. On `accept` / `discard` — the poll script already cleaned up; just poll again.
-6. On `exit` — run the cleanup at the bottom.
+4. On `generate`: read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again.
+5. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts remain recoverable until you finish cleanup, run `live-complete.mjs --id EVENT_ID`, and only then poll again.
+6. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
 - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell.
-- **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout.
-- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.
+- **Cursor**: run the poll in the **foreground** (blocking shell; not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout.
+- **Codex**: run the poll in the **foreground** (blocking shell; not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.
 - **Other harnesses**: foreground unless you know stdout reliably returns to this session.
 
 Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
@@ -29,7 +30,7 @@ Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodi
 node .agents/skills/impeccable/scripts/live.mjs
 ```
 
-Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath, migrated }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md and DESIGN.md in mind for variant generation — **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** If `migrated: true`, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md`; mention this once and suggest `$impeccable document` for the matching DESIGN.md.
+Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath, migrated }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md and DESIGN.md in mind for variant generation; **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure from existing identity requires an explicit trigger from PRODUCT.md anti-references or the user's freeform prompt. If `migrated: true`, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md`; mention this once and suggest `$impeccable document` for the matching DESIGN.md.
 
 `serverPort` and `serverToken` belong to the small **Impeccable live helper** HTTP server (serves `/live.js`, SSE, and `/poll`). That port is **not** your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the `pageFiles` entries (Vite / Next / Bun / tunnel / LAN hostname).
 
@@ -43,22 +44,40 @@ LOOP:
   Read JSON; dispatch on "type"
 
   "generate"  → Handle Generate; reply done; LOOP
-  "accept"    → Handle Accept; LOOP
+  "accept"    → Handle Accept; complete carbonize cleanup if required; LOOP
   "discard"   → Handle Discard; LOOP
   "prefetch"  → Handle Prefetch; LOOP
   "timeout"   → LOOP
   "exit"      → break → Cleanup
 ```
 
+## Recovery commands
+
+The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
+
+Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
+
+```bash
+node .agents/skills/impeccable/scripts/live-status.mjs
+node .agents/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
+node .agents/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
+```
+
+- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
+- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
+- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
+
+Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
+
 ## Handle `generate`
 
 Event: `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
 
-Speed matters — the user is watching a spinner. Minimize tool calls by using the `wrap` helper and writing all variants in a single edit.
+Speed matters; the user is watching a spinner. Minimize tool calls by using the `wrap` helper and writing all variants in a single edit.
 
 ### 1. Read the screenshot (if present)
 
-`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning** — annotations encode user intent not recoverable from `element.outerHTML` alone.
+`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
 
 When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
 
@@ -66,32 +85,42 @@ When `screenshotPath` is absent, don't ask for one and don't go looking for the
 
 Reading annotations precisely:
 
-- **Comment position is load-bearing.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
+- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
 - **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
-- **Strokes are gestures — read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
+- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
 - **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
 
 ### 2. Wrap the element
 
 ```bash
-node .agents/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div"
+node .agents/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
 ```
 
-Flag mapping — keep them separate, don't collapse into `--query`:
+Flag mapping. Keep them separate, don't collapse into `--query`:
 
 - `--element-id` ← `event.element.id`
 - `--classes` ← `event.element.classes` joined with commas
 - `--tag` ← `event.element.tagName`
+- `--text` ← first ~80 chars of `event.element.textContent` (trim, single-line). **Pass this every call.** When the picked element shares classes + tag with sibling components (a list of `<Card>`s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.
 
-The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only — do not use it for normal element lookups.
+The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only; do not use it for normal element lookups.
 
-Output on success: `{ file, insertLine, commentSyntax }`.
+If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing — accepting a variant into a generated file is silent data loss. Three shapes:
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
 
-- `{ error: "file_is_generated", file, hint }` — user-supplied `--file` points at a generated file.
-- `{ error: "element_not_in_source", generatedMatch, hint }` — element exists only in a generated file (the next build would wipe any edits).
-- `{ error: "element_not_found", hint }` — element isn't in any project file; likely runtime-injected (JS component, data-driven render).
+`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
+
+- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
+- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
+
+Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
+
+**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
+
+- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
+- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
+- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
 
 All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
 
@@ -101,68 +130,118 @@ If `event.action` is `impeccable` (the default freeform action), use SKILL.md's
 
 Any other `event.action` (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): Read `reference/<action>.md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
 
-### 4. Plan three genuinely distinct directions
+### 4. Plan three variants: identity first, then mode, then axes
 
-Before writing a single line of code, name each variant.
+The wrong frame for live mode is "show three different design directions." Live runs on an existing surface; the brand has already been chosen. The job is variation **within identity**, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.
 
-**For freeform (`action` is `impeccable`, or the user supplied a free prompt):** each variant must anchor to a different **archetype** — a real-world design analogue specific enough to be recognizable at a glance. Not "modern landing page." Not "minimal product hero." Examples:
+Four phases. Do them in order.
 
-- *Broadsheet masthead with rule-divided columns* (think NYT print edition)
-- *Klim Type Foundry specimen page* (dense, technical, catalog-driven)
-- *Japanese print-poster minimalism with a single oversize glyph*
-- *Bloomberg Terminal status bar*
-- *Condé Nast Traveler feature layout*
+#### Phase A: Extract the identity (non-skippable)
 
-Then commit each variant to a different **primary axis** of difference:
+The existing surface has an identity already. Read it before planning anything. Sources, in priority order:
 
-1. **Hierarchy** — which element commands the eye?
-2. **Layout topology** — stacked / side-by-side / grid / asymmetric / overlay
-3. **Typographic system** — pairing, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
-5. **Density** — minimal / comfortable / dense
-6. **Structural decomposition** — merge, split, progressive disclosure
+1. **DESIGN.md** if loaded: read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.
+2. **CSS custom properties** in the page's stylesheets (`:root { --color-...; --font-...; ... }`): these are de-facto tokens.
+3. **Computed styles** on the picked element and its parent: colors, fonts, spacing scales, corner radii.
+4. **Sibling components on the page**: what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)
 
-Three variants → three DIFFERENT primary axes, not three riffs on color.
+Write down what you see in **one sentence**. The sentence describes the surface that's actually on screen; it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:
 
-**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for one dark-neutral-accent, one light-drenched, one full-palette-saturated — three color worlds, not three shades of the same.
+- The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").
+- The type pairing: the actual font names loaded, primary first.
+- The layout topology: how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).
+- The surface treatment: corners, borders, shadows, density of decoration.
+- The voice tone you read off the copy itself, not off the aesthetic feel.
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.
 
-> V1: Broadsheet masthead, ruled columns, 24px ink on cream.
-> V2: Enormous italic title, catalog spec rows, heavy monospace data.
-> V3: Card-framed poster with one oversize glyph, magenta veil.
+Do not include adjectives that name an aesthetic family ("editorial-leaning", "terminal-flavored", "brutalist"); those are conclusions, not data. They belong to Phase C lane selection in departure mode, not to identity description. Letting them sneak into Phase A is how the identity-lock collapses into a self-fulfilling prophecy.
 
-If two of them rhyme ("both use big type" / "both are stacks of sections" / "both feature the CTA prominently"), rework the offender. Freeform variants failing the squint test is the primary failure mode of this flow — three-of-the-same with minor styling tweaks.
+This sentence is the **identity lock**. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse; extract from CSS and computed styles instead.
+
+#### Phase B: Pick mode (default vs departure)
+
+**Default mode**: the existing identity is preserved. Variants vary expression axes within it. *This is the right mode for ~90% of live sessions.* The user picked an element on a real product they're shipping; they expect variants of *their* hero, not three different brands' heroes.
+
+**Departure mode**: the existing identity is rejected. Variants propose alternatives consistent with PRODUCT.md voice. Trigger only when at least one is true:
+
+- PRODUCT.md anti-references explicitly call out the current surface ("the current `index.html` is itself an example"; "diffuse away from this"; "the page on screen is the failure"). Generic anti-references that describe what to avoid in general do **not** trigger departure mode; only ones that point at *this* surface specifically.
+- The user's freeform prompt explicitly asks for departure ("rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different").
+
+If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel": recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants": unrecoverable, the user is annoyed.
+
+#### Phase C: Plan three variants
+
+**Default mode.** Each variant commits to a different **primary axis** of difference, while preserving the identity sentence. The six axes:
+
+1. **Hierarchy**: which element commands the eye?
+2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
+3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
+4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
+5. **Density**: minimal / comfortable / dense
+6. **Structural decomposition**: merge, split, progressive disclosure
+
+Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
+
+**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
+
+**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from the brand's stated voice and register in PRODUCT.md. Do NOT pick from a fixed catalog of lane categories. The right three directions for this brand are not the same as the right three for another brand, and picking from a list is itself the training-data reflex (the model selects "Swiss-grid, Terminal, Industrial-signage" every time because those are the furthest-from-editorial items in any enumerated list).
+
+Instead, work from the brand:
+
+1. Read PRODUCT.md's Brand Personality words. What physical, spatial, or material experiences would embody those words if design were not involved? (A personality described as "specific, earned, unmistakable" evokes a hand-stamped letter, a numbered print, a watchmaker's loupe. A personality described as "restless, loud, unfiltered" evokes a concert poster, a spray-painted wall, a megaphone.)
+2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
+3. Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. If you find yourself reaching for "Swiss-grid" or "Terminal" or "Industrial-signage" by reflex, you are pattern-matching a catalog in your training data, not reading the brand. Start over from the personality words.
+4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
+5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
+
+#### Phase D: Squint test
+
+**Default mode squint.** Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident; rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.
+
+**Departure mode squint.** Two passes, family before sentence:
+
+1. **Family pass.** Label each variant with one design-family word of your own choosing (any concrete noun: *exhibition, storefront, cockpit, recipe-card, playbill, field-manual*). If any two variants share a label, or if the label could apply to the other variants equally well, rework. Do not use a fixed vocabulary list for the labels. *This pass is non-negotiable in departure mode and catches the monoculture failure that the sentence pass misses.*
+2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
+
+**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
 
 **For action-specific invocations**, each variant must vary along the dimension the action names:
 
-- `bolder` — amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
-- `quieter` — pull back a different dimension (color / ornament / spacing).
-- `distill` — remove a different class of excess (visual noise / redundant content / nested structure).
-- `polish` — target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
-- `typeset` — different type pairing AND different scale ratio each. Not three riffs on one pairing.
-- `colorize` — different hue family each (not shades of one hue). Vary chroma and contrast strategy.
-- `layout` — different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
-- `adapt` — different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
-- `animate` — different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
-- `delight` — different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
-- `overdrive` — different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step — live mode is non-interactive.
+- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
+- `quieter`: pull back a different dimension (color / ornament / spacing).
+- `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
+- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
+- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
+- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
+- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
+- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
+- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
+- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
+- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
 
 ### 5. Apply the freeform prompt (if present)
 
-`event.freeformPrompt` is the user's ceiling on direction — all variants must honor it — but still explore meaningfully different *interpretations*. "Make it feel like a newspaper front page" → variant 1 = broadsheet masthead + rule-divided columns, variant 2 = tabloid headline + single dominant image, variant 3 = minimalist editorial with oversized drop cap. Not three newspapers in the same voice.
+`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. The interpretations stay within whichever mode you picked in Phase B.
+
+In **default mode**, the prompt narrows the axes you choose, not the identity. *"Make it feel more confident"* → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.
+
+In **departure mode**, the prompt narrows the lanes you draw from, not the families. *"Make it feel like a newspaper front page"* would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.
+
+When the prompt and PRODUCT.md anti-references conflict (the prompt asks for X, the anti-references ban X), the anti-references win; they describe the brand's standing position, the prompt is one moment.
 
 ### 6. Write all variants in a single edit
 
 Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
 
-Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate scoped CSS as a `<style>` tag inside the variant wrapper — `<style>` works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).
+Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).
+
+Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
 
 ```html
 <!-- Variants: insert below this line -->
 <style data-impeccable-css="SESSION_ID">
-  @scope ([data-impeccable-variant="1"]) { ... }
-  @scope ([data-impeccable-variant="2"]) { ... }
+  /* rules matching cssAuthoring.rulePattern */
 </style>
 <div data-impeccable-variant="1">
   <!-- variant 1: full element replacement (single top-level element) -->
@@ -175,11 +254,30 @@ Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Col
 </div>
 ```
 
-**Each variant div contains exactly one top-level element — the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
+**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
 
-The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no scoped CSS, omit the `<style>` tag entirely. Use `@scope` for CSS isolation (Chrome 118+ / Firefox 128+ / Safari 17.4+).
+The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
 
-One edit, all variants — the browser's MutationObserver picks everything up in one pass.
+One edit, all variants; the browser's MutationObserver picks everything up in one pass.
+
+For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
+
+**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
+
+```tsx
+<style data-impeccable-css="SESSION_ID">{`
+  @scope ([data-impeccable-variant="1"]) { ... }
+  @scope ([data-impeccable-variant="2"]) { ... }
+`}</style>
+<div data-impeccable-variant="1">
+  {/* variant 1 */}
+</div>
+<div data-impeccable-variant="2" style={{ display: 'none' }}>
+  {/* variant 2 */}
+</div>
+```
+
+The wrap script already gives you a single-rooted JSX wrapper: a `<div data-impeccable-variants="…">` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
 
 ### 7. Parameters (composition-sized, 0–4 per variant)
 
@@ -189,18 +287,18 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
 
-**Freeform (`action` is `impeccable`) bias.** You did not load `reference/bolder.md` (etc.), so you must **choose** 1–2 signature-like axes yourself. Prefer knobs that sit on the same dimensions as your three directions (e.g. all three riffs on editorial density → expose `density` or a `steps` “air / snug / packed”; two directions differ mostly in chroma → add `color-amount`). A hero, section, or other **large** surface that ships with **0** params needs a one-line reason in your head (e.g. “truly a fixed-point A/B/C comparison, no shared dial”), not a default habit.
+**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
 
 **Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
 
-- **Leaf / tiny** — a single button, icon, input, bare heading, solitary paragraph: **0 params.**
-- **Small composition** — labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
-- **Medium composition** — section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
-- **Large composition** — hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
+- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
+- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
+- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
+- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
 
 **When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
 
-**Hard cap per variant** — at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
+**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
 
 **How to declare.** Put a JSON manifest on the variant wrapper:
 
@@ -220,9 +318,9 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **Three kinds:**
 
-- `range` — smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
-- `steps` — segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
-- `toggle` — on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
+- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
+- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
+- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
 
 **Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
 
@@ -242,10 +340,20 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
 node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
 ```
 
-`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.) — the browser fetches source directly if the dev server lacks HMR.
+`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
 
 Then run `live-poll.mjs` again immediately.
 
+### Aborting an in-flight session
+
+If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
+
+```bash
+node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
+```
+
+Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
+
 ## Handle fallback
 
 When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
@@ -256,9 +364,9 @@ The goal is the same: give the user three variants to choose from AND persist th
 
 Use the error payload:
 
-- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"` — the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
-- `element_not_found` — the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
-- `file_is_generated` with `file: "..."` — user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
+- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
+- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
+- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
 
 Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
 
@@ -266,19 +374,19 @@ Read the candidate source until you're confident where a change to the element w
 
 The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
 
-1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces — `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
+1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
 2. Insert your three variant divs inside it, same shape as the deterministic path.
 3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
 
-This served-file edit is **temporary** — next regen wipes it, and that's fine. The real work happens on accept.
+This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
 
 ### Step 3: On accept, write to true source
 
-When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files — see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
+When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
 
 - Structural change → edit the template / component source.
 - Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
-- Data-driven → update the data source or the render logic.
+- Dynamic from data → update the data source or the render logic.
 
 Then remove the temporary wrapper from the served file if it's still there.
 
@@ -288,45 +396,46 @@ Remove the wrapper you inserted in Step 2. Nothing else to do.
 
 ## Handle `accept`
 
-Event: `{id, variantId, _acceptResult}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically; the browser DOM is already updated.
+Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
 
-- `_acceptResult.handled: true` and `carbonize: false` — nothing to do. Poll again.
-- `_acceptResult.handled: true` and `carbonize: true` — **post-accept cleanup is required before the next poll.** See the "Required after accept (carbonize)" section below. The `event._acceptResult.todo` field and a stderr banner both list the steps explicitly; neither is decorative.
-- `_acceptResult.handled: false, mode: "fallback"` — the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
-- `_acceptResult.handled: false` without `mode` — manual cleanup: read file, find markers, edit.
+- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
+- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
+- `_acceptResult.handled: true` and `carbonize: true`: **post-accept cleanup is required before the next poll.** See the "Required after accept (carbonize)" section below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and a stderr banner all point at this required follow-up; none are decorative. After cleanup, run `live-complete.mjs --id EVENT_ID`, then poll again.
+- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
+- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
 
 ### Required after accept (carbonize)
 
-When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file — all of which accumulate across sessions.
+When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
 
 Do these five steps in the current thread, synchronously, before the next poll. Do not poll again until the file is clean.
 
-1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values — read it first; it drives steps 3 and 4 below.
-2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `public/css/workflow.css` for this repo, or the component's co-located CSS file for a Vite/Next project — pick whichever already owns styling for the surrounding element).
+1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
+2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
 3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it — those are live-mode plumbing, not source.
-5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one — those are dead code now.
+4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it; those are live-mode plumbing, not source.
+5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
 
-Then poll again.
+After the file is clean, run `live-complete.mjs --id SESSION_ID`, verify it reports `phase: "completed"`, then poll again.
 
 A background agent may be used for the rewrite, but the current thread is responsible for verifying the five steps are complete before issuing the next poll. In practice, inline is usually faster and less error-prone.
 
 ## Handle `discard`
 
-Event: `{id, _acceptResult}`. The poll script already restored the original and removed all variant markers. Nothing to do. Poll again.
+Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
 
 ## Handle `prefetch`
 
-Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut — it signals the user is likely about to Go on a page you haven't read yet.
+Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
 
 Resolve `pageUrl` to the underlying file:
 
 - Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
 - Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
 
-Read the file into context, then poll again. No `--reply` — this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
+Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
 
-Dedupe is the browser's job (one prefetch per unique pathname per session) — trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
+Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
 
 ## Exit
 
@@ -343,7 +452,7 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
 node .agents/skills/impeccable/scripts/live-server.mjs stop
 ```
 
-Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `config.json` persists for future sessions.
+Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
 
 Then:
 - Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
@@ -351,7 +460,7 @@ Then:
 
 ## First-time setup (config missing or invalid)
 
-If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write `config.json` at the reported path.
+If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
 
 Schema:
 
@@ -365,7 +474,7 @@ Schema:
 }
 ```
 
-`files` is the inject target — **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
+`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
 
 `exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
 
@@ -383,13 +492,13 @@ Schema:
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
-| Multi-page (separate HTML per route) | `["public/**/*.html"]` — a glob covering the served directory | `</body>` | `html` |
+| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
-For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected — it writes to true source via the fallback flow.
+For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
 
 ### Drift-heal warning
 
@@ -417,7 +526,7 @@ When `configDrift` is present, surface it to the user once per session before en
 >
 > Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
 
-Don't auto-update the config — let the user decide. `configDrift` is `null` when there's no drift.
+Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
 
 ### CSP detection (first-time only)
 
@@ -431,21 +540,21 @@ node .agents/skills/impeccable/scripts/detect-csp.mjs
 
 Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
 
-- **`null`** — no CSP; skip to writing `config.json` with `cspChecked: true`.
-- **`append-arrays`** — CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
+- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
+- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
   - Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
   - SvelteKit `kit.csp.directives`
   - Nuxt `nuxt-security` module's `contentSecurityPolicy`
-- **`append-string`** — CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
+- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
   - Inline `next.config.*` `headers()` with a CSP literal
   - Nuxt `routeRules` / `nitro.routeRules` headers
-- **`middleware`** or **`meta-tag`** — rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
+- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
 
 #### Consent prompt template
 
 Use this phrasing so the experience is consistent across agents:
 
-> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400` — the live picker won't load without an allowance. Here's the change I'd make:
+> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
 >
 > ```diff
 > [file: <patchTarget>]
@@ -472,9 +581,9 @@ const __impeccableLiveDev =
 
 **Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
 
-- **Next.js + monorepo helper** — edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
-- **SvelteKit** — edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
-- **Nuxt + nuxt-security** — edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
+- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
+- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
+- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
 
 Reference outputs:
 - `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
@@ -499,8 +608,8 @@ Then in the CSP value string:
 (Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
 
 Per-framework specifics:
-- **Next.js inline `headers()`** — edit `next.config.*`, splicing the variable into the CSP value.
-- **Nuxt `routeRules`** — edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
+- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
+- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
 
 Reference outputs:
 - `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
@@ -508,6 +617,6 @@ Reference outputs:
 
 ### Troubleshooting
 
-If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `config.json` and re-run `live.mjs` — setup will ask again.
+If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
 
 Then re-run `live.mjs`.

.agents/skills/impeccable/reference/motion-design.md

@@ -11,7 +11,7 @@ Timing matters more than easing. These durations feel right for most UI:
 | **300-500ms** | Layout changes | Accordion, modal, drawer |
 | **500-800ms** | Entrance animations | Page load, hero reveals |
 
-**Exit animations are faster than entrances**—use ~75% of enter duration.
+**Exit animations are faster than entrances.** Use ~75% of enter duration.
 
 ## Easing: Pick the Right Curve
 
@@ -23,7 +23,7 @@ Timing matters more than easing. These durations feel right for most UI:
 | **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
 | **ease-in-out** | State toggles (there → back) | `cubic-bezier(0.65, 0, 0.35, 1)` |
 
-**For micro-interactions, use exponential curves**—they feel natural because they mimic real physics (friction, deceleration):
+**For micro-interactions, use exponential curves.** They feel natural because they mimic real physics (friction, deceleration):
 
 ```css
 /* Quart out - smooth, refined (recommended default) */
@@ -36,7 +36,7 @@ Timing matters more than easing. These durations feel right for most UI:
 --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
 ```
 
-**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop—they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.
+**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop; they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.
 
 ## Premium Motion Materials
 
@@ -54,7 +54,7 @@ The hard rule is not "transform and opacity only." The hard rule is: avoid anima
 
 ## Staggered Animations
 
-Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time**—10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
+Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time**: 10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
 
 ## Reduced Motion
 
@@ -82,19 +82,19 @@ This is not optional. Vestibular disorders affect ~35% of adults over 40.
 }
 ```
 
-**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work—just without spatial movement.
+**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work, just without spatial movement.
 
 ## Perceived Performance
 
-**Nobody cares how fast your site is—just how fast it feels.** Perception can be as effective as actual performance.
+**Nobody cares how fast your site is, just how fast it feels.** Perception can be as effective as actual performance.
 
 **The 80ms threshold**: Our brains buffer sensory input for ~80ms to synchronize perception. Anything under 80ms feels instant and simultaneous. This is your target for micro-interactions.
 
 **Active vs passive time**: Passive waiting (staring at a spinner) feels longer than active engagement. Strategies to shift the balance:
 
 - **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
-- **Early completion**: Show content progressively—don't wait for everything. Video buffering, progressive images, streaming HTML.
-- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Instagram likes work offline—the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.
+- **Early completion**: Show content progressively, don't wait for everything. Video buffering, progressive images, streaming HTML.
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Instagram likes work offline; the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.
 
 **Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances, but ease-in toward a task's end compresses perceived time.
 
@@ -102,7 +102,7 @@ This is not optional. Vestibular disorders affect ~35% of adults over 40.
 
 ## Performance
 
-Don't use `will-change` preemptively—only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
+Don't use `will-change` preemptively, only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
 
 ---
 

.agents/skills/impeccable/reference/onboard.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: the "aha moment" you want users to reach, and users' experience level.
 
-Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
+Get users to first value as fast as possible. Onboarding's job is not to teach the product. Its job is to get people to the moment that proves the product is worth their time.
 
 ## Assess Onboarding Needs
 
@@ -231,4 +231,4 @@ Test with real users:
 - **Completion rate**: Are users completing? (If low, simplify)
 - **Time to value**: How long until users get first value?
 
-Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.
+When users hit the aha moment fast and don't drop off, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/optimize.md

@@ -1,4 +1,4 @@
-Identify and fix performance issues to create faster, smoother user experiences.
+Performance is a feature. Identify the actual bottleneck for THIS interface, fix it, then measure. Don't optimize what isn't slow.
 
 ## Assess Performance Issues
 
@@ -255,4 +255,4 @@ Test that optimizations worked:
 - **No regressions**: Ensure functionality still works
 - **User perception**: Does it *feel* faster?
 
-Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
+When the user-facing numbers move, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/overdrive.md

@@ -30,16 +30,16 @@ Technically ambitious effects almost never work on the first try. You MUST activ
 The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
 
 ### For visual/marketing surfaces
-Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
+Pages, hero sections, landing pages, portfolios: the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
 
 ### For functional UI
-Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
+Tables, forms, dialogs, navigation: the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
 
 ### For performance-critical UI
 The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
 
 ### For data-heavy interfaces
-Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
+Charts and dashboards: the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
 
 **The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
 
@@ -48,36 +48,36 @@ Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering vi
 Organized by what you're trying to achieve, not by technology name.
 
 ### Make transitions feel cinematic
-- **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
-- **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes
-- **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
+- **View Transitions API** (same-document: all browsers; cross-document: no Firefox): shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
+- **`@starting-style`** (all browsers): animate elements from `display: none` to visible with CSS only, including entry keyframes
+- **Spring physics**: natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
 
 ### Tie animation to scroll position
-- **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)
+- **Scroll-driven animations** (`animation-timeline: scroll()`): CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only; always provide a static fallback)
 
 ### Render beyond CSS
-- **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
-- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
-- **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
-- **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
+- **WebGL** (all browsers): shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
+- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only): next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
+- **Canvas 2D / OffscreenCanvas**: custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
+- **SVG filter chains**: displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
 
 ### Make data feel alive
-- **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
-- **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
-- **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
+- **Virtual scrolling**: render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
+- **GPU-accelerated charts**: Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
+- **Animated data transitions**: morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
 
 ### Animate complex properties
-- **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
-- **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
+- **`@property`** (all browsers): register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
+- **Web Animations API** (all browsers): JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
 
 ### Push performance boundaries
-- **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
-- **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background.
-- **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
+- **Web Workers**: move computation off the main thread. Heavy data processing, image manipulation, search indexing: anything that would cause jank.
+- **OffscreenCanvas**: render in a Worker thread. The main thread stays free while complex visuals render in the background.
+- **WASM**: near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
 
 ### Interact with the device
-- **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
-- **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
+- **Web Audio API**: spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
+- **Device APIs**: orientation, ambient light, geolocation. Use sparingly and always with user permission.
 
 **NOTE**: This command is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
 
@@ -102,22 +102,22 @@ else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
 ### Performance rules
 
 - Target 60fps. If dropping below 50, simplify.
-- Respect `prefers-reduced-motion` — always. Provide a beautiful static alternative.
+- Respect `prefers-reduced-motion`, always. Provide a beautiful static alternative.
 - Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
 - Pause off-screen rendering. Kill what you can't see.
 - Test on real mid-range devices, not just your development machine.
 
 ### Polish is the difference
 
-The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.
+The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works; ship the version that feels inevitable.
 
 **NEVER**:
-- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion
+- Ignore `prefers-reduced-motion`. This is an accessibility requirement, not a suggestion
 - Ship effects that cause jank on mid-range devices
 - Use bleeding-edge APIs without a functional fallback
 - Add sound without explicit user opt-in
 - Use technical ambition to mask weak design fundamentals; fix those first with other commands
-- Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
+- Layer multiple competing extraordinary moments. Focus creates impact, excess creates noise
 
 ## Verify the Result
 
@@ -127,4 +127,4 @@ The gap between "cool" and "extraordinary" is in the last 20% of refinement: the
 - **The accessibility test**: Enable reduced motion. Still beautiful?
 - **The context test**: Does this make sense for THIS brand and audience?
 
-Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.
+"Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

.agents/skills/impeccable/reference/personas.md

@@ -2,11 +2,12 @@
 
 Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss.
 
-**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns.
+**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags, not generic concerns.
 
 ---
 
-## 1. Impatient Power User — "Alex"
+## 1. Impatient Power User: "Alex"
+
 
 **Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave.
 
@@ -33,7 +34,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 2. Confused First-Timer — "Jordan"
+## 2. Confused First-Timer: "Jordan"
 
 **Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out.
 
@@ -60,7 +61,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 3. Accessibility-Dependent User — "Sam"
+## 3. Accessibility-Dependent User: "Sam"
 
 **Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences.
 
@@ -88,7 +89,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 4. Deliberate Stress Tester — "Riley"
+## 4. Deliberate Stress Tester: "Riley"
 
 **Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience.
 
@@ -115,12 +116,12 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 5. Distracted Mobile User — "Casey"
+## 5. Distracted Mobile User: "Casey"
 
 **Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection.
 
 **Behaviors**:
-- Uses thumb only — prefers bottom-of-screen actions
+- Uses thumb only; prefers bottom-of-screen actions
 - Gets interrupted mid-flow and returns later
 - Switches between apps frequently
 - Has limited attention span and low patience
@@ -130,12 +131,12 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 - Are primary actions in the thumb zone (bottom half of screen)?
 - Is state preserved if the user leaves and returns?
 - Does it work on slow connections (3G)?
-- Can forms leverage autocomplete and smart defaults?
+- Can forms use autocomplete and smart defaults?
 - Are touch targets at least 44×44pt?
 
 **Red Flags** (report these specifically):
 - Important actions positioned at the top of the screen (unreachable by thumb)
-- No state persistence — progress lost on tab switch or interruption
+- No state persistence; progress lost on tab switch or interruption
 - Large text inputs required where selection would work
 - Heavy assets loading on every page (no lazy loading)
 - Tiny tap targets or targets too close together
@@ -166,7 +167,7 @@ If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable
 3. Create a persona following this template:
 
 ```
-### [Role] — "[Name]"
+### [Role]: "[Name]"
 
 **Profile**: [2-3 key characteristics derived from Design Context]
 
@@ -175,4 +176,4 @@ If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable
 **Red Flags**: [3-4 things that would alienate this specific user type]
 ```
 
-Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists.
+Only generate project-specific personas when real Design Context data is available. Don't invent audience details; use the 5 predefined personas when no context exists.

.agents/skills/impeccable/reference/polish.md

@@ -2,15 +2,17 @@
 
 Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
 
+Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path.
+
 ## Design System Discovery
 
 Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work.
 
 1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: design principles, target audience, color tokens, spacing scale, typography styles, component API, motion conventions.
 2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established? What flow shapes are used for comparable actions (modal vs full-page, inline vs route, save-on-blur vs explicit submit)?
-3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category — patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
+3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category: patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
 
-If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask — never guess at design system principles.**
+If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask. Never guess at design system principles.**
 
 ## Pre-Polish Assessment
 
@@ -22,7 +24,7 @@ Understand the current state and goals before touching anything:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish — a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
+2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish; a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
 
 3. **Identify polish areas**:
    - Visual inconsistencies
@@ -33,7 +35,14 @@ Understand the current state and goals before touching anything:
    - Loading and transition smoothness
    - Information architecture and flow drift (does this feature reveal complexity the way neighboring features do?)
 
-4. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent — never perfect one corner while leaving another rough.
+4. **Pull in any prior critique** (optional signal): If `$impeccable critique` has been run on the same target, its priority issues are a useful prior for what to address first. Resolve the target to a file path or URL, then:
+   ```bash
+   slug=$(node .agents/skills/impeccable/scripts/critique-storage.mjs slug "<resolved>")
+   node .agents/skills/impeccable/scripts/critique-storage.mjs latest "$slug"
+   ```
+   Exit 0 with body = found; fold the P0/P1 items into your polish list and mention the snapshot path so the user sees what you read. Exit 2 = no snapshot, continue without it. The critique is one input among many. Do your own pass either way.
+
+5. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent; never perfect one corner while leaving another rough.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -60,7 +69,7 @@ Work through these dimensions methodically:
 Visual polish on a misshapen flow is wasted work. Match the *shape* of the experience to the system, not just the surface.
 
 - **Progressive disclosure**: Match how much is revealed when, compared to neighboring features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift, even if every field is perfectly styled.
-- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere — modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
+- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere: modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
 - **Hierarchy & complexity**: The same conceptual weight gets the same visual weight throughout. Primary actions don't become tertiary in one corner of the product, and tertiary actions don't shout.
 - **Empty, loading, and arrival transitions**: How content arrives, updates, and leaves matches how it does in adjacent features.
 - **Naming and mental model**: The feature uses the same nouns and verbs as the rest of the system. A "Workspace" here shouldn't be a "Project" three screens away.
@@ -82,8 +91,8 @@ Visual polish on a misshapen flow is wasted work. Match the *shape* of the exper
 - **Theme consistency**: Works in all theme variants
 - **Color meaning**: Same colors mean same things throughout
 - **Accessible focus**: Focus indicators visible with sufficient contrast
-- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)
-- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency
+- **Tinted neutrals**: No pure gray or pure black; add subtle color tint (0.01 chroma)
+- **Gray on color**: Never put gray text on colored backgrounds; use a shade of that color or transparency
 
 ### Interaction States
 
@@ -103,7 +112,7 @@ Every interactive element needs all states:
 ### Micro-interactions & Transitions
 
 - **Smooth transitions**: All state changes animated appropriately (150-300ms)
-- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
+- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic; they feel dated.
 - **No jank**: Smooth animations; use atmospheric blur/filter/mask/shadow effects when they add polish, but bound expensive paint areas and avoid casual layout-property animation
 - **Appropriate motion**: Motion serves purpose, not decoration
 - **Reduced motion**: Respects `prefers-reduced-motion`
@@ -198,9 +207,11 @@ Go through systematically:
 
 **IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
 
+Sweat the details. Zoom in until the alignment is right and the spacing reads as deliberate. Then ship.
+
 **NEVER**:
 - Polish before it's functionally complete
-- Polish without aligning to the design system — that's decoration on drift
+- Polish without aligning to the design system; that's decoration on drift
 - Guess at design system principles instead of asking when something is ambiguous
 - Spend hours on polish if it ships in 30 minutes (triage)
 - Introduce bugs while polishing (test thoroughly)
@@ -214,11 +225,12 @@ Go through systematically:
 
 Before marking as done:
 
-- **Use it yourself**: Actually interact with the feature
-- **Test on real devices**: Not just browser DevTools
-- **Ask someone else to review**: Fresh eyes catch things
-- **Compare to design**: Match intended design
-- **Check all states**: Don't just test happy path
+- **Use it yourself**: Actually interact with the feature.
+- **Test on real devices**: Not just browser DevTools.
+- **Ask someone else to review**: Fresh eyes catch things.
+- **Compare to design**: Match intended design.
+- **Check all states**: Don't just test happy path.
+- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished.
 
 ## Clean Up
 
@@ -228,5 +240,3 @@ After polishing, ensure code quality:
 - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.
 - **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
 - **Verify DRYness**: Look for duplication introduced during polishing and consolidate.
-
-Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.

.agents/skills/impeccable/reference/product.md

@@ -4,7 +4,7 @@ When design SERVES the product: app UIs, admin dashboards, settings panels, data
 
 ## The product slop test
 
-Not "would someone say AI made this" — familiarity is often a feature here. The test is: would a user fluent in the category's best tools (Linear, Figma, Notion, Raycast, Stripe come to mind) sit down and trust this interface, or pause at every subtly-off component?
+Not "would someone say AI made this." Familiarity is often a feature here. The test is: would a user fluent in the category's best tools (Linear, Figma, Notion, Raycast, Stripe come to mind) sit down and trust this interface, or pause at every subtly-off component?
 
 Product UI's failure mode isn't flatness, it's strangeness without purpose: over-decorated buttons, mismatched form controls, gratuitous motion, display fonts where labels should be, invented affordances for standard tasks. The bar is earned familiarity. The tool should disappear into the task.
 
@@ -14,19 +14,19 @@ Product UI's failure mode isn't flatness, it's strangeness without purpose: over
 - **One family is often right.** Product UIs don't need display/body pairing. A well-tuned sans carries headings, buttons, labels, body, data.
 - **Fixed rem scale, not fluid.** Clamp-sized headings don't serve product UI. Users view at consistent DPI, and a fluid h1 that shrinks in a sidebar looks worse, not better.
 - **Tighter scale ratio.** 1.125–1.2 between steps is typical. More type elements here than on brand surfaces; exaggerated contrast creates noise.
-- **Line length still applies for prose** (65–75ch). Data and compact UI can run denser — tables at 120ch+ are fine.
+- **Line length still applies for prose** (65–75ch). Data and compact UI can run denser; tables at 120ch+ are fine.
 
 ## Color
 
-Product defaults to Restrained. A single surface can earn Committed — a dashboard where one category color carries a report, an onboarding flow with a drenched welcome screen — but Restrained is the floor.
+Product defaults to Restrained. A single surface can earn Committed (a dashboard where one category color carries a report, an onboarding flow with a drenched welcome screen), but Restrained is the floor.
 
 - State-rich semantic vocabulary: hover, focus, active, disabled, selected, loading, error, warning, success, info. Standardize these.
-- Accent color used for primary actions, current selection, and state indicators only — not decoration.
+- Accent color used for primary actions, current selection, and state indicators only, not decoration.
 - A second neutral layer for sidebars, toolbars, and panels (slightly cooler or warmer than the content surface).
 
 ## Layout
 
-- Predictable grids. Consistency IS an affordance — users navigate faster when the structure is expected.
+- Predictable grids. Consistency IS an affordance; users navigate faster when the structure is expected.
 - Familiar patterns are features. Standard navigation (top bar, side nav), breadcrumbs, tabs, and form layouts have established user expectations. Don't reinvent for flavor.
 - Responsive behavior is structural (collapse sidebar, responsive table, breakpoint-driven columns), not fluid typography.
 
@@ -40,8 +40,8 @@ Every interactive component has: default, hover, focus, active, disabled, loadin
 
 ## Motion
 
-- 150–250 ms on most transitions. Users are in flow — don't make them wait for choreography.
-- Motion conveys state, not decoration. State change, feedback, loading, reveal — nothing else.
+- 150–250 ms on most transitions. Users are in flow; don't make them wait for choreography.
+- Motion conveys state, not decoration. State change, feedback, loading, reveal: nothing else.
 - No orchestrated page-load sequences. Product loads into a task; users don't want to watch it load.
 
 ## Product bans (on top of the shared absolute bans)

.agents/skills/impeccable/reference/quieter.md

@@ -1,12 +1,12 @@
-Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
+Quiet design is harder than bold design. Subtlety needs precision. Reduce visual intensity in designs that are too loud, aggressive, or overstimulating without losing personality or making the result generic.
 
 ---
 
 ## Register
 
-Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated — the POV stays intact.
+Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the POV stays intact.
 
-Product: "quieter" means reducing visual noise — fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
+Product: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
 
 ---
 
@@ -30,18 +30,18 @@ Analyze what makes the design feel too intense:
 
 If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
 
-**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
+**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness.
 
 ## Plan Refinement
 
 Create a strategy to reduce intensity while maintaining impact:
 
-- **Color approach**: Desaturate or shift to more sophisticated tones?
+- **Color approach**: Desaturate or shift to more restrained tones?
 - **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
 - **Simplification approach**: What can be removed entirely?
 - **Sophistication approach**: How can we signal quality through restraint?
 
-**IMPORTANT**: Great quiet design is harder than great bold design. Subtlety requires precision.
+**IMPORTANT**: Subtlety requires precision. Quiet without intent collapses to generic.
 
 ## Refine the Design
 
@@ -49,11 +49,11 @@ Systematically reduce intensity across these dimensions:
 
 ### Color Refinement
 - **Reduce saturation**: Shift from fully saturated to 70-85% saturation
-- **Soften palette**: Replace bright colors with muted, sophisticated tones
+- **Soften palette**: Replace bright colors with muted tones
 - **Reduce color variety**: Use fewer colors more thoughtfully
 - **Neutral dominance**: Let neutrals do more work, use color as accent (10% rule)
 - **Gentler contrasts**: High contrast only where it matters most
-- **Tinted grays**: Use warm or cool tinted grays instead of pure gray—adds sophistication without loudness
+- **Tinted grays**: Use warm or cool tinted grays instead of pure gray. Adds depth without loudness
 - **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead
 
 ### Visual Weight Reduction
@@ -72,7 +72,7 @@ Systematically reduce intensity across these dimensions:
 - **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing
 - **Remove decorative animations**: Keep functional motion, remove flourishes
 - **Subtle micro-interactions**: Replace dramatic effects with gentle feedback
-- **Refined easing**: Use ease-out-quart for smooth, understated motion—never bounce or elastic
+- **Refined easing**: Use ease-out-quart for smooth, understated motion. Never bounce or elastic
 - **Remove animations entirely** if they're not serving a clear purpose
 
 ### Composition Refinement
@@ -94,6 +94,6 @@ Ensure refinement maintains quality:
 - **Still functional**: Can users still accomplish tasks easily?
 - **Still distinctive**: Does it have character, or is it generic now?
 - **Better reading**: Is text easier to read for extended periods?
-- **Sophistication**: Does it feel more refined and premium?
+- **Restrained, not absent**: Does the POV survive the cuts?
 
-Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.
+When the result feels right, hand off to `$impeccable polish` for the final pass.

.agents/skills/impeccable/reference/responsive-design.md

@@ -6,11 +6,11 @@ Start with base styles for mobile, use `min-width` queries to layer complexity.
 
 ## Breakpoints: Content-Driven
 
-Don't chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
+Don't chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
 
 ## Detect Input Method, Not Just Screen Size
 
-**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries:
+**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:
 
 ```css
 /* Fine pointer (mouse, trackpad) */
@@ -95,7 +95,7 @@ When you need different crops/compositions (not just resolutions):
 
 ## Layout Adaptation Patterns
 
-**Navigation**: Three stages—hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
+**Navigation**: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
 
 ## Testing: Don't Trust DevTools Alone
 

.agents/skills/impeccable/reference/shape.md

@@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co
 
 ### Interview cadence
 
-Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
+Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
 
 - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
 - Ask **2-3 questions per round**, then wait for answers.
 - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific.
-- Round 1 should clarify purpose, audience/context, and success or emotional outcome.
-- Round 2 should clarify content/data/states and scope/fidelity.
-- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved.
+- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough.
+- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction.
+- Round 2, when needed, fills in whatever's still genuinely missing.
+
+**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -36,14 +38,15 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.
 - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
 - What are the edge cases? (Empty state, error state, first-time use, power user)
 - Is any content dynamic? What changes and how often?
+- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets.
 
 ### Design Direction
 
 Force a visual decision on three fronts. Skip anything PRODUCT.md or DESIGN.md already answers; ask only what's missing.
 
 - **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
-- **Theme via scene sentence.** Write one sentence of physical context for this surface — who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
-- **Two or three named anchor references.** Specific products, brands, objects — not adjectives like "modern" or "clean."
+- **Theme via scene sentence.** Write one sentence of physical context for this surface: who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
+- **Two or three named anchor references.** Specific products, brands, objects. Not adjectives like "modern" or "clean."
 
 ### Scope
 
@@ -54,7 +57,7 @@ Always ask. Sketch quality and shipped quality are different outputs; don't gues
 - **Interactivity.** Static visual / interactive prototype / shipped-quality component?
 - **Time intent.** Quick exploration, or polish until it ships?
 
-Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — carry them through the design brief only.
+Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md; carry them through the design brief only.
 
 ### Constraints
 - Are there technical constraints? (Framework, performance budget, browser support)
@@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes *
 
 - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
 - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
-- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling.
 
-When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+When those conditions are met, this step is mandatory. If image generation isn't natively available, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. The one-line announcement is required, not optional; it forces a conscious decision instead of letting the step quietly evaporate.
 
 Use probes to explore visual lanes, not to replace the brief.
 
@@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi
 - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
 - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
 
-If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief.
+If image generation isn't natively available, announce the skip in one line and proceed to the design brief.
 
 ## Phase 2: Design Brief
 
-After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief.
+After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate.
+
+**Choose the brief shape based on how clear the answers are:**
+
+- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt.
+- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight.
+
+Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point.
+
+Present the brief, then **stop and wait for explicit confirmation**. You are not the judge of whether the user already approved. Even when the brief feels obviously right, ask once and wait. The pause is what separates shape from premature implementation.
 
 ### Brief Structure
 
@@ -124,7 +136,7 @@ Color strategy (Restrained / Committed / Full palette / Drenched) + the theme sc
 If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
 
 **4. Scope**
-Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief.
+Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped; these don't persist beyond the brief.
 
 **5. Layout Strategy**
 High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
@@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg
 How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
 
 **8. Content Requirements**
-What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges.
+What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission).
 
 **9. Recommended References**
 Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features).
 
 **10. Open Questions**
-Anything unresolved that the implementer should resolve during build.
+Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X.
 
 ---
 
-STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed.
+STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing.
+
+If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction.
 
 Once confirmed, the brief is complete. The user can now hand it to $impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use $impeccable craft instead, which runs this command internally.)

.agents/skills/impeccable/reference/spatial-design.md

@@ -4,11 +4,11 @@
 
 ### Use 4pt Base, Not 8pt
 
-8pt systems are too coarse—you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+8pt systems are too coarse; you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
 
 ### Name Tokens Semantically
 
-Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks.
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing; it eliminates margin collapse and cleanup hacks.
 
 ## Grid Systems
 
@@ -43,7 +43,7 @@ Don't rely on size alone. Combine:
 
 ### Cards Are Not Required
 
-Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards**—use spacing, typography, and subtle dividers for hierarchy within a card.
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards.** Use spacing, typography, and subtle dividers for hierarchy within a card.
 
 ## Container Queries
 
@@ -67,11 +67,11 @@ Viewport queries are for page layouts. **Container queries are for components**:
 }
 ```
 
-**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands automatically, without viewport hacks.
 
 ## Optical Adjustments
 
-Text at `margin-left: 0` looks indented due to letterform whitespace—use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
+Text at `margin-left: 0` looks indented due to letterform whitespace; use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
 
 ### Touch Targets vs Visual Size
 
@@ -93,7 +93,7 @@ Buttons can look small but need large touch targets (44px minimum). Use padding
 
 ## Depth & Elevation
 
-Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle—if you can clearly see it, it's probably too strong.
+Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle. If you can clearly see it, it's probably too strong.
 
 ---
 

.agents/skills/impeccable/reference/teach.md

@@ -2,8 +2,8 @@
 
 Gathers design context for a project and writes two complementary files at the project root:
 
-- **PRODUCT.md** (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
-- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+- **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
 
 Every other impeccable command reads these files before doing any work.
 
@@ -19,7 +19,7 @@ The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migr
 
 Decision tree:
 - **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
-- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `$impeccable document` for DESIGN.md.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `$impeccable document` for DESIGN.md.
 - **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
 - **Both exist**: STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which file to refresh. Skip the one the user doesn't want changed.
 - **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
@@ -44,7 +44,7 @@ Also form a **register hypothesis** from what you find:
 - Brand signals: `/`, `/about`, `/pricing`, `/blog/*`, `/docs/*`, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
 - Product signals: `/app/*`, `/dashboard`, `/settings`, `/(auth)`, forms, data tables, side/top nav, app-shell components.
 
-Register is a hypothesis at this point, not a decision — Step 3 confirms it.
+Register is a hypothesis at this point, not a decision; Step 3 confirms it.
 
 Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
@@ -67,11 +67,11 @@ If the repo is empty or the user's brief is sparse, run a short interview before
 
 Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
 
-### Register (ask first — it shapes everything below)
+### Register (ask first; it shapes everything below)
 
-Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboards, tools — design SERVES the product).
+Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboards, tools: design SERVES the product).
 
-If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface — does that match your intent, or should we treat it differently?"*
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
 
 If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
 
@@ -84,7 +84,7 @@ If the signal is genuinely split (e.g. a product with a big marketing landing),
 ### Brand & Personality
 - How would you describe the brand personality in 3 words?
 - Reference sites or apps that capture the right feel? What specifically about them?
-  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.) — not generic "modern" adjectives.
+  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.), not generic "modern" adjectives.
   - For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
 - What should this explicitly NOT look like? Any anti-references?
 
@@ -92,7 +92,7 @@ If the signal is genuinely split (e.g. a product with a big marketing landing),
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here.** Those belong in DESIGN.md, not PRODUCT.md.
 
 ## Step 4: Write PRODUCT.md
 
@@ -120,7 +120,7 @@ product
 [What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
 ## Design Principles
-[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence". NOT visual rules like "use OKLCH" or "magenta accent".]
 
 ## Accessibility & Inclusion
 [WCAG level, known user needs, considerations]
@@ -128,7 +128,7 @@ product
 
 Register is either `brand` or `product` as a bare value. No prose, no commentary.
 
-Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
 
 ## Step 5: Decide on DESIGN.md
 

.agents/skills/impeccable/reference/typeset.md

@@ -1,4 +1,4 @@
-Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+Typography carries most of the information on the page. Replace generic defaults (Inter, Roboto, system fallback at flat scale) with type that reflects the brand and scales with intentional contrast.
 
 ---
 
@@ -39,7 +39,7 @@ Analyze what's weak or generic about the current type:
    - Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
    - Is letter-spacing intentional or default everywhere?
 
-**CRITICAL**: The goal isn't to make text "fancier" — it's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
+**CRITICAL**: The goal isn't to make text "fancier." It's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
 
 ## Plan Typography Improvements
 
@@ -49,7 +49,7 @@ Create a systematic plan:
 
 - **Font selection**: Do fonts need replacing? What fits the brand/context?
 - **Type scale**: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
-- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings — or whatever fits)
+- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings, or whatever fits)
 - **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
 
 ## Improve Typography Systematically
@@ -58,7 +58,7 @@ Create a systematic plan:
 
 If fonts need replacing:
 - Choose fonts that reflect the brand personality
-- Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights
+- Pair with genuine contrast (serif + sans, geometric + humanist), or use a single family in multiple weights
 - Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks)
 
 ### Establish Hierarchy
@@ -66,7 +66,7 @@ If fonts need replacing:
 Build a clear type scale:
 - **5 sizes cover most needs**: caption, secondary, body, subheading, heading
 - **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
-- **Combine dimensions**: Size + weight + color + space for strong hierarchy — don't rely on size alone
+- **Combine dimensions**: Size + weight + color + space for strong hierarchy. Don't rely on size alone
 - **App UIs**: Use a fixed `rem`-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
 - **Marketing / content pages**: Use fluid sizing via `clamp(min, preferred, max)` for headings and display text. Keep body text fixed
 
@@ -92,11 +92,11 @@ Build a clear type scale:
 
 **NEVER**:
 - Use more than 2-3 font families
-- Pick sizes arbitrarily — commit to a scale
+- Pick sizes arbitrarily; commit to a scale
 - Set body text below 16px
 - Use decorative/display fonts for body text
 - Disable browser zoom (`user-scalable=no`)
-- Use `px` for font sizes — use `rem` to respect user settings
+- Use `px` for font sizes; use `rem` to respect user settings
 - Default to Inter/Roboto/Open Sans when personality matters
 - Pair fonts that are similar but not identical (two geometric sans-serifs)
 
@@ -109,7 +109,7 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
-Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.
+When the type carries the hierarchy on its own, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params
 

.agents/skills/impeccable/reference/typography.md

@@ -4,7 +4,7 @@
 
 ### Vertical Rhythm
 
-Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.
+Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony; text and space share a mathematical foundation.
 
 ### Modular Scale & Hierarchy
 
@@ -24,7 +24,7 @@ Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth).
 
 ### Readability & Measure
 
-Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length: narrow columns need tighter leading, wide columns need more.
 
 **Non-obvious**: Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05–0.1, add a touch of letter-spacing (0.01–0.02em), and optionally step the body weight up one notch (regular → medium). The perceived weight drops across all three; fix all three.
 
@@ -93,11 +93,11 @@ Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these override
 
 ### Fluid Type
 
-Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
+Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate (higher vw = faster scaling). Add a rem offset so it doesn't collapse to 0 on small screens.
 
 **Use fluid type for**: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.
 
-**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI — fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
+**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI; fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
 
 **Bound your clamp()**: keep `max-size ≤ ~2.5 × min-size`. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.
 

.agents/skills/impeccable/reference/ux-writing.md

@@ -40,7 +40,7 @@ Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the va
 
 ## Voice vs Tone
 
-**Voice** is your brand's personality—consistent everywhere.
+**Voice** is your brand's personality, consistent everywhere.
 **Tone** adapts to the moment.
 
 | Moment | Tone Shift |
@@ -54,7 +54,7 @@ Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the va
 
 ## Writing for Accessibility
 
-**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
+**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
 
 ## Writing for Translation
 
@@ -96,7 +96,7 @@ Be specific: "Saving your draft..." not "Loading...". For long waits, set expect
 
 ## Confirmation Dialogs: Use Sparingly
 
-Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
 
 ## Form Instructions
 

.agents/skills/impeccable/scripts/critique-storage.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Critique persistence helper.
+ *
+ * Each run of /impeccable critique writes a per-target snapshot to
+ *   .impeccable/critique/<timestamp>__<slug>.md
+ * with a small YAML frontmatter carrying the score + P0/P1 counts.
+ *
+ * /impeccable polish reads the latest matching snapshot at start as its
+ * fix backlog. No other skill auto-reads critique output.
+ *
+ * The slug is derived mechanically from the *resolved* primary artifact
+ * (file path or URL), never from the user's natural-language phrasing.
+ * Slug stability across runs is what lets the trend display work.
+ *
+ * CLI entry points (called from skill instructions):
+ *   node critique-storage.mjs slug <resolved-target>
+ *   node critique-storage.mjs write <slug> <snapshot-body-file>
+ *   node critique-storage.mjs latest <slug>
+ *   node critique-storage.mjs trend <slug> [limit]
+ *
+ * Note: there is intentionally no `ignore` subcommand. ignore.md is a plain
+ * markdown file; the model reads it directly with its file-read tool. This
+ * helper only exists for operations the model can't trivially do inline
+ * (normalizing paths, generating filenames, globbing + parsing frontmatter).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCritiqueDir } from './impeccable-paths.mjs';
+
+const SLUG_MAX = 50;
+
+/**
+ * Mechanically derive a slug from a resolved target. Returns null if the
+ * input doesn't look like a stable identifier (empty, project root, etc).
+ *
+ * Accepts file paths and URLs. The model resolves "the homepage" to a
+ * concrete artifact before calling this — we never slug a natural-language
+ * phrase.
+ */
+export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
+  if (!resolved || typeof resolved !== 'string') return null;
+  const trimmed = resolved.trim();
+  if (!trimmed) return null;
+
+  // URL
+  if (/^https?:\/\//i.test(trimmed)) {
+    let url;
+    try { url = new URL(trimmed); } catch { return null; }
+    const hostPath = `${url.hostname}${url.pathname}`;
+    return kebab(hostPath);
+  }
+
+  // File path. Make it project-relative so two devs critiquing the same
+  // checkout get the same slug regardless of where their repo is cloned.
+  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+  let rel = path.relative(cwd, abs);
+  // If the target is outside cwd, fall back to the basename so we still
+  // produce a stable slug (vs the absolute path, which would include
+  // home dirs / usernames).
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    rel = path.basename(abs);
+  }
+  if (!rel || rel === '.' || rel === '') return null;
+  return kebab(rel);
+}
+
+function kebab(s) {
+  const slug = s
+    .toLowerCase()
+    .replace(/[/\\.]+/g, '-')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!slug) return null;
+  // Cap from the tail — the tail (filename) is more identifying than the
+  // top-level directory.
+  return slug.length <= SLUG_MAX ? slug : slug.slice(slug.length - SLUG_MAX).replace(/^-/, '');
+}
+
+/**
+ * Filename-safe UTC ISO timestamp: hyphens for separators, trailing Z.
+ * Plain colons aren't allowed on Windows filesystems.
+ */
+export function nowFilenameStamp(date = new Date()) {
+  const iso = date.toISOString();           // 2026-05-12T18:30:00.123Z
+  return iso.replace(/[:.]/g, '-').replace(/-\d+Z$/, 'Z');
+}
+
+/**
+ * Write a snapshot for `slug`. `meta` carries the small structured frontmatter
+ * keys read back by readTrend(). `body` is the human-readable critique
+ * report (everything below the frontmatter).
+ *
+ * Returns the absolute path written.
+ */
+export function writeSnapshot({ slug, meta, body, cwd = process.cwd(), now = new Date() }) {
+  if (!slug) throw new Error('writeSnapshot requires a slug');
+  const dir = getCritiqueDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const timestamp = nowFilenameStamp(now);
+  const filePath = path.join(dir, `${timestamp}__${slug}.md`);
+  // Spread `meta` first so internally computed `timestamp` and `slug`
+  // always win. Otherwise a caller-supplied meta blob (parsed from the
+  // IMPECCABLE_CRITIQUE_META env var) could clobber them, leaving the
+  // filename in disagreement with its frontmatter and corrupting trends.
+  const front = serializeFrontmatter({ ...meta, timestamp, slug });
+  fs.writeFileSync(filePath, `${front}\n${body.trim()}\n`, 'utf-8');
+  return filePath;
+}
+
+function serializeFrontmatter(obj) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined || value === null) continue;
+    const str = typeof value === 'string' ? value : String(value);
+    // Quote strings that contain : or # to keep parsing simple.
+    const needsQuotes = typeof value === 'string' && /[:#]/.test(str);
+    lines.push(`${key}: ${needsQuotes ? JSON.stringify(str) : str}`);
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (/^".*"$/.test(value)) {
+      try { value = JSON.parse(value); } catch { /* leave as-is */ }
+    } else if (/^-?\d+$/.test(value)) {
+      value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Return all snapshot files for `slug`, sorted oldest → newest.
+ */
+function listSnapshotsForSlug(slug, cwd) {
+  const dir = getCritiqueDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  const suffix = `__${slug}.md`;
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith(suffix))
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+/**
+ * Return the most recent snapshot for `slug`, or null. Polish reads this
+ * to find its fix backlog when the slug matches.
+ */
+export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
+  const all = listSnapshotsForSlug(slug, cwd);
+  if (!all.length) return null;
+  const latest = all[all.length - 1];
+  const body = fs.readFileSync(latest, 'utf-8');
+  return { path: latest, body, meta: parseFrontmatter(body) };
+}
+
+/**
+ * Return the last `limit` snapshots' frontmatter, oldest → newest.
+ * Critique appends a one-line trend to its output using this.
+ */
+export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
+  const all = listSnapshotsForSlug(slug, cwd);
+  const slice = all.slice(-limit);
+  return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
+}
+
+// ---- CLI ---------------------------------------------------------------
+
+function main(argv) {
+  const [cmd, ...args] = argv;
+  switch (cmd) {
+    case 'slug': {
+      const slug = slugFromTarget(args[0]);
+      if (!slug) { process.stderr.write('no stable slug for input\n'); process.exit(1); }
+      process.stdout.write(`${slug}\n`);
+      return;
+    }
+    case 'write': {
+      const [slug, bodyFile] = args;
+      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug> <body-file>\n'); process.exit(1); }
+      const raw = fs.readFileSync(bodyFile, 'utf-8');
+      // The body file may be a full report. The caller passes the meta as
+      // a JSON object on stdin if it wants structured frontmatter; otherwise
+      // we write with minimal metadata.
+      let meta = {};
+      const metaArg = process.env.IMPECCABLE_CRITIQUE_META;
+      if (metaArg) {
+        try { meta = JSON.parse(metaArg); } catch { /* ignore */ }
+      }
+      const out = writeSnapshot({ slug, meta, body: raw });
+      process.stdout.write(`${out}\n`);
+      return;
+    }
+    case 'latest': {
+      const latest = readLatestSnapshot(args[0]);
+      if (!latest) { process.exit(2); }
+      process.stdout.write(latest.body);
+      return;
+    }
+    case 'trend': {
+      const rows = readTrend(args[0], { limit: args[1] ? Number(args[1]) : 5 });
+      process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+      return;
+    }
+    default:
+      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend> [args]\n');
+      process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2));
+}

.agents/skills/impeccable/scripts/impeccable-paths.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const IMPECCABLE_DIR = '.impeccable';
+export const LIVE_DIR = 'live';
+export const CRITIQUE_DIR = 'critique';
+
+export function getImpeccableDir(cwd = process.cwd()) {
+  return path.join(cwd, IMPECCABLE_DIR);
+}
+
+export function getDesignSidecarPath(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), 'design.json');
+}
+
+export function getDesignSidecarCandidates(cwd = process.cwd(), contextDir = cwd) {
+  const candidates = [
+    getDesignSidecarPath(cwd),
+    path.join(cwd, 'DESIGN.json'),
+  ];
+  const contextLegacy = path.join(contextDir, 'DESIGN.json');
+  if (!candidates.includes(contextLegacy)) candidates.push(contextLegacy);
+  return candidates;
+}
+
+export function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd) {
+  return firstExisting(getDesignSidecarCandidates(cwd, contextDir));
+}
+
+export function getLiveDir(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), LIVE_DIR);
+}
+
+export function getLiveConfigPath(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'config.json');
+}
+
+export function getLegacyLiveConfigPath(scriptsDir) {
+  return path.join(scriptsDir, 'config.json');
+}
+
+export function resolveLiveConfigPath({ cwd = process.cwd(), scriptsDir, env = process.env } = {}) {
+  if (env.IMPECCABLE_LIVE_CONFIG && env.IMPECCABLE_LIVE_CONFIG.trim()) {
+    const configured = env.IMPECCABLE_LIVE_CONFIG.trim();
+    return path.isAbsolute(configured) ? configured : path.resolve(cwd, configured);
+  }
+  const primary = getLiveConfigPath(cwd);
+  if (fs.existsSync(primary)) return primary;
+  if (scriptsDir) {
+    const legacy = getLegacyLiveConfigPath(scriptsDir);
+    if (fs.existsSync(legacy)) return legacy;
+  }
+  return primary;
+}
+
+export function getLiveServerPath(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'server.json');
+}
+
+export function getLegacyLiveServerPath(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live.json');
+}
+
+export function readLiveServerInfo(cwd = process.cwd()) {
+  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
+    try {
+      return { info: JSON.parse(fs.readFileSync(filePath, 'utf-8')), path: filePath };
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+export function writeLiveServerInfo(cwd = process.cwd(), info) {
+  const filePath = getLiveServerPath(cwd);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(info));
+  return filePath;
+}
+
+export function removeLiveServerInfo(cwd = process.cwd()) {
+  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
+    try { fs.unlinkSync(filePath); } catch {}
+  }
+}
+
+export function getLiveSessionsDir(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'sessions');
+}
+
+export function getLegacyLiveSessionsDir(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live', 'sessions');
+}
+
+export function getLiveAnnotationsDir(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'annotations');
+}
+
+export function getCritiqueDir(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), CRITIQUE_DIR);
+}
+
+export function getLegacyLiveAnnotationsDir(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live', 'annotations');
+}
+
+function firstExisting(paths) {
+  return paths.find((filePath) => fs.existsSync(filePath)) || null;
+}

.agents/skills/impeccable/scripts/live-accept.mjs

@@ -105,15 +105,22 @@ function handleDiscard(id, lines, targetFile) {
   if (!block) return { handled: false, error: 'Markers not found' };
 
   const original = extractOriginal(lines, block);
-  const indent = lines[block.start].match(/^(\s*)/)[1];
+  const isJsx = detectCommentSyntax(targetFile).open === '{/*';
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
 
-  // De-indent the original content back to the marker's indentation level
+  // Restore at the line we're actually replacing FROM, not the marker line.
+  // For JSX wrappers the marker comments live INSIDE the outer `<div>`, so
+  // `block.start` sits 2 spaces deeper than the original element. Using that
+  // as the deindent base would push the restored content 2 spaces too far
+  // right on every JSX/TSX session. `replaceRange.start` is the outer wrapper
+  // line, which is at the original element's indent for both HTML and JSX.
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
   const restored = deindentContent(original, indent);
 
   const newLines = [
-    ...lines.slice(0, block.start),
+    ...lines.slice(0, replaceRange.start),
     ...restored,
-    ...lines.slice(block.end + 1),
+    ...lines.slice(replaceRange.end + 1),
   ];
   fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
   return {};
@@ -127,8 +134,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const block = findMarkerBlock(id, lines);
   if (!block) return { handled: false, error: 'Markers not found' };
 
-  const indent = lines[block.start].match(/^(\s*)/)[1];
   const commentSyntax = detectCommentSyntax(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  // Anchor indent on the line we're replacing FROM (the outer wrapper),
+  // not on `block.start` — for JSX that's the marker comment 2 spaces
+  // deeper than the original element. See handleDiscard for the full
+  // rationale.
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
 
   // Extract the chosen variant's inner content
   const variantContent = extractVariant(lines, block, variantNum);
@@ -149,7 +162,6 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const replacement = [];
 
   if (cssContent) {
-    const isJsx = commentSyntax.open === '{/*';
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
     // JSX targets need the CSS body wrapped in a template literal so that the
     // `{` and `}` in CSS rules don't get parsed as JSX expressions.
@@ -177,7 +189,6 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // need the object form, otherwise React 19 throws "Failed to set indexed
   // property [0] on CSSStyleDeclaration" while parsing the string char-by-char.
   if (cssContent) {
-    const isJsx = commentSyntax.open === '{/*';
     const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
     replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
@@ -187,9 +198,9 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   }
 
   const newLines = [
-    ...lines.slice(0, block.start),
+    ...lines.slice(0, replaceRange.start),
     ...replacement,
-    ...lines.slice(block.end + 1),
+    ...lines.slice(replaceRange.end + 1),
   ];
   fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
 
@@ -218,6 +229,72 @@ function findMarkerBlock(id, lines) {
   return (start !== -1 && end !== -1) ? { start, end } : null;
 }
 
+/**
+ * Compute the line range to REPLACE (vs. just the marker range to extract
+ * from). For JSX/TSX wrappers, live-wrap places the marker comments INSIDE
+ * the `<div data-impeccable-variants="ID">` outer wrapper so the picked
+ * element's JSX slot keeps a single child — a Fragment `<></>` would have
+ * solved the multi-sibling case but failed inside `asChild` / cloneElement
+ * parents with "Invalid prop supplied to React.Fragment".
+ *
+ * That means the marker block is enclosed by the wrapper `<div>` opener
+ * (with `data-impeccable-variants="ID"`) and its matching `</div>`. We
+ * walk back to the opener and forward to the closer so accept/discard
+ * remove the entire scaffold, not just the inner markers.
+ *
+ * Marker lines themselves stay where they were so extractOriginal /
+ * extractVariant / extractCss continue to walk the same range.
+ */
+function expandReplaceRange(block, lines, isJsx) {
+  if (!isJsx) return { start: block.start, end: block.end };
+
+  let { start, end } = block;
+
+  // Walk back for the wrapper `<div data-impeccable-variants="..."` opener.
+  // The attr may sit on a continuation line of a multi-line opening tag, so
+  // also walk to the line that actually contains `<div`.
+  for (let i = start - 1; i >= Math.max(0, start - 12); i--) {
+    if (/data-impeccable-variants=/.test(lines[i])) {
+      let opener = i;
+      while (opener > 0 && !/<div\b/.test(lines[opener])) opener--;
+      start = opener;
+      break;
+    }
+  }
+
+  // Walk forward to the matching `</div>` by div-depth tracking from the
+  // wrapper opener. Operate on JOINED text instead of per-line: a
+  // multi-line self-closing JSX `<div\n  className="spacer"\n/>` would
+  // fool per-line regex tracking (the `<div` line matches openRe but the
+  // `/>` line never matches selfCloseRe since it needs `<div` on the same
+  // line). That left depth permanently over-counted and the wrapper's
+  // outer `</div>` orphaned after accept/discard. Single regex with
+  // `[^>]*?` (which spans newlines in JS) handles either form correctly.
+  const joined = lines.slice(start).join('\n');
+  // Match either `<div … />` (self-close, group 1 is `/`), `<div … >`
+  // (open, group 1 is empty), or `</div>`.
+  const tagRe = /<div\b[^>]*?(\/?)>|<\/div\s*>/g;
+  let depth = 0;
+  let m;
+  while ((m = tagRe.exec(joined)) !== null) {
+    const isClose = m[0].startsWith('</');
+    const isSelfClose = !isClose && m[1] === '/';
+    if (isClose) depth--;
+    else if (!isSelfClose) depth++;
+    if (depth <= 0) {
+      // m.index is offset within `joined`; convert back to a file line.
+      const linesBefore = joined.slice(0, m.index + m[0].length).split('\n').length - 1;
+      const candidateEnd = start + linesBefore;
+      if (candidateEnd >= end) {
+        end = candidateEnd;
+        break;
+      }
+    }
+  }
+
+  return { start, end };
+}
+
 /**
  * Join wrapper lines into a single string with `<style>` elements removed so
  * marker matching and div-depth tracking aren't confused by:
@@ -345,7 +422,7 @@ function extractCss(lines, block, id) {
       // Same-line open + close: extract inner text.
       const sameLine = line.match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/);
       if (sameLine) {
-        const inner = sameLine[1];
+        const inner = stripJsxTemplateWrap(sameLine[1]);
         return inner.length > 0 ? inner.split('\n') : null;
       }
       inStyle = true;
@@ -362,7 +439,60 @@ function extractCss(lines, block, id) {
     }
   }
 
-  return content.length > 0 ? content : null;
+  if (content.length === 0) return null;
+  return stripJsxTemplateLines(content);
+}
+
+/**
+ * Strip a JSX template-literal wrap (`{` … `}`) from CSS extracted out of a
+ * `<style>` element in a JSX/TSX file. The agent may write the wrap with
+ * `{` and `}` directly attached to the `<style>` tags, on their own lines,
+ * or attached to the first/last CSS lines — all three are JSX-legal.
+ *
+ * Stripping is required because handleAccept re-wraps the CSS itself when
+ * carbonizing. Without this, two consecutive accepts (or a previously-
+ * accepted variants block being carbonized) would produce nested
+ * `{` `{` … `}` `}`, which oxc rejects with "Expected `}` but found `@`".
+ */
+function stripJsxTemplateLines(content) {
+  const out = content.slice();
+
+  // Drop any leading blank lines so we don't miss a `{` line buried below
+  // them; same for trailing.
+  while (out.length > 0 && out[0].trim() === '') out.shift();
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+  if (out.length === 0) return null;
+
+  // Leading `{`: own line, or attached to the first CSS line.
+  const firstTrim = out[0].trimStart();
+  if (firstTrim === '{`') {
+    out.shift();
+  } else if (firstTrim.startsWith('{`')) {
+    const idx = out[0].indexOf('{`');
+    out[0] = out[0].slice(0, idx) + out[0].slice(idx + 2);
+    if (out[0].trim() === '') out.shift();
+  }
+  if (out.length === 0) return null;
+
+  // Trailing `` ` `` `}`: own line, or attached to the last CSS line.
+  const lastIdx = out.length - 1;
+  const lastTrim = out[lastIdx].trimEnd();
+  if (lastTrim === '`}') {
+    out.pop();
+  } else if (lastTrim.endsWith('`}')) {
+    const text = out[lastIdx];
+    const idx = text.lastIndexOf('`}');
+    out[lastIdx] = text.slice(0, idx) + text.slice(idx + 2);
+    if (out[lastIdx].trim() === '') out.pop();
+  }
+
+  return out.length > 0 ? out : null;
+}
+
+function stripJsxTemplateWrap(text) {
+  const lines = text.split('\n');
+  const stripped = stripJsxTemplateLines(lines);
+  return stripped ? stripped.join('\n') : '';
 }
 
 /**

.agents/skills/impeccable/scripts/live-browser-session.js

@@ -0,0 +1,123 @@
+/**
+ * Browser-side durable session helpers for Impeccable live mode.
+ *
+ * Kept separate from live-browser.js so recovery state can be tested without
+ * booting the full overlay UI. Served before live-browser.js and attached to
+ * window.__IMPECCABLE_LIVE_SESSION__.
+ */
+(function (root) {
+  'use strict';
+
+  function createLiveBrowserSessionState({ prefix, storage, idFactory }) {
+    if (!prefix) throw new Error('prefix required');
+    const store = storage || root.localStorage;
+    const makeId = idFactory || function () { return Math.random().toString(16).slice(2, 10); };
+    const sessionKey = prefix + '-session';
+    const handledKey = sessionKey + '-handled';
+    const scrollKey = sessionKey + '-scroll';
+    let checkpointRevision = 0;
+    const owner = makeId();
+
+    function safeRead(key) {
+      try { return store.getItem(key); } catch { return null; }
+    }
+
+    function safeWrite(key, value) {
+      try { store.setItem(key, value); } catch { /* quota exceeded or private mode */ }
+    }
+
+    function safeRemove(key) {
+      try { store.removeItem(key); } catch { /* unavailable storage */ }
+    }
+
+    function loadSession() {
+      try {
+        const raw = safeRead(sessionKey);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (Number.isInteger(parsed.checkpointRevision)) {
+          checkpointRevision = Math.max(checkpointRevision, parsed.checkpointRevision);
+        }
+        return parsed;
+      } catch { return null; }
+    }
+
+    function saveSession(session) {
+      if (!session || !session.id) return;
+      const payload = {
+        ...session,
+        checkpointRevision,
+      };
+      safeWrite(sessionKey, JSON.stringify(payload));
+    }
+
+    function clearSession() {
+      safeRemove(sessionKey);
+    }
+
+    function nextCheckpointRevision() {
+      checkpointRevision += 1;
+      const existing = loadSession();
+      if (existing?.id) saveSession(existing);
+      return checkpointRevision;
+    }
+
+    function seedCheckpointRevision(value) {
+      if (Number.isInteger(value)) checkpointRevision = Math.max(checkpointRevision, value);
+      return checkpointRevision;
+    }
+
+    function currentCheckpointRevision() {
+      return checkpointRevision;
+    }
+
+    function markHandled(id) {
+      if (!id) return;
+      safeWrite(handledKey, id);
+    }
+
+    function isHandled(id) {
+      return !!id && safeRead(handledKey) === id;
+    }
+
+    function clearHandled() {
+      safeRemove(handledKey);
+    }
+
+    function writeScrollY(y) {
+      safeWrite(scrollKey, String(y));
+    }
+
+    function readScrollY() {
+      const raw = safeRead(scrollKey);
+      if (raw == null) return null;
+      const n = parseFloat(raw);
+      return isFinite(n) ? n : null;
+    }
+
+    function clearScrollY() {
+      safeRemove(scrollKey);
+    }
+
+    return {
+      owner,
+      sessionKey,
+      handledKey,
+      scrollKey,
+      saveSession,
+      loadSession,
+      clearSession,
+      nextCheckpointRevision,
+      seedCheckpointRevision,
+      currentCheckpointRevision,
+      markHandled,
+      isHandled,
+      clearHandled,
+      writeScrollY,
+      readScrollY,
+      clearScrollY,
+    };
+  }
+
+  root.__IMPECCABLE_LIVE_SESSION__ = { createLiveBrowserSessionState };
+})(typeof window !== 'undefined' ? window : globalThis);

.agents/skills/impeccable/scripts/live-browser.js

@@ -50,6 +50,16 @@
   const Z = { highlight: 100001, bar: 100005, picker: 100007, toast: 100010 };
   const EASE = 'cubic-bezier(0.22, 1, 0.36, 1)'; // ease-out-quint
   const PREFIX = 'impeccable-live';
+  const sessionState = window.__IMPECCABLE_LIVE_SESSION__?.createLiveBrowserSessionState({
+    prefix: PREFIX,
+    storage: localStorage,
+    idFactory: () => crypto.randomUUID().replace(/-/g, '').slice(0, 8),
+  });
+  if (!sessionState) {
+    console.error('[impeccable] live-browser-session.js was not loaded. Live mode cannot start safely.');
+    window.__IMPECCABLE_LIVE_INIT__ = false;
+    return;
+  }
   const HIGHLIGHT_TRANSITION =
     'top 140ms ' + EASE +
     ', left 140ms ' + EASE +
@@ -112,6 +122,8 @@
   let hasProjectContext = false;
   let selectedAction = 'impeccable';
   let selectedCount = 3;
+  const browserOwner = sessionState.owner;
+  let checkpointTimer = null;
 
   // Scroll lock — holds window.scrollY at a fixed value while the session is
   // active, so HMR DOM patches and variant swaps can't drift the page. See
@@ -126,21 +138,9 @@
   // (Previously: saveSession wrote scrollY alongside state, so every call
   // during resume overwrote the pre-reload value with whatever the browser
   // had landed on, typically 0.)
-  const SCROLL_KEY_SUFFIX = '-scroll';
-  function writeScrollY(y) {
-    try { localStorage.setItem(LS_KEY + SCROLL_KEY_SUFFIX, String(y)); } catch {}
-  }
-  function readScrollY() {
-    try {
-      const raw = localStorage.getItem(LS_KEY + SCROLL_KEY_SUFFIX);
-      if (raw == null) return null;
-      const n = parseFloat(raw);
-      return isFinite(n) ? n : null;
-    } catch { return null; }
-  }
-  function clearScrollY() {
-    try { localStorage.removeItem(LS_KEY + SCROLL_KEY_SUFFIX); } catch {}
-  }
+  function writeScrollY(y) { sessionState.writeScrollY(y); }
+  function readScrollY() { return sessionState.readScrollY(); }
+  function clearScrollY() { sessionState.clearScrollY(); }
 
   // Pre-empt the browser: apply manual scroll restoration and jump to the
   // saved scrollY at script-parse time. Retries on fonts.ready and load
@@ -1585,6 +1585,7 @@
           paramsCurrentValues[p.id] = v;
           readout.textContent = formatRangeValue(input);
           applyParamValue(variantEl, p, v);
+          queueCheckpoint('param_changed');
         });
         row.appendChild(input);
       } else if (p.kind === 'toggle') {
@@ -1615,6 +1616,7 @@
           knob.style.left = next ? '18px' : '2px';
           readout.textContent = next ? 'On' : 'Off';
           applyParamValue(variantEl, p, next);
+          queueCheckpoint('param_changed');
         });
         row.appendChild(track);
       } else if (p.kind === 'steps') {
@@ -1651,6 +1653,7 @@
               btn.style.color = on ? 'oklch(98% 0 0)' : P.text;
             });
             applyParamValue(variantEl, p, o.value);
+            queueCheckpoint('param_changed');
           });
           segRow.appendChild(b);
           segBtns.push({ btn: b, val: o.value });
@@ -1872,19 +1875,26 @@
           return;
         }
 
+        const previousVisibleVariant = currentSessionId === sessionId ? visibleVariant : 0;
+
         // Replace the live element with the full wrapper from source
         const wrapper = srcWrapper.cloneNode(true);
         liveEl.parentElement.replaceChild(wrapper, liveEl);
 
-        // Update state: count variants, show the first one
+        // Update state: count variants, preserving the user's current variant
+        // when a late HMR/source reinjection lands after they have cycled.
         const variants = wrapper.querySelectorAll('[data-impeccable-variant]:not([data-impeccable-variant="original"])');
         arrivedVariants = variants.length;
         expectedVariants = parseInt(wrapper.dataset.impeccableVariantCount || arrivedVariants);
-        visibleVariant = 1;
-        showVariantInDOM(sessionId, 1);
+        const saved = loadSession();
+        const savedVisibleVariant = saved && saved.id === sessionId ? saved.visible : 0;
+        visibleVariant = previousVisibleVariant > 0 && previousVisibleVariant <= arrivedVariants
+          ? previousVisibleVariant
+          : (savedVisibleVariant > 0 && savedVisibleVariant <= arrivedVariants ? savedVisibleVariant : 1);
+        showVariantInDOM(sessionId, visibleVariant);
 
         // Update selectedElement to the visible variant's content
-        selectedElement = pickVariantContent(wrapper, 1) || wrapper.parentElement;
+        selectedElement = pickVariantContent(wrapper, visibleVariant) || wrapper.parentElement;
 
         state = 'CYCLING';
         hideShaderOverlay();
@@ -1907,6 +1917,7 @@
     updateSelectedElement();
     updateBarContent('cycling');
     saveSession();
+    queueCheckpoint('variant_changed');
   }
 
   function updateSelectedElement() {
@@ -1917,6 +1928,18 @@
     if (visEl) selectedElement = visEl;
   }
 
+  function readVisibleVariantFromDOM(sessionId) {
+    const wrapper = document.querySelector('[data-impeccable-variants="' + sessionId + '"]');
+    if (!wrapper) return 0;
+    const variants = wrapper.querySelectorAll('[data-impeccable-variant]:not([data-impeccable-variant="original"])');
+    for (const variant of variants) {
+      if (variant.style.display === 'none') continue;
+      const idx = parseInt(variant.dataset.impeccableVariant || '0', 10);
+      if (idx > 0) return idx;
+    }
+    return 0;
+  }
+
   // Resolve the element that represents the variant's visible content.
   // Contract: each variant div should contain exactly one top-level element
   // (the full replacement). In practice a model may ship loose siblings or
@@ -2107,8 +2130,10 @@
       updating = true;
       arrivedVariants = count;
       if (visibleVariant === 0 && arrivedVariants > 0) {
-        visibleVariant = 1;
-        showVariantInDOM(sessionId, 1);
+        const saved = loadSession();
+        const savedVisibleVariant = saved && saved.id === sessionId ? saved.visible : 0;
+        visibleVariant = savedVisibleVariant > 0 && savedVisibleVariant <= arrivedVariants ? savedVisibleVariant : 1;
+        showVariantInDOM(sessionId, visibleVariant);
         // showVariantInDOM hid the original (display:none); if we were still
         // anchored to the original's content, its boundingRect is now zero
         // and the bar snaps to (0,0). Re-point at the visible variant instead.
@@ -2128,6 +2153,7 @@
         updateBarContent('generating');
       }
       saveSession();
+      queueCheckpoint(state === 'CYCLING' ? 'variants_ready' : 'variants_progress');
       updating = false;
     });
 
@@ -2236,6 +2262,7 @@
 
   /** Server died or became unreachable. Reset UI to a clean state. */
   function handleServerLost() {
+    const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
       showToast('Live server disconnected. Session ended.', 5000);
     }
@@ -2246,21 +2273,61 @@
     stopScrollTracking();
     if (variantObserver) { variantObserver.disconnect(); variantObserver = null; }
     stopScrollLock();
-    clearScrollY();
-    clearSession();
+    // Preserve local session state on server loss. The durable journal is the
+    // source of truth, but localStorage plus the variant wrapper lets the UI
+    // resume after a helper restart or page reload instead of treating a
+    // transient disconnect as an explicit discard.
     selectedElement = null;
-    currentSessionId = null;
     selectedAction = 'impeccable';
-    state = 'IDLE';
+    state = recoveryState;
+    if (currentSessionId) saveSession();
   }
 
-  function sendEvent(msg) {
+  function sendEvent(msg, opts) {
     msg.token = TOKEN;
-    fetch('http://localhost:' + PORT + '/events', {
+    function handleFailure(err) {
+      console.error('[impeccable] Failed to send event:', err);
+      if (opts && opts.throwOnError) throw err;
+      return null;
+    }
+    return fetch('http://localhost:' + PORT + '/events', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(msg),
-    }).catch(err => console.error('[impeccable] Failed to send event:', err));
+    }).then(res => {
+      if (res.ok) return res;
+      return handleFailure(new Error('HTTP ' + res.status + ' ' + res.statusText));
+    }).catch(handleFailure);
+  }
+
+  function checkpointPayload(reason) {
+    return {
+      type: 'checkpoint',
+      id: currentSessionId,
+      revision: sessionState.nextCheckpointRevision(),
+      owner: browserOwner,
+      phase: String(state || '').toLowerCase(),
+      reason,
+      pageUrl: location.pathname,
+      expectedVariants,
+      arrivedVariants,
+      visibleVariant,
+      paramValues: { ...paramsCurrentValues },
+    };
+  }
+
+  function sendCheckpoint(reason) {
+    if (!currentSessionId) return Promise.resolve(null);
+    return sendEvent(checkpointPayload(reason)).catch(() => null);
+  }
+
+  function queueCheckpoint(reason) {
+    if (!currentSessionId) return;
+    if (checkpointTimer) clearTimeout(checkpointTimer);
+    checkpointTimer = setTimeout(() => {
+      checkpointTimer = null;
+      sendCheckpoint(reason);
+    }, 120);
   }
 
   // ---------------------------------------------------------------------------
@@ -2496,6 +2563,7 @@
     state = 'GENERATING';
     showBar('generating');
     saveSession();
+    sendCheckpoint('generate_started');
     writeScrollY(window.scrollY);
     if (variantObserver) variantObserver.disconnect();
     variantObserver = startVariantObserver(currentSessionId);
@@ -2622,11 +2690,15 @@
       if (!isTransparentColor(cs.backgroundColor)) return cs.backgroundColor;
       node = node.parentElement;
     }
-    return (
-      getComputedStyle(document.body).backgroundColor ||
-      getComputedStyle(document.documentElement).backgroundColor ||
-      '#ffffff'
-    );
+    // The walk already passed through <body> and <html>; if they had been
+    // opaque we would have returned. Falling through with the previous
+    // `getComputedStyle(body).backgroundColor || …` chain is a trap: that
+    // call returns the literal string `"rgba(0, 0, 0, 0)"` for a page that
+    // never set its own bg, which is truthy and short-circuits the chain to
+    // transparent-black — modern-screenshot then renders the capture on a
+    // black canvas and the shader overlay flashes solid black during load.
+    // The browser canvas defaults to white, so we do too.
+    return '#ffffff';
   }
 
   // Capture the element (with current annotations baked in) and return a PNG
@@ -2916,13 +2988,12 @@ void main() {
 
   function handleAccept() {
     if (!currentSessionId || arrivedVariants === 0) return;
+    const domVisibleVariant = readVisibleVariantFromDOM(currentSessionId);
+    if (domVisibleVariant > 0) visibleVariant = domVisibleVariant;
     const acceptPayload = { type: 'accept', id: currentSessionId, variantId: String(visibleVariant) };
     if (Object.keys(paramsCurrentValues).length > 0) {
       acceptPayload.paramValues = { ...paramsCurrentValues };
     }
-    sendEvent(acceptPayload);
-    markSessionHandled();
-
     // The accepted variant is already the only visible child of the wrapper
     // (all other variants are display:none). HMR from the source rewrite will
     // replace the wrapper imminently. Don't eagerly replaceChild here — React
@@ -2932,9 +3003,28 @@ void main() {
     const acceptedSessionId = currentSessionId;
     const acceptedVariant = visibleVariant;
 
-    state = 'CONFIRMED';
-    updateBarContent('confirmed');
-    setTimeout(function() {
+    state = 'SAVING';
+    updateBarContent('saving');
+
+    sendEvent(acceptPayload, { throwOnError: true })
+      .then(() => {
+        markSessionHandled();
+        confirmAcceptAfterReceipt();
+      })
+      .catch(() => {
+        state = 'CYCLING';
+        updateBarContent('cycling');
+        showToast('Could not confirm accept with the live server. Session kept for recovery; try Accept again.', 5000);
+      });
+
+    function confirmAcceptAfterReceipt() {
+      state = 'CONFIRMED';
+      updateBarContent('confirmed');
+      scheduleAcceptCleanup();
+    }
+
+    function scheduleAcceptCleanup() {
+      setTimeout(function() {
       hideBar();
       hideHighlight();
       stopScrollTracking();
@@ -2963,50 +3053,46 @@ void main() {
         accepted.style.display = 'contents';
         parent.replaceChild(accepted, wrapper);
       }
-    }, 2000);
+      }, 2000);
+    }
   }
 
   function handleDiscard() {
     if (!currentSessionId) return;
-    sendEvent({ type: 'discard', id: currentSessionId });
-    markSessionHandled();
-    // Instant DOM restore + fire-and-forget (script handles file cleanup)
-    cleanup();
+    sendEvent({ type: 'discard', id: currentSessionId }, { throwOnError: true })
+      .then(() => {
+        markSessionHandled();
+        cleanup();
+      })
+      .catch(() => showToast('Could not confirm discard with the live server. Session kept for recovery.', 5000));
   }
 
   // ---------------------------------------------------------------------------
-  // Session persistence via localStorage
+  // Session persistence via live-browser-session.js
   // ---------------------------------------------------------------------------
   // Survives page reloads, browser close/reopen, HMR, and accidental refreshes.
 
-  const LS_KEY = PREFIX + '-session';
-
   function saveSession() {
     if (!currentSessionId) return;
     // NOTE: scrollY is stored under a separate key (writeScrollY). Storing
     // it here would overwrite the Go-time value every time state changes.
-    try {
-      localStorage.setItem(LS_KEY, JSON.stringify({
-        id: currentSessionId,
-        state: state,
-        action: selectedAction,
-        count: selectedCount,
-        expected: expectedVariants,
-        arrived: arrivedVariants,
-        visible: visibleVariant,
-      }));
-    } catch { /* quota exceeded or private mode */ }
+    sessionState.saveSession({
+      id: currentSessionId,
+      state,
+      action: selectedAction,
+      count: selectedCount,
+      expected: expectedVariants,
+      arrived: arrivedVariants,
+      visible: visibleVariant,
+    });
   }
 
   function loadSession() {
-    try {
-      const raw = localStorage.getItem(LS_KEY);
-      return raw ? JSON.parse(raw) : null;
-    } catch { return null; }
+    return sessionState.loadSession();
   }
 
   function clearSession() {
-    try { localStorage.removeItem(LS_KEY); } catch {}
+    sessionState.clearSession();
   }
 
   /** Mark session as handled (accepted/discarded). The agent will clean up
@@ -3014,19 +3100,15 @@ void main() {
    *  prevents resumeSession from picking it up again after reload. */
   function markSessionHandled() {
     if (!currentSessionId) return;
-    try {
-      localStorage.setItem(LS_KEY + '-handled', currentSessionId);
-    } catch {}
+    sessionState.markHandled(currentSessionId);
   }
 
   function isSessionHandled(id) {
-    try {
-      return localStorage.getItem(LS_KEY + '-handled') === id;
-    } catch { return false; }
+    return sessionState.isHandled(id);
   }
 
   function clearHandled() {
-    try { localStorage.removeItem(LS_KEY + '-handled'); } catch {}
+    sessionState.clearHandled();
   }
 
   function cleanup() {
@@ -3157,6 +3239,7 @@ void main() {
     // hid. Now that state is CYCLING, re-fire.
     if (state === 'CYCLING') refreshParamsPanel();
     saveSession();
+    queueCheckpoint('browser_resumed');
 
     // Start observing for more variants AFTER initial setup
     if (variantObserver) variantObserver.disconnect();
@@ -3613,7 +3696,7 @@ void main() {
   }
 
   // ---------------------------------------------------------------------------
-  // Design System Panel — visualizes the project's DESIGN.json sidecar
+  // Design System Panel — visualizes the project's .impeccable/design.json sidecar
   // ---------------------------------------------------------------------------
 
   const DESIGN_PREFS_KEY = 'impeccable-live-design-panel';
@@ -3625,7 +3708,7 @@ void main() {
     open: false,
     tab: 'visual',          // 'visual' | 'raw'
     parsed: null,           // parseDesignMd output (frontmatter + body sections)
-    sidecar: null,          // DESIGN.json v2 payload (extensions + components + narrative)
+    sidecar: null,          // .impeccable/design.json v2 payload (extensions + components + narrative)
     hasMd: false,
     hasSidecar: false,
     present: null,          // true/false once fetch resolves
@@ -4126,7 +4209,7 @@ void main() {
     box.className = 'stale';
     box.innerHTML = `
       <span class="stale-dot"></span>
-      <span class="stale-text"><strong>DESIGN.md is newer than DESIGN.json.</strong> Run <code>/impeccable document</code> to refresh the sidecar.</span>
+      <span class="stale-text"><strong>DESIGN.md is newer than .impeccable/design.json.</strong> Run <code>/impeccable document</code> to refresh the sidecar.</span>
     `;
     return box;
   }
@@ -4134,7 +4217,7 @@ void main() {
   function renderParsedMdCta() {
     const box = document.createElement('div');
     box.className = 'parsed-md-cta';
-    box.innerHTML = `<strong>Basic view</strong>This panel reads the tokens in your <code>DESIGN.md</code> frontmatter. Running <code>/impeccable document</code> also generates a <code>DESIGN.json</code> sidecar with your project's actual component snippets (button, input, nav) and tonal ramps, rendered live below the tokens.`;
+    box.innerHTML = `<strong>Basic view</strong>This panel reads the tokens in your <code>DESIGN.md</code> frontmatter. Running <code>/impeccable document</code> also generates a <code>.impeccable/design.json</code> sidecar with your project's actual component snippets (button, input, nav) and tonal ramps, rendered live below the tokens.`;
     return box;
   }
 
@@ -4594,7 +4677,7 @@ void main() {
 
   function cssSafe(v) {
     // Strip anything outside valid CSS value chars to prevent injection via
-    // DESIGN.json values rendered into inline style strings.
+    // .impeccable/design.json values rendered into inline style strings.
     return String(v).replace(/[<>"'`\n]/g, '');
   }
 

.agents/skills/impeccable/scripts/live-complete.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Canonical durable completion acknowledgement for Impeccable live sessions.
+ */
+
+import { createLiveSessionStore } from './live-session-store.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
+
+function parseArgs(argv) {
+  const out = { status: 'complete' };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--id') out.id = argv[++i];
+    else if (arg.startsWith('--id=')) out.id = arg.slice('--id='.length);
+    else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
+    else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
+    else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
+    else if (arg === '--help' || arg === '-h') out.help = true;
+  }
+  return out;
+}
+
+export async function completeCli() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.id) {
+    console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
+    process.exit(args.help ? 0 : 1);
+  }
+
+  const serverInfo = readServerInfo();
+  const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
+  if (serverResult?.ok) {
+    const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
+    const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
+    console.log(JSON.stringify({ ok: true, id: args.id, phase: snapshot?.phase || args.status, snapshot }, null, 2));
+    return;
+  }
+
+  const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
+  const event = args.status === 'discarded'
+    ? { type: 'discarded', id: args.id }
+    : args.status === 'agent_error'
+      ? { type: 'agent_error', id: args.id, message: args.message || 'unknown error' }
+      : { type: 'complete', id: args.id };
+  const snapshot = store.appendEvent(event);
+  console.log(JSON.stringify({ ok: true, id: args.id, phase: snapshot.phase, snapshot }, null, 2));
+}
+
+function readServerInfo() {
+  return readLiveServerInfo(process.cwd())?.info || null;
+}
+
+async function completeThroughServer(info, args) {
+  const type = args.status === 'discarded'
+    ? 'discarded'
+    : args.status === 'agent_error'
+      ? 'error'
+      : 'complete';
+  try {
+    const res = await fetch(`http://localhost:${info.port}/poll`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token: info.token, id: args.id, type, message: args.message }),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
+  completeCli();
+}

.agents/skills/impeccable/scripts/live-completion.mjs

@@ -0,0 +1,18 @@
+export function completionTypeForAcceptResult(eventType, acceptResult) {
+  if (eventType === 'discard') return acceptResult?.handled === true ? 'discarded' : 'error';
+  if (acceptResult?.handled === true && acceptResult?.carbonize === true) return 'agent_done';
+  if (acceptResult?.handled === true) return 'complete';
+  if (acceptResult?.mode === 'error') return 'error';
+  return 'agent_done';
+}
+
+export function completionAckForAcceptResult(eventId, completionType, acceptResult) {
+  const ack = { ok: true, type: completionType };
+  if (acceptResult?.handled === true && acceptResult?.carbonize === true) {
+    ack.final = false;
+    ack.requiresComplete = true;
+    ack.nextCommand = `live-complete.mjs --id ${eventId}`;
+    ack.message = 'Carbonize cleanup must be verified, then the session must be completed explicitly before polling again.';
+  }
+  return ack;
+}

.agents/skills/impeccable/scripts/live-inject.mjs

@@ -2,23 +2,24 @@
  * CLI helper: insert/remove the live variant mode script tag in the project's
  * main HTML entry point.
  *
- * On first live run, the agent generates `config.json` in this script's
- * directory with the project's insertion target (framework-specific). On
+ * On first live run, the agent generates `.impeccable/live/config.json`
+ * with the project's insertion target (framework-specific). On
  * every subsequent run, this script handles insert/remove deterministically
  * with zero LLM involvement.
  *
  * Usage:
  *   node live-inject.mjs --port PORT   # Insert the live script tag
  *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether config.json exists
+ *   node live-inject.mjs --check       # Check whether live config exists
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveLiveConfigPath } from './impeccable-paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_PATH = process.env.IMPECCABLE_LIVE_CONFIG || path.join(__dirname, 'config.json');
+const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
 const MARKER_OPEN_TEXT = 'impeccable-live-start';
 const MARKER_CLOSE_TEXT = 'impeccable-live-end';
 
@@ -39,12 +40,12 @@ export async function injectCli() {
     console.log(`Usage: node live-inject.mjs [options]
 
 Insert or remove the live mode script tag in the project's HTML entry point.
-Reads configuration from config.json (in this same directory).
+Reads configuration from .impeccable/live/config.json.
 
 Modes:
   --port PORT   Insert script tag pointing at http://localhost:PORT/live.js
   --remove      Remove the script tag (if present)
-  --check       Print whether config.json exists and its content
+  --check       Print whether .impeccable/live/config.json exists and its content
 
 Output (JSON):
   { ok, file, inserted|removed, config? }`);
@@ -388,7 +389,16 @@ export function patchCspMeta(content, port) {
 
     const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
     const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
-    const newAttrs = attrs.replace(contentAttr.full, newContentAttr) + ' ' + marker;
+    // The tagRe captures any whitespace between the last attribute and the
+    // closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
+    // a replace would land it BEFORE that trailing space, leaving a double
+    // space inside attrs and clobbering the space before `/>`. Split off
+    // the trailing whitespace, splice the marker into the attribute body,
+    // and re-append the original trailing whitespace so a self-closing
+    // `<meta … />` round-trips byte-for-byte.
+    const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
+    const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
+    const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
     const newTag = tag.full.replace(attrs, newAttrs);
 
     result = result.slice(0, tag.start) + newTag + result.slice(tag.end);

.agents/skills/impeccable/scripts/live-poll.mjs

@@ -8,11 +8,11 @@
  *   npx impeccable poll --reply <id> error "msg" # Reply with error
  */
 
-import { execSync } from 'node:child_process';
-import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import path from 'node:path';
-import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live-completion.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
 
 // Node's built-in fetch (undici under the hood) enforces a 300s headers
 // timeout that can't be lowered per-request. We cap each request below
@@ -20,15 +20,29 @@ import { fileURLToPath } from 'node:url';
 // depending on the standalone undici package.
 const PER_REQUEST_TIMEOUT_MS = 270_000;
 
-const LIVE_PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-
 function readServerInfo() {
-  try {
-    return JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
-  } catch {
+  const record = readLiveServerInfo(process.cwd());
+  if (!record) {
     console.error('No running live server found. Start one with: npx impeccable live');
     process.exit(1);
   }
+  return record.info;
+}
+
+export function buildPollReplyPayload(token, { id, type, message, file, data }) {
+  return { token, id, type, message, file, data };
+}
+
+async function postReply(base, token, reply) {
+  const res = await fetch(`${base}/poll`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(buildPollReplyPayload(token, reply)),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || res.statusText);
+  }
 }
 
 export async function pollCli() {
@@ -69,23 +83,7 @@ Options:
     }
 
     try {
-      const res = await fetch(`${base}/poll`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          token: info.token,
-          id,
-          type: status,
-          message,
-          file: filePath,
-        }),
-      });
-
-      if (!res.ok) {
-        const body = await res.json().catch(() => ({}));
-        console.error(`Reply failed (${res.status}):`, body.error || res.statusText);
-        process.exit(1);
-      }
+      await postReply(base, info.token, { id, type: status, message, file: filePath });
 
       // Success — silent exit (agent doesn't need output for replies)
     } catch (err) {
@@ -146,18 +144,33 @@ Options:
         ? ['--id', event.id, '--discard']
         : ['--id', event.id, '--variant', event.variantId];
       if (event.type === 'accept' && event.paramValues && Object.keys(event.paramValues).length > 0) {
-        // Pass through a JSON blob; the shell-safe wrap uses single quotes because
-        // values are finite {id, number|string|boolean} pairs from a validated payload.
-        scriptArgs.push('--param-values', `'${JSON.stringify(event.paramValues).replace(/'/g, "'\\''")}'`);
+        scriptArgs.push('--param-values', JSON.stringify(event.paramValues));
       }
       try {
-        const out = execSync(
-          `node "${acceptScript}" ${scriptArgs.join(' ')}`,
+        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, error: err.message };
+        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);
       }
     }
 
@@ -165,7 +178,7 @@ Options:
     // 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. See reference/live.md "Required after accept".\n\n');
+      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

.agents/skills/impeccable/scripts/live-resume.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Recover the next agent action from the durable live-session journal.
+ */
+
+import { createLiveSessionStore } from './live-session-store.mjs';
+
+function parseArgs(argv) {
+  const out = { id: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--id') out.id = argv[++i];
+    else if (arg.startsWith('--id=')) out.id = arg.slice('--id='.length);
+    else if (arg === '--help' || arg === '-h') out.help = true;
+  }
+  return out;
+}
+
+export async function resumeCli() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(`Usage: node live-resume.mjs [--id SESSION_ID]\n\nPrint the active durable session checkpoint and the next safe agent action.`);
+    return;
+  }
+
+  const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id || undefined });
+  const snapshot = args.id ? store.getSnapshot(args.id) : store.listActiveSessions()[0] || null;
+  if (!snapshot) {
+    console.log(JSON.stringify({ active: false, nextAction: 'No active durable live session found.' }, null, 2));
+    return;
+  }
+
+  const pending = snapshot.pendingEvent || null;
+  const nextAction = pending
+    ? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
+    : snapshot.phase === 'carbonize_required'
+      ? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
+      : snapshot.phase === 'accept_requested'
+        ? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
+        : `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
+
+  console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
+  resumeCli();
+}

.agents/skills/impeccable/scripts/live-server.mjs

@@ -21,11 +21,22 @@ 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 { createLiveSessionStore } from './live-session-store.mjs';
+import {
+  getDesignSidecarPath,
+  getLiveAnnotationsDir,
+  readLiveServerInfo,
+  removeLiveServerInfo,
+  resolveDesignSidecarPath,
+  writeLiveServerInfo,
+} from './impeccable-paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// PID file in the project root so both the server and agent can find it
-// predictably (os.tmpdir() varies across platforms).
-const LIVE_PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
+// PRODUCT.md / DESIGN.md live wherever load-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());
 const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
 const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
 
@@ -52,10 +63,12 @@ const state = {
   token: null,
   port: null,
   sseClients: new Set(),   // SSE response objects (server→browser push)
-  pendingEvents: [],        // browser events waiting for agent poll
+  pendingEvents: [],        // browser events waiting for agent ack ({ event, leaseUntil })
   pendingPolls: [],         // agent poll callbacks waiting for browser events
   exitTimer: null,
   sessionDir: null,         // per-session tmp dir for annotation screenshots
+  sessionStore: null,
+  leaseTimer: null,
 };
 
 // Cap per-annotation upload size. A full 1920×1080 PNG is typically <1 MB;
@@ -63,13 +76,72 @@ const state = {
 const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
 
 function enqueueEvent(event) {
-  if (state.pendingPolls.length > 0) {
-    state.pendingPolls.shift()(event);
-  } else {
-    state.pendingEvents.push(event);
+  if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
+  state.pendingEvents.push({ event, leaseUntil: 0 });
+  flushPendingPolls();
+}
+
+function restorePendingEventsFromStore() {
+  if (!state.sessionStore) return;
+  for (const snapshot of state.sessionStore.listActiveSessions()) {
+    if (snapshot.pendingEvent) enqueueEvent(snapshot.pendingEvent);
   }
 }
 
+function findAvailablePendingEvent(now = Date.now()) {
+  return state.pendingEvents.find((entry) => !entry.leaseUntil || entry.leaseUntil <= now);
+}
+
+function leaseEvent(entry, leaseMs) {
+  if (!entry.event?.id) {
+    const idx = state.pendingEvents.indexOf(entry);
+    if (idx !== -1) state.pendingEvents.splice(idx, 1);
+    return entry.event;
+  }
+  entry.leaseUntil = Date.now() + leaseMs;
+  return entry.event;
+}
+
+function acknowledgePendingEvent(id) {
+  if (!id) return false;
+  const idx = state.pendingEvents.findIndex((entry) => entry.event?.id === id);
+  if (idx === -1) return false;
+  state.pendingEvents.splice(idx, 1);
+  scheduleLeaseFlush();
+  return true;
+}
+
+function scheduleLeaseFlush() {
+  if (state.leaseTimer) {
+    clearTimeout(state.leaseTimer);
+    state.leaseTimer = null;
+  }
+  if (state.pendingPolls.length === 0) return;
+  const now = Date.now();
+  const nextLeaseUntil = state.pendingEvents
+    .map((entry) => entry.leaseUntil || 0)
+    .filter((leaseUntil) => leaseUntil > now)
+    .sort((a, b) => a - b)[0];
+  if (!nextLeaseUntil) return;
+  state.leaseTimer = setTimeout(() => {
+    state.leaseTimer = null;
+    flushPendingPolls();
+  }, Math.max(0, nextLeaseUntil - now));
+}
+
+function flushPendingPolls() {
+  while (state.pendingPolls.length > 0) {
+    const entry = findAvailablePendingEvent();
+    if (!entry) {
+      scheduleLeaseFlush();
+      return;
+    }
+    const poll = state.pendingPolls.shift();
+    poll.resolve(leaseEvent(entry, poll.leaseMs));
+  }
+  scheduleLeaseFlush();
+}
+
 /** Push a message to all connected SSE clients. */
 function broadcast(msg) {
   const data = 'data: ' + JSON.stringify(msg) + '\n\n';
@@ -84,11 +156,11 @@ function broadcast(msg) {
 
 function loadBrowserScripts() {
   // Detection script: look relative to the skill scripts dir, then fall back
-  // to the npm package location (src/detect-antipatterns-browser.js).
+  // to the npm package location (cli/engine/detect-antipatterns-browser.js).
   // This one IS cached — detect.js rarely changes during a session.
   const detectPaths = [
-    path.join(__dirname, '..', '..', '..', '..', 'src', 'detect-antipatterns-browser.js'),
-    path.join(process.cwd(), 'node_modules', 'impeccable', 'src', 'detect-antipatterns-browser.js'),
+    path.join(__dirname, '..', '..', '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
+    path.join(process.cwd(), 'node_modules', 'impeccable', 'cli', 'engine', 'detect-antipatterns-browser.js'),
   ];
   let detectScript = '';
   for (const p of detectPaths) {
@@ -98,13 +170,16 @@ function loadBrowserScripts() {
   // live-browser.js: DO NOT cache. Return the path so the /live.js handler
   // can re-read on every request. Editing the browser script during iteration
   // should land on the next tab reload, not require a server restart.
+  const sessionPath = path.join(__dirname, 'live-browser-session.js');
   const livePath = path.join(__dirname, 'live-browser.js');
-  if (!fs.existsSync(livePath)) {
-    process.stderr.write('Error: live-browser.js not found at ' + livePath + '\n');
-    process.exit(1);
+  for (const p of [sessionPath, livePath]) {
+    if (!fs.existsSync(p)) {
+      process.stderr.write('Error: live browser script not found at ' + p + '\n');
+      process.exit(1);
+    }
   }
 
-  return { detectScript, livePath };
+  return { detectScript, sessionPath, livePath };
 }
 
 function hasProjectContext() {
@@ -113,7 +188,7 @@ function hasProjectContext() {
   // concern, surfaced by the design panel's own empty state. Legacy
   // .impeccable.md is auto-migrated to PRODUCT.md by load-context.mjs.
   try {
-    fs.accessSync(path.join(process.cwd(), 'PRODUCT.md'), fs.constants.R_OK);
+    fs.accessSync(path.join(CONTEXT_DIR, 'PRODUCT.md'), fs.constants.R_OK);
     return true;
   } catch { return false; }
 }
@@ -131,11 +206,21 @@ const VISUAL_ACTIONS = [
   '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 (!msg.id || typeof msg.id !== 'string') return 'generate: missing id';
+      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';
@@ -145,8 +230,8 @@ function validateEvent(msg) {
       if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) return 'generate: strokes must be array';
       return null;
     case 'accept':
-      if (!msg.id) return 'accept: missing id';
-      if (!msg.variantId) return 'accept: missing variantId';
+      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';
@@ -154,7 +239,14 @@ function validateEvent(msg) {
       }
       return null;
     case 'discard':
-      return msg.id ? null : 'discard: missing id';
+      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':
@@ -169,7 +261,7 @@ function validateEvent(msg) {
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
-function createRequestHandler({ detectScript, livePath }) {
+function createRequestHandler({ detectScript, sessionPath, livePath }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
     res.setHeader('Access-Control-Allow-Origin', '*');
@@ -185,17 +277,20 @@ function createRequestHandler({ detectScript, livePath }) {
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
       // every subsequent session.
+      let sessionScript;
       let liveScript;
       try {
+        sessionScript = fs.readFileSync(sessionPath, 'utf-8');
         liveScript = fs.readFileSync(livePath, 'utf-8');
       } catch (err) {
         res.writeHead(500, { 'Content-Type': 'text/plain' });
-        res.end('Error reading live-browser.js: ' + err.message);
+        res.end('Error reading live browser scripts: ' + err.message);
         return;
       }
       const body =
         `window.__IMPECCABLE_TOKEN__ = '${state.token}';\n` +
         `window.__IMPECCABLE_PORT__ = ${state.port};\n` +
+        sessionScript + '\n' +
         liveScript;
       res.writeHead(200, {
         'Content-Type': 'application/javascript',
@@ -290,6 +385,26 @@ function createRequestHandler({ detectScript, livePath }) {
     }
 
     // --- Health ---
+    if (p === '/status') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
+      const sessions = state.sessionStore ? state.sessionStore.listActiveSessions() : [];
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        status: 'ok',
+        port: state.port,
+        connectedClients: state.sseClients.size,
+        pendingEvents: state.pendingEvents.map((entry) => ({
+          id: entry.event?.id,
+          type: entry.event?.type,
+          leased: !!(entry.leaseUntil && entry.leaseUntil > Date.now()),
+          leaseUntil: entry.leaseUntil || null,
+        })),
+        activeSessions: sessions,
+      }));
+      return;
+    }
+
     if (p === '/health') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({
@@ -301,13 +416,13 @@ function createRequestHandler({ detectScript, livePath }) {
     }
 
     // --- Design system (unified v2 response) + raw ---
-    //   /design-system.json    returns both parsed DESIGN.md and DESIGN.json
+    //   /design-system.json    returns both parsed DESIGN.md and .impeccable/design.json
     //                          sidecar when present. Panel merges them:
     //                            { present, parsed, sidecar, hasMd, hasSidecar,
     //                              mdNewerThanJson, parseError?, sidecarError? }
     //                          - parsed: output of parseDesignMd (frontmatter
     //                            + six canonical sections) when DESIGN.md exists.
-    //                          - sidecar: DESIGN.json contents when present.
+    //                          - sidecar: .impeccable/design.json contents when present.
     //                            Expected shape: schemaVersion 2, carrying
     //                            extensions + components + narrative.
     //   /design-system/raw     returns DESIGN.md markdown verbatim
@@ -315,8 +430,8 @@ function createRequestHandler({ detectScript, livePath }) {
       const token = url.searchParams.get('token');
       if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
 
-      const mdPath = path.join(process.cwd(), 'DESIGN.md');
-      const jsonPath = path.join(process.cwd(), 'DESIGN.json');
+      const mdPath = path.join(CONTEXT_DIR, 'DESIGN.md');
+      const jsonPath = resolveDesignSidecarPath(process.cwd(), CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 
@@ -352,7 +467,7 @@ function createRequestHandler({ detectScript, livePath }) {
         try {
           response.sidecar = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
         } catch (err) {
-          response.sidecarError = 'Failed to parse DESIGN.json: ' + err.message;
+          response.sidecarError = 'Failed to parse .impeccable/design.json: ' + err.message;
         }
       }
 
@@ -434,7 +549,16 @@ function createRequestHandler({ detectScript, livePath }) {
           res.end(JSON.stringify({ error }));
           return;
         }
-        enqueueEvent(msg);
+        if (state.sessionStore && msg.id) {
+          try {
+            state.sessionStore.appendEvent(msg);
+          } catch (err) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'session_store_append_failed', message: err.message }));
+            return;
+          }
+        }
+        if (msg.type !== 'checkpoint') enqueueEvent(msg);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ ok: true }));
       });
@@ -477,13 +601,16 @@ function handlePollGet(req, res, url) {
     return;
   }
   const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
-  if (state.pendingEvents.length > 0) {
+  const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
+  const available = findAvailablePendingEvent();
+  if (available) {
     res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify(state.pendingEvents.shift()));
+    res.end(JSON.stringify(leaseEvent(available, leaseMs)));
     return;
   }
+  const poll = { resolve, leaseMs };
   const timer = setTimeout(() => {
-    const idx = state.pendingPolls.indexOf(resolve);
+    const idx = state.pendingPolls.indexOf(poll);
     if (idx !== -1) state.pendingPolls.splice(idx, 1);
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ type: 'timeout' }));
@@ -493,10 +620,11 @@ function handlePollGet(req, res, url) {
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(event));
   }
-  state.pendingPolls.push(resolve);
+  state.pendingPolls.push(poll);
+  scheduleLeaseFlush();
   req.on('close', () => {
     clearTimeout(timer);
-    const idx = state.pendingPolls.indexOf(resolve);
+    const idx = state.pendingPolls.indexOf(poll);
     if (idx !== -1) state.pendingPolls.splice(idx, 1);
   });
 }
@@ -516,6 +644,26 @@ function handlePollPost(req, res) {
       res.end(JSON.stringify({ error: 'Unauthorized' }));
       return;
     }
+    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';
+        state.sessionStore.appendEvent({
+          type: eventType,
+          id: msg.id,
+          file: msg.file,
+          message: msg.message,
+          carbonize: msg.data?.carbonize === true,
+        });
+      } catch { /* keep reply path best-effort; browser still needs SSE */ }
+    }
+    flushPendingPolls();
     // Forward the reply to the browser via SSE
     broadcast({ type: msg.type || 'done', id: msg.id, message: msg.message, file: msg.file, data: msg.data });
     res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -530,13 +678,15 @@ function handlePollPost(req, res) {
 let httpServer = null;
 
 function shutdown() {
-  try { fs.unlinkSync(LIVE_PID_FILE); } catch {}
+  removeLiveServerInfo(process.cwd());
+  if (state.leaseTimer) clearTimeout(state.leaseTimer);
+  state.leaseTimer = null;
   if (state.sessionDir) {
     try { fs.rmSync(state.sessionDir, { recursive: true, force: true }); } catch {}
   }
   for (const res of state.sseClients) { try { res.end(); } catch {} }
   state.sseClients.clear();
-  for (const resolve of state.pendingPolls) resolve({ type: 'exit' });
+  for (const poll of state.pendingPolls) poll.resolve({ type: 'exit' });
   state.pendingPolls.length = 0;
   if (httpServer) httpServer.close();
   process.exit(0);
@@ -572,6 +722,7 @@ Endpoints:
   /events              SSE stream (server→browser) + POST (browser→server)
   /poll                Long-poll for agent CLI
   /source              Raw source file reader (no-HMR fallback)
+  /status              Durable recovery status (token-protected)
   /health              Health check`);
   process.exit(0);
 }
@@ -579,7 +730,7 @@ Endpoints:
 if (args.includes('stop')) {
   const keepInject = args.includes('--keep-inject');
   try {
-    const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
+    const { info } = readLiveServerInfo(process.cwd()) || {};
     const res = await fetch(`http://localhost:${info.port}/stop?token=${info.token}`);
     if (res.ok) console.log(`Stopped live server on port ${info.port}.`);
   } catch {
@@ -630,7 +781,7 @@ if (args.includes('--background')) {
   const deadline = Date.now() + 10_000;
   while (Date.now() < deadline) {
     try {
-      const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
+      const { info } = readLiveServerInfo(process.cwd()) || {};
       if (info.pid !== process.pid) {
         // Output JSON so the agent can read port + token from stdout.
         console.log(JSON.stringify(info));
@@ -644,30 +795,36 @@ if (args.includes('--background')) {
 }
 
 // Check for existing session
-try {
-  const existing = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
-  try { process.kill(existing.pid, 0);
+const existingRecord = readLiveServerInfo(process.cwd());
+if (existingRecord?.info) {
+  const existing = existingRecord.info;
+  try {
+    process.kill(existing.pid, 0);
     console.error(`Live server already running on port ${existing.port} (pid ${existing.pid}).`);
     console.error('Stop it first with: node ' + path.basename(fileURLToPath(import.meta.url)) + ' stop');
     process.exit(1);
-  } catch { fs.unlinkSync(LIVE_PID_FILE); }
-} catch {}
+  } catch {
+    try { fs.unlinkSync(existingRecord.path); } catch {}
+  }
+}
 
 state.token = randomUUID();
+state.sessionStore = createLiveSessionStore({ cwd: process.cwd() });
+restorePendingEventsFromStore();
 const portArg = args.find(a => a.startsWith('--port='));
 state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
 // Annotation screenshots live in the project root so the agent's Read tool
 // doesn't trip a per-file permission prompt. Sessioned by token so concurrent
 // projects (or quick restarts) don't collide.
-const annotRoot = path.join(process.cwd(), '.impeccable-live', 'annotations');
+const annotRoot = getLiveAnnotationsDir(process.cwd());
 fs.mkdirSync(annotRoot, { recursive: true });
 state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
 
-const { detectScript, livePath } = loadBrowserScripts();
-httpServer = http.createServer(createRequestHandler({ detectScript, livePath }));
+const { detectScript, sessionPath, livePath } = loadBrowserScripts();
+httpServer = http.createServer(createRequestHandler({ detectScript, sessionPath, livePath }));
 
 httpServer.listen(state.port, '127.0.0.1', () => {
-  fs.writeFileSync(LIVE_PID_FILE, JSON.stringify({ pid: process.pid, port: state.port, token: state.token }));
+  writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
   const url = `http://localhost:${state.port}`;
   console.log(`\nImpeccable live server running on ${url}`);
   console.log(`Token: ${state.token}\n`);

.agents/skills/impeccable/scripts/live-session-store.mjs

@@ -0,0 +1,254 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLegacyLiveSessionsDir, getLiveSessionsDir } from './impeccable-paths.mjs';
+
+const COMPLETED_PHASES = new Set(['completed', 'discarded']);
+
+export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
+  const rootDir = getLiveSessionsDir(cwd);
+  const legacyRootDir = getLegacyLiveSessionsDir(cwd);
+  fs.mkdirSync(rootDir, { recursive: true });
+  const snapshotCache = new Map();
+
+  function loadCachedOrRebuild(id) {
+    const cached = snapshotCache.get(id);
+    if (cached) return cached;
+    const journalPath = getReadableJournalPath(id);
+    const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
+    snapshotCache.set(id, rebuilt);
+    return rebuilt;
+  }
+
+  function getReadableJournalPath(id) {
+    const primary = getJournalPath(rootDir, id);
+    if (fs.existsSync(primary)) return primary;
+    const legacy = getJournalPath(legacyRootDir, id);
+    if (fs.existsSync(legacy)) return legacy;
+    return primary;
+  }
+
+  return {
+    rootDir,
+    legacyRootDir,
+    appendEvent(event) {
+      const normalized = normalizeEvent(event, sessionId);
+      const journalPath = getJournalPath(rootDir, normalized.id);
+      const snapshotPath = getSnapshotPath(rootDir, normalized.id);
+      const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
+      if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
+        fs.copyFileSync(legacyJournalPath, journalPath);
+      }
+      const prior = loadCachedOrRebuild(normalized.id);
+      const seq = prior.nextSeq;
+      const entry = {
+        seq,
+        id: normalized.id,
+        type: normalized.type,
+        ts: new Date().toISOString(),
+        event: normalized,
+      };
+      fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
+      const next = applyEvent(prior.snapshot, entry, prior.diagnostics);
+      snapshotCache.set(normalized.id, { snapshot: next, diagnostics: next.diagnostics || [], nextSeq: seq + 1 });
+      writeSnapshot(snapshotPath, next);
+      return next;
+    },
+    getSnapshot(id = sessionId, opts = {}) {
+      if (!id) throw new Error('session id required');
+      const journalPath = getReadableJournalPath(id);
+      const snapshotPath = getSnapshotPath(rootDir, id);
+      const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
+      snapshotCache.set(id, rebuilt);
+      writeSnapshot(snapshotPath, rebuilt.snapshot);
+      if (!opts.includeCompleted && COMPLETED_PHASES.has(rebuilt.snapshot.phase)) return null;
+      return rebuilt.snapshot;
+    },
+    listActiveSessions() {
+      const ids = new Set();
+      for (const dir of [legacyRootDir, rootDir]) {
+        if (!fs.existsSync(dir)) continue;
+        for (const name of fs.readdirSync(dir)) {
+          if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
+        }
+      }
+      return [...ids]
+        .sort()
+        .map((id) => this.getSnapshot(id))
+        .filter(Boolean);
+    },
+  };
+}
+
+function normalizeEvent(event, fallbackId) {
+  if (!event || typeof event !== 'object') throw new Error('event object required');
+  const id = event.id || fallbackId;
+  if (!id || typeof id !== 'string') throw new Error('event id required');
+  if (!event.type || typeof event.type !== 'string') throw new Error('event type required');
+  return { ...event, id };
+}
+
+function getJournalPath(rootDir, id) {
+  return path.join(rootDir, safeSessionId(id) + '.jsonl');
+}
+
+function getSnapshotPath(rootDir, id) {
+  return path.join(rootDir, safeSessionId(id) + '.snapshot.json');
+}
+
+function safeSessionId(id) {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new Error('invalid session id: ' + id);
+  return id;
+}
+
+function baseSnapshot(id) {
+  return {
+    id,
+    phase: 'new',
+    pageUrl: null,
+    sourceFile: null,
+    expectedVariants: 0,
+    arrivedVariants: 0,
+    visibleVariant: null,
+    paramValues: {},
+    pendingEventSeq: null,
+    pendingEvent: null,
+    deliveryLease: null,
+    checkpointRevision: 0,
+    activeOwner: null,
+    sourceMarkers: {},
+    fallbackMode: null,
+    annotationArtifacts: [],
+    diagnostics: [],
+    updatedAt: null,
+  };
+}
+
+function rebuildSnapshotFromJournal(journalPath, id) {
+  let snapshot = baseSnapshot(id);
+  const diagnostics = [];
+  let nextSeq = 1;
+  if (!fs.existsSync(journalPath)) return { snapshot, diagnostics, nextSeq };
+
+  const lines = fs.readFileSync(journalPath, 'utf-8').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (!entry || typeof entry !== 'object') throw new Error('entry is not object');
+      if (Number.isInteger(entry.seq)) nextSeq = Math.max(nextSeq, entry.seq + 1);
+      snapshot = applyEvent(snapshot, entry);
+    } catch (err) {
+      diagnostics.push({
+        error: 'journal_parse_failed',
+        line: i + 1,
+        message: err.message,
+      });
+    }
+  }
+  snapshot.diagnostics = [...snapshot.diagnostics, ...diagnostics];
+  return { snapshot, diagnostics, nextSeq };
+}
+
+function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
+  const event = entry.event || entry;
+  const next = {
+    ...snapshot,
+    paramValues: { ...(snapshot.paramValues || {}) },
+    sourceMarkers: { ...(snapshot.sourceMarkers || {}) },
+    annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
+    diagnostics: [...(snapshot.diagnostics || [])],
+    updatedAt: entry.ts || new Date().toISOString(),
+  };
+
+  if (inheritedDiagnostics.length && next.diagnostics.length === 0) {
+    next.diagnostics = [...inheritedDiagnostics];
+  }
+
+  switch (event.type) {
+    case 'generate':
+      next.phase = 'generate_requested';
+      next.pageUrl = event.pageUrl ?? next.pageUrl;
+      next.expectedVariants = event.count ?? next.expectedVariants;
+      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
+      next.pendingEvent = toPendingEvent(event);
+      if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
+      break;
+    case 'variants_ready':
+    case 'agent_done':
+      next.phase = event.carbonize === true ? 'carbonize_required' : 'variants_ready';
+      next.sourceFile = event.file ?? next.sourceFile;
+      next.arrivedVariants = event.arrivedVariants ?? (next.arrivedVariants ?? next.expectedVariants);
+      next.pendingEventSeq = null;
+      next.pendingEvent = null;
+      if (event.carbonize === true) {
+        next.diagnostics.push({
+          error: 'carbonize_cleanup_required',
+          file: event.file || null,
+          message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
+        });
+      }
+      break;
+    case 'checkpoint':
+      if ((event.revision ?? 0) >= (next.checkpointRevision ?? 0)) {
+        next.phase = event.phase ?? next.phase;
+        next.checkpointRevision = event.revision ?? next.checkpointRevision;
+        next.activeOwner = event.owner ?? next.activeOwner;
+        next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
+        next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
+        if (event.paramValues) next.paramValues = { ...event.paramValues };
+      } else {
+        next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision });
+      }
+      break;
+    case 'accept':
+    case 'accept_intent':
+      next.phase = 'accept_requested';
+      next.visibleVariant = Number(event.variantId ?? next.visibleVariant);
+      if (event.paramValues) next.paramValues = { ...event.paramValues };
+      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
+      next.pendingEvent = toPendingEvent(event);
+      break;
+    case 'discard':
+      next.phase = 'discard_requested';
+      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
+      next.pendingEvent = toPendingEvent(event);
+      break;
+    case 'discarded':
+      next.phase = 'discarded';
+      next.pendingEventSeq = null;
+      next.pendingEvent = null;
+      break;
+    case 'complete':
+      next.phase = 'completed';
+      next.pendingEventSeq = null;
+      next.pendingEvent = null;
+      break;
+    case 'agent_error':
+      next.phase = 'agent_error';
+      next.pendingEventSeq = null;
+      next.pendingEvent = null;
+      next.diagnostics.push({ error: 'agent_error', message: event.message || 'unknown agent error' });
+      break;
+    default:
+      next.diagnostics.push({ error: 'unknown_event_type', type: event.type });
+      break;
+  }
+  return next;
+}
+
+function toPendingEvent(event) {
+  const pending = { ...event };
+  delete pending.token;
+  return pending;
+}
+
+function upsertArtifact(artifacts, artifact) {
+  if (!artifacts.some((existing) => existing.path === artifact.path && existing.type === artifact.type)) {
+    artifacts.push(artifact);
+  }
+}
+
+function writeSnapshot(snapshotPath, snapshot) {
+  fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2) + '\n');
+}

.agents/skills/impeccable/scripts/live-status.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Print durable recovery status for Impeccable live sessions.
+ */
+
+import { createLiveSessionStore } from './live-session-store.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
+
+function readServerInfo() {
+  return readLiveServerInfo(process.cwd())?.info || null;
+}
+
+async function fetchServerStatus(info) {
+  if (!info) return null;
+  try {
+    const res = await fetch(`http://localhost:${info.port}/status?token=${info.token}`);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+export async function statusCli() {
+  const info = readServerInfo();
+  const server = await fetchServerStatus(info);
+  const store = createLiveSessionStore({ cwd: process.cwd() });
+  const activeSessions = store.listActiveSessions();
+  const payload = {
+    liveServer: server ? {
+      status: server.status,
+      port: server.port,
+      connectedClients: server.connectedClients,
+      pendingEvents: server.pendingEvents,
+    } : null,
+    activeSessions: server?.activeSessions || activeSessions,
+    recoveryHint: server
+      ? 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.'
+      : 'Start live-server.mjs to requeue pending durable events, then run live-poll.mjs.',
+  };
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-status.mjs') || _running?.endsWith('live-status.mjs/')) {
+  statusCli();
+}

.agents/skills/impeccable/scripts/live-wrap.mjs

@@ -37,6 +37,10 @@ Element identification (at least one required):
 
 Optional:
   --file PATH        Source file to search in (skips auto-detection)
+  --text TEXT        Picked element's textContent. Used to disambiguate when
+                     classes/tag match multiple sibling elements (e.g. a list
+                     of <Card>s with the same className). Pass the first ~80
+                     chars of event.element.textContent.
   --help             Show this help message
 
 Output (JSON):
@@ -53,6 +57,7 @@ The agent should insert variant HTML at insertLine.`);
   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 (!elementId && !classes && !query) {
@@ -115,35 +120,117 @@ The agent should insert variant HTML at insertLine.`);
   const content = fs.readFileSync(targetFile, 'utf-8');
   const lines = content.split('\n');
 
-  // Find the element, trying each query in priority order.
-  // Pass tag hint so findElement can reject matches inside wrong element types
-  // and walk backward to the real opener on multi-line JSX tags.
+  // Find the element, trying each query in priority order. When `--text` is
+  // supplied, collect every candidate the queries surface and disambiguate
+  // by the picked element's textContent. Without `--text`, fall back to the
+  // legacy first-match behavior so unmodified callers keep working.
   let match = null;
-  for (const q of queries) {
-    match = findElement(lines, q, tag);
-    if (match) break;
-  }
-  if (!match) {
-    console.error(JSON.stringify({ error: 'Found file but could not locate element in ' + targetFile + '. Searched for: ' + queries.join(', ') }));
-    process.exit(1);
+  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);
+        }
+      }
+      // Once a more-specific query (ID, full className combo) yielded a unique
+      // result, stop — falling through to the loose tag+single-class query
+      // would readmit the siblings we just disambiguated past.
+      if (candidates.length === 1) break;
+    }
+    if (candidates.length === 0) {
+      console.error(JSON.stringify({ error: 'Found file but could not locate element in ' + targetFile + '. Searched for: ' + queries.join(', ') }));
+      process.exit(1);
+    }
+    if (candidates.length === 1) {
+      match = candidates[0];
+    } else {
+      const filtered = filterByText(candidates, lines, text);
+      if (filtered.length === 1) {
+        match = filtered[0];
+      } else if (filtered.length === 0) {
+        // Source uses dynamic content (`<h1>{title}</h1>` etc.) so the
+        // browser-side textContent doesn't appear literally in source. Fall
+        // back to first-match rather than refusing — this is the same
+        // behavior unmodified callers see, just preserved.
+        match = candidates[0];
+      } else {
+        // Multiple candidates ALSO match the text. Truly ambiguous — refuse
+        // rather than pick wrong, and hand the agent the candidate locations
+        // so it can disambiguate by reading the file.
+        console.error(JSON.stringify({
+          error: 'element_ambiguous',
+          fallback: 'agent-driven',
+          file: path.relative(process.cwd(), targetFile),
+          candidates: filtered.map((c) => ({
+            startLine: c.startLine + 1,
+            endLine: c.endLine + 1,
+          })),
+          hint: 'Multiple source elements match both classes/tag and textContent. Pass --element-id, a more specific --text, or write the wrapper manually. See "Handle fallback" in live.md.',
+        }));
+        process.exit(1);
+      }
+    }
+  } else {
+    for (const q of queries) {
+      match = findElement(lines, q, tag);
+      if (match) break;
+    }
+    if (!match) {
+      console.error(JSON.stringify({ error: 'Found file but could not locate element in ' + targetFile + '. Searched for: ' + queries.join(', ') }));
+      process.exit(1);
+    }
   }
 
   const { startLine, endLine } = match;
   const commentSyntax = detectCommentSyntax(targetFile);
+  const styleMode = detectStyleMode(targetFile);
   const isJsx = commentSyntax.open === '{/*';
   const indent = lines[startLine].match(/^(\s*)/)[1];
 
-  // Extract the original element
+  // Extract the original element. Reindent under the wrapper while preserving
+  // the relative depth between lines — `l.trimStart()` would strip ALL leading
+  // whitespace and collapse e.g. `<aside>`/`  <h1>`/`</aside>` (6/8/6 spaces)
+  // to a single uniform indent, so on accept/discard the round-trip restores
+  // the inner element at its parent's depth instead of nested inside it.
+  // Strip only the COMMON minimum leading whitespace across the picked lines;
+  // `deindentContent` on the accept side already mirrors this convention.
   const originalLines = lines.slice(startLine, endLine + 1);
-  const originalIndented = originalLines.map(l => indent + '    ' + l.trimStart()).join('\n');
+  const originalBaseIndent = minLeadingSpaces(originalLines);
+  const reindentOriginal = (extra) => originalLines
+    .map((l) => (l.trim() === '' ? '' : indent + extra + l.slice(originalBaseIndent)))
+    .join('\n');
+  const originalIndented = reindentOriginal('    ');
 
   // Wrapper attributes differ by syntax. HTML allows plain string attrs;
   // JSX requires object-literal style and parses string attrs as HTML (which
   // either type-errors or renders a literal CSS string).
   const styleContents = isJsx ? 'style={{ display: "contents" }}' : 'style="display: contents"';
 
-  // Build the wrapper
-  const wrapperLines = [
+  // JSX/TSX guard: the picked element occupies a single JSX child slot
+  // (inside `return (...)`, an array `.map(...)`, an `asChild` branch, or
+  // any other expression position). Replacing it with `comment + <div> +
+  // comment` yields three adjacent siblings — invalid JSX. We can't use a
+  // Fragment `<></>` either: parents that clone children (Radix `asChild`,
+  // Headless UI, etc.) hit "Invalid prop supplied to React.Fragment" when
+  // they try to pass an `id` through.
+  //
+  // Solution: keep the wrapper `<div>` as the single JSX-slot child and
+  // tuck both marker comments INSIDE it. accept/discard then expands its
+  // replacement range to include the wrapper's `<div>` open / close lines
+  // so the entire scaffold gets removed cleanly.
+  const wrapperLines = isJsx ? [
+    indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
+    indent + '  ' + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+    indent + '  ' + commentSyntax.open + ' Original ' + commentSyntax.close,
+    indent + '  <div data-impeccable-variant="original">',
+    reindentOriginal('    '),
+    indent + '  </div>',
+    indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+    indent + '  ' + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+    indent + '</div>',
+  ] : [
     indent + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
     indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
     indent + '  ' + commentSyntax.open + ' Original ' + commentSyntax.close,
@@ -163,15 +250,30 @@ The agent should insert variant HTML at insertLine.`);
   ];
   fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
 
-  // Calculate insert line (the "insert below this line" comment)
-  const insertLine = startLine + 6; // 0-indexed in the new file
+  // Calculate insert line (the "insert below this line" comment).
+  // 0-indexed file position. Both HTML and JSX wrappers have 6 lines above
+  // the insert marker (HTML: start-comment + outer-div + Original-comment +
+  // original-div + content + close-original-div; JSX: outer-div +
+  // start-comment + Original-comment + original-div + content +
+  // close-original-div). Multi-line originals push the marker by their
+  // extra line count.
+  const insertLine = startLine + 6 + (originalLines.length - 1);
 
   console.log(JSON.stringify({
     file: path.relative(process.cwd(), targetFile),
     startLine: startLine + 1,       // 1-indexed for the agent
-    endLine: startLine + wrapperLines.length, // 1-indexed
+    // wrapperLines is an array but one element (the original-content slot)
+    // is a `\n`-joined multi-line string, so the actual file-row count is
+    // wrapperLines.length + (originalLines.length - 1). Without the offset,
+    // endLine pointed inside the wrapper for any picked element that
+    // spanned more than one source line.
+    endLine: startLine + wrapperLines.length + (originalLines.length - 1), // 1-indexed
     insertLine: insertLine + 1,     // 1-indexed: where variants go
     commentSyntax: commentSyntax,
+    styleMode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    cssSelectorPrefixExamples: buildCssSelectorPrefixExamples(styleMode.mode, count),
+    cssAuthoring: buildCssAuthoring(styleMode, count),
     originalLineCount: originalLines.length,
   }));
 }
@@ -238,6 +340,62 @@ function detectCommentSyntax(filePath) {
   return { open: '<!--', close: '-->' };
 }
 
+function detectStyleMode(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.astro') {
+    return {
+      mode: 'astro-global-prefixed',
+      styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
+    };
+  }
+  return {
+    mode: 'scoped',
+    styleTag: '<style data-impeccable-css="SESSION_ID">',
+  };
+}
+
+function buildCssSelectorPrefixExamples(styleMode, count) {
+  if (styleMode !== 'astro-global-prefixed') return [];
+  return Array.from({ length: count }, (_, i) => `[data-impeccable-variant="${i + 1}"]`);
+}
+
+function buildCssAuthoring(styleMode, count) {
+  const variantNumbers = Array.from({ length: count }, (_, i) => i + 1);
+  if (styleMode.mode === 'astro-global-prefixed') {
+    return {
+      mode: styleMode.mode,
+      styleTag: styleMode.styleTag,
+      strategy: 'global-prefixed',
+      rulePattern: '[data-impeccable-variant="N"] > .variant-class { ... }',
+      selectorExamples: variantNumbers.map((n) => `[data-impeccable-variant="${n}"] > .variant-class`),
+      requirements: [
+        'Use the styleTag exactly; the is:inline attribute is required for this file.',
+        '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.',
+      ],
+    };
+  }
+  return {
+    mode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    strategy: 'scope-rule',
+    rulePattern: '@scope ([data-impeccable-variant="N"]) { :scope > .variant-class { ... } }',
+    selectorExamples: variantNumbers.map((n) => `@scope ([data-impeccable-variant="${n}"]) { :scope > .variant-class { ... } }`),
+    requirements: [
+      'Use @scope blocks keyed to each [data-impeccable-variant="N"] wrapper.',
+      'Inside each @scope block, make :scope rules step into the replacement element with a descendant combinator.',
+      'Use the styleTag exactly; do not add framework-specific style attributes unless this object says to.',
+    ],
+    forbidden: [
+      'Do not use global [data-impeccable-variant="N"] selector prefixes for this styleMode.',
+      'Do not add is:inline to the style tag for this styleMode.',
+    ],
+  };
+}
+
 /**
  * Search project files for the query string (class name, ID, etc.)
  * Returns the first matching file path, or null.
@@ -310,6 +468,22 @@ const OPENER_RE = /<([A-Za-z][A-Za-z0-9]*)(?=[\s/>]|$)/;
  * line to find the actual tag opener. When `tag` is provided, opener candidates
  * must match that tag name.
  */
+/**
+ * Return the smallest leading-whitespace count across a set of lines,
+ * ignoring blank lines (whose indent isn't load-bearing). Used to compute
+ * the common base indent of a multi-line picked element so reindenting
+ * under the wrapper preserves the relative depth between lines.
+ */
+function minLeadingSpaces(lines) {
+  let min = Infinity;
+  for (const l of lines) {
+    if (l.trim() === '') continue;
+    const m = l.match(/^(\s*)/);
+    if (m && m[1].length < min) min = m[1].length;
+  }
+  return min === Infinity ? 0 : min;
+}
+
 function findElement(lines, query, tag = null) {
   // Iterate all matches — the first substring hit isn't always the right one.
   for (let i = 0; i < lines.length; i++) {
@@ -330,6 +504,69 @@ function findElement(lines, query, tag = null) {
   return null;
 }
 
+/**
+ * Like findElement, but returns every match. Used for ambiguity detection
+ * when the agent passes --text: when the same className appears on multiple
+ * sibling elements (a list of cards, repeated section variants, etc.),
+ * first-match silently lands on the wrong branch. Returning all matches lets
+ * the caller narrow by textContent or fail with a structured ambiguity error.
+ */
+function findAllElements(lines, query, tag = null) {
+  const out = [];
+  const seen = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes(query)) continue;
+    const stripped = lines[i].trim();
+    if (stripped.startsWith('<!--') || stripped.startsWith('{/*') || stripped.startsWith('//')) continue;
+    if (lines[i].includes('data-impeccable-variant')) continue;
+    const openerLine = findOpenerLine(lines, i, tag);
+    if (openerLine === -1) continue;
+    if (seen.has(openerLine)) continue; // multiple matches inside the same element
+    seen.add(openerLine);
+    const endLine = findClosingLine(lines, openerLine);
+    out.push({ startLine: openerLine, endLine });
+  }
+  return out;
+}
+
+/**
+ * Narrow a candidate set to those whose source body matches a meaningful
+ * prefix of the picked element's textContent. The compare strips tags and
+ * JSX expressions, then checks two whitespace normalizations side-by-side:
+ *
+ *   - single-space ("hero two second card body")
+ *   - no-whitespace ("herotwosecondcardbody")
+ *
+ * Both are needed because `el.textContent` concatenates sibling text without
+ * inserting whitespace (e.g. `<h1>Hero Two</h1><p>Second…</p>` reads as
+ * `"Hero TwoSecond…"`), while the source has whitespace between tags. If
+ * EITHER normalization matches, the candidate keeps. A snippet shorter than
+ * 8 chars after stripping is too weak to disambiguate — the caller falls
+ * back to first-match.
+ */
+function filterByText(candidates, lines, text) {
+  const trimmed = text.replace(/\s+/g, ' ').trim().toLowerCase().slice(0, 80);
+  // Too short to disambiguate. Return [] so the caller's `filtered.length
+  // === 0` branch fires (fall back to first-match) — the previous
+  // `candidates.slice()` return forced `filtered.length > 1` and surfaced
+  // a spurious `element_ambiguous` error on every short-text picker event
+  // with multiple candidates.
+  if (trimmed.length < 8) return [];
+  const targetSpaced = trimmed;
+  const targetCompact = trimmed.replace(/\s+/g, '');
+
+  return candidates.filter((c) => {
+    const body = lines.slice(c.startLine, c.endLine + 1).join(' ');
+    const inner = body
+      .replace(/<[^>]*>/g, ' ')   // strip HTML/JSX tags
+      .replace(/\{[^}]*\}/g, ' ')  // strip JSX expressions
+      .toLowerCase();
+    const sourceSpaced = inner.replace(/\s+/g, ' ').trim();
+    const sourceCompact = inner.replace(/\s+/g, '');
+    return sourceSpaced.includes(targetSpaced) || sourceCompact.includes(targetCompact);
+  });
+}
+
 /**
  * Resolve a match line to the real tag opener. If the match line itself opens
  * a tag, return it. Otherwise walk up to 10 lines backward looking for the

.agents/skills/impeccable/scripts/live.mjs

@@ -2,10 +2,10 @@
  * CLI entry point: prepare everything needed to enter the live variant poll loop.
  *
  * Does (all in one command):
- *   1. Check config.json (returns config_missing if first-ever run)
+ *   1. Check .impeccable/live/config.json (returns config_missing if first-ever run)
  *   2. Start the live server in the background (or reuse a running one)
  *   3. Inject the browser script tag into the project's entry file
- *   4. Read .impeccable.md for design context (if present)
+ *   4. Read PRODUCT.md / DESIGN.md for project context
  *   5. Print a single JSON blob with everything the agent needs
  *
  * After this, the agent's only remaining steps are:
@@ -23,9 +23,9 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadContext } from './load-context.mjs';
 import { resolveFiles } from './live-inject.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -34,10 +34,10 @@ async function liveCli() {
     console.log(`Usage: node live.mjs
 
 Prepare everything for live variant mode in a single command:
-  - Checks scripts/config.json (required, created once per project)
+  - Checks .impeccable/live/config.json (required, created once per project)
   - Starts (or reuses) the live server in the background
   - Injects the browser script tag
-  - Reads .impeccable.md for design context
+  - Reads PRODUCT.md / DESIGN.md for project context
 
 On success, prints a JSON blob with:
   { ok, serverPort, serverToken, pageFile, hasContext, context }
@@ -223,7 +223,7 @@ function safeParse(out) {
 function ensureServerRunning() {
   // Try to reuse an existing server
   try {
-    const existing = JSON.parse(fs.readFileSync(PID_FILE, 'utf-8'));
+    const existing = readLiveServerInfo(process.cwd())?.info;
     if (existing && existing.pid) {
       try {
         process.kill(existing.pid, 0); // throws if dead

.agents/skills/impeccable/scripts/load-context.mjs

@@ -13,11 +13,21 @@
  *     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';
@@ -26,15 +36,52 @@ 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)
-  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+  // 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, rename in place
-  if (!productPath) {
+  // 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');
@@ -50,7 +97,7 @@ export function loadContext(cwd = process.cwd()) {
   }
 
   // 3. DESIGN.md (case-insensitive)
-  const designPath = firstExisting(cwd, DESIGN_NAMES);
+  const designPath = firstExisting(contextDir, DESIGN_NAMES);
 
   const product = productPath ? safeRead(productPath) : null;
   const design = designPath ? safeRead(designPath) : null;
@@ -63,12 +110,13 @@ export function loadContext(cwd = process.cwd()) {
     design,
     designPath: designPath ? path.relative(cwd, designPath) : null,
     migrated,
+    contextDir,
   };
 }
 
-function firstExisting(cwd, names) {
+function firstExisting(dir, names) {
   for (const name of names) {
-    const abs = path.join(cwd, name);
+    const abs = path.join(dir, name);
     if (fs.existsSync(abs)) return abs;
   }
   return null;

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
     {
       "name": "impeccable",
       "description": "Design fluency for frontend development. 1 skill with 23 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
-      "version": "3.0.4",
+      "version": "3.1.0",
       "author": {
         "name": "Paul Bakaus",
         "email": "paul@paulbakaus.com"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "impeccable",
   "description": "Design fluency for frontend development. 1 skill with 23 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "author": {
     "name": "Paul Bakaus",
     "email": "paul@paulbakaus.com"

.claude/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 3.0.4
+version: 3.1.0
 user-invocable: true
 argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
@@ -11,35 +11,22 @@ allowed-tools:
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
 
-## Setup (non-optional)
+## Setup
 
-Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+Before any design work or file edits:
 
-| Gate | Required check | If fail |
-|---|---|---|
-| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .claude/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. |
-| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. |
-| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. |
-| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. |
-| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. |
-| Mutation | All active gates above pass. | Do not edit project files yet. |
+1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
+2. Identify the register and load the matching register reference (brand.md or product.md).
+3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects.
 
-Codex-style agents must state this before editing files:
-
-```text
-IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
-```
-
-For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.
-
-Other harnesses should follow the same checklist when they can expose this state.
+Skipping these produces generic output that ignores the project.
 
 ### 1. Context gathering
 
-Two files at the project root, case-insensitive:
+Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
 
-- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
-- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components.
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
 
 Load both in one call:
 
@@ -47,11 +34,11 @@ Load both in one call:
 node .claude/skills/impeccable/scripts/load-context.mjs
 ```
 
-Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`.
+Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
 
 If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `/impeccable teach` or `/impeccable document` (they rewrite the files), or the user manually edited one.
 
-`/impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session.
+`/impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session.
 
 If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/impeccable teach`, then resume the user's original task with the fresh context. If the original task was `/impeccable craft`, resume into `/impeccable shape` before any implementation work.
 
@@ -59,7 +46,7 @@ If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` fo
 
 ### 2. Register
 
-Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product).
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
 
 Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
 
@@ -69,24 +56,24 @@ Load the matching reference: [reference/brand.md](reference/brand.md) or [refere
 
 ## Shared design laws
 
-Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work — don't hold back.
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back.
 
 ### Color
 
-- Use OKLCH. Reduce chroma as lightness approaches 0 or 100 — high chroma at extremes looks garish.
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
 - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
 - Pick a **color strategy** before picking colors. Four steps on the commitment axis:
-  - **Restrained** — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
-  - **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
-  - **Full palette** — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
-  - **Drenched** — the surface IS the color. Brand heroes, campaign pages.
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
 - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
 
 ### Theme
 
 Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
 
-Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
 
 "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
 
@@ -126,7 +113,10 @@ Match-and-refuse. If you're about to write any of these, rewrite the element wit
 
 If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
 
-**Category-reflex check.** If someone could guess the theme and palette from the category name alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the training-data reflex. Rework the scene sentence and color strategy until the answer is no longer obvious from the domain.
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
 
 ## Commands
 
@@ -156,13 +146,13 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
 | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
 
-Plus two management commands — `pin <command>` and `unpin <command>`, detailed below.
+Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
 
 ### Routing rules
 
-1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
-2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target.
-3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
@@ -176,4 +166,4 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
 node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
 ```
 
-Valid `<command>` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.

.claude/skills/impeccable/reference/adapt.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: target platforms/devices and usage contexts.
 
-Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.
+Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
 
 ---
@@ -27,7 +27,7 @@ Understand what needs adaptation and why:
    - What won't work? (Hover states on touch, tiny touch targets)
    - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
 
-**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context.
+**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels.
 
 ## Plan Adaptation Strategy
 
@@ -164,7 +164,7 @@ Choose appropriate breakpoints:
 - Persistent side navigation on desktop
 - Breadcrumbs on smaller screens for context
 
-**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.
+**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect.
 
 **NEVER**:
 - Hide core functionality on mobile (if it matters, make it work)
@@ -187,4 +187,4 @@ Test thoroughly across contexts:
 - **Edge cases**: Very small screens (320px), very large screens (4K)
 - **Slow connections**: Test on throttled network
 
-Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
+When the adaptation feels native to each context, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/animate.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: performance constraints.
 
-Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
+Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut motion that exists only for decoration. Animation fatigue is a real cost; spend the budget on the moments that need it.
 
 ---
 
@@ -8,7 +8,7 @@ Analyze a feature and strategically add animations and micro-interactions that e
 
 Brand: orchestrated page-load sequences, staggered reveals, scroll-driven animation. Motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions.
 
-Product: 150–250 ms on most transitions. Motion conveys state — feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
+Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
 ---
 
@@ -105,12 +105,12 @@ Use appropriate techniques for each animation:
 
 **Easing curves (use these, not CSS defaults):**
 ```css
-/* Recommended - natural deceleration */
---ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
+/* Recommended: natural deceleration */
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth */
 --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
 --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
 
-/* AVOID - feel dated and tacky */
+/* AVOID: feel dated and tacky */
 /* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
 /* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
 ```
@@ -153,12 +153,12 @@ Use appropriate techniques for each animation:
 ```
 
 **NEVER**:
-- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
+- Use bounce or elastic easing curves; they feel dated and draw attention to the animation itself
 - Animate layout properties casually (`width`, `height`, `top`, `left`, margins) when transform, FLIP, or grid-based techniques would work
-- Use durations over 500ms for feedback—it feels laggy
-- Animate without purpose—every animation needs a reason
-- Ignore `prefers-reduced-motion`—this is an accessibility violation
-- Animate everything—animation fatigue makes interfaces feel exhausting
+- Use durations over 500ms for feedback (it feels laggy)
+- Animate without purpose (every animation needs a reason)
+- Ignore `prefers-reduced-motion` (this is an accessibility violation)
+- Animate everything (animation fatigue makes interfaces feel exhausting)
 - Block interaction during animations unless intentional
 
 ## Verify Quality
@@ -172,4 +172,4 @@ Test animations thoroughly:
 - **Doesn't block**: Users can interact during/after animations
 - **Adds value**: Makes interface clearer or more delightful
 
-Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.
+When the motion clarifies state instead of decorating it, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/audit.md

@@ -1,4 +1,4 @@
-Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address.
+Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
 
 This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
 
@@ -83,10 +83,10 @@ Check against ALL the **DON'T** guidelines from the parent impeccable skill (alr
 ### Detailed Findings by Severity
 
 Tag every issue with **P0-P3 severity**:
-- **P0 Blocking**: Prevents task completion — fix immediately
-- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release
-- **P2 Minor**: Annoyance, workaround exists — fix in next pass
-- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or WCAG AA violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
 
 For each issue, document:
 - **[P?] Issue name**
@@ -105,14 +105,14 @@ Identify recurring problems that indicate systemic gaps rather than one-off mist
 
 ### Positive Findings
 
-Note what's working well — good practices to maintain and replicate.
+Note what's working well: good practices to maintain and replicate.
 
 ## Recommended Actions
 
 List recommended commands in priority order (P0 first, then P1, then P2):
 
-1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
-2. **[P?] `/command-name`** — Brief description (specific context)
+1. **[P?] `/command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `/command-name`**: Brief description (specific context)
 
 **Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
@@ -131,4 +131,3 @@ After presenting the summary, tell the user:
 - Forget to prioritize (everything can't be P0)
 - Report false positives without verification
 
-Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.

.claude/skills/impeccable/reference/bolder.md

@@ -1,4 +1,4 @@
-Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
+When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type.
 
 ---
 
@@ -6,7 +6,7 @@ Increase visual impact and personality in designs that are too safe, generic, or
 
 Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV.
 
-Product: "bolder" rarely means theatrics — those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
+Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
 
 ---
 
@@ -32,7 +32,7 @@ If any of these are unclear from the codebase, STOP and call the AskUserQuestion
 
 **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
 
-**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold. They're generic. Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
+**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
 
 ## Plan Amplification
 
@@ -57,7 +57,7 @@ Systematically increase impact across these dimensions:
 
 ### Color Intensification
 - **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
-- **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop
+- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop
 - **Dominant color strategy**: Let one bold color own 60% of the design
 - **Sharp accents**: High-contrast accent colors that pop
 - **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
@@ -73,7 +73,7 @@ Systematically increase impact across these dimensions:
 ### Visual Effects
 - **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
 - **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
-- **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop)
+- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop)
 - **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
 - **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
 
@@ -81,7 +81,7 @@ Systematically increase impact across these dimensions:
 - **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays
 - **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences
 - **Micro-interactions**: Satisfying hover effects, click feedback, state changes
-- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect)
+- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect)
 
 ### Composition Boldness
 - **Hero moments**: Create clear focal points with dramatic treatment
@@ -92,7 +92,7 @@ Systematically increase impact across these dimensions:
 **NEVER**:
 - Add effects randomly without purpose (chaos ≠ bold)
 - Sacrifice readability for aesthetics (body text must be readable)
-- Make everything bold (then nothing is bold - need contrast)
+- Make everything bold (then nothing is bold; you need contrast)
 - Ignore accessibility (bold design must still meet WCAG standards)
 - Overwhelm with motion (animation fatigue is real)
 - Copy trendy aesthetics blindly (bold means distinctive, not derivative)
@@ -110,4 +110,4 @@ Ensure amplification maintains usability and coherence:
 
 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
 
-Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.
+When the result feels right, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/brand.md

@@ -1,42 +1,54 @@
 # Brand register
 
-When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself — a visitor's impression is the thing being made.
+When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself; a visitor's impression is the thing being made.
 
-The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance — *communicate, not transact* — and diverge wildly in aesthetic. Don't collapse them into a single look.
+The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance (*communicate, not transact*) and diverge wildly in aesthetic. Don't collapse them into a single look.
 
 ## The brand slop test
 
-If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness — a visitor should ask "how was this made?", not "which AI made this?"
+If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness; a visitor should ask "how was this made?", not "which AI made this?"
 
 Brand isn't a neutral register. AI-generated landing pages have flooded the internet, and average is no longer findable. Restraint without intent now reads as mediocre, not refined. Brand surfaces need a POV, a specific audience, a willingness to risk strangeness. Go big or go home.
 
 **The second slop test: aesthetic lane.** Before committing to moves, name the reference. A Klim-style specimen page is one lane; Stripe-minimal is another; Liquid-Death-acid-maximalism is another. Don't drift into editorial-magazine aesthetics on a brief that isn't editorial. A hiking brand with Cormorant italic drop caps has the wrong register within the register.
 
+Then the inverse test: in one sentence, describe what you're about to build the way a competitor would describe theirs. If that sentence fits the modal landing page in the category, restart.
+
 ## Typography
 
 ### Font selection procedure
 
 Every project. Never skip.
 
-1. Read the brief. Write three concrete brand-voice words — not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
-2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them — they are training-data defaults and they create monoculture.
-3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object* — a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
+1. Read the brief. Write three concrete brand-voice words. Not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words.
+2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them; they are training-data defaults and they create monoculture.
+3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object*: a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy."
 4. Cross-check. "Elegant" is not necessarily serif. "Technical" is not necessarily sans. "Warm" is not Fraunces. If the final pick lines up with the original reflex, start over.
 
 ### Reflex-reject list
 
-Training-data defaults. Ban list — look further:
+Training-data defaults. Ban list. Look further:
 
 Fraunces · Newsreader · Lora · Crimson · Crimson Pro · Crimson Text · Playfair Display · Cormorant · Cormorant Garamond · Syne · IBM Plex Mono · IBM Plex Sans · IBM Plex Serif · Space Mono · Space Grotesk · Inter · DM Sans · DM Serif Display · DM Serif Text · Outfit · Plus Jakarta Sans · Instrument Sans · Instrument Serif
 
+### Reflex-reject aesthetic lanes
+
+Parallel to the font list. Currently saturated aesthetic families that have flooded brand surfaces. If a brief lands in one of these lanes without a register reason that *requires* it (a literal magazine, a literal terminal, a literal industrial signage system), it's the second-order training reflex: the trap one tier deeper than picking a Fraunces font. Look further.
+
+- **Editorial-typographic.** Display serif (often italic) + small mono labels + ruled separators + monochromatic restraint. Klim-influenced, magazine-cover affectation. By 2026, every Stripe-adjacent and Notion-adjacent brand has landed here. The fingerprint: three rule-separated columns, an italic Fraunces / Recoleta / Newsreader headline, lowercase track-spaced metadata, no imagery.
+
+(More entries land here on the same cadence the font list updates. Brutalist-utility and acid-maximalism may join when they saturate. Removing entries when they fall back below saturation is also fine.)
+
+The reflex-reject lists apply to **new design choices**. When the existing brand has already committed to a font or a lane as part of its identity, identity-preservation wins; variants on an existing surface don't second-guess what's already shipping. The reflex-reject lists are for greenfield decisions and for departure-mode variants in [live.md](live.md).
+
 ### Pairing and voice
 
-Distinctive + refined is the goal — the specific shape depends on the brand:
+Distinctive + refined is the goal. The specific shape depends on the brand:
 
 - **Editorial / long-form / luxury**: display serif + sans body (a magazine shape).
 - **Tech / dev tools / fintech**: one committed sans, usually; custom-tight tracking, strong weight contrast inside a single family.
 - **Consumer / food / travel**: warmer pairings, often a humanist sans plus a script or display serif.
-- **Creative studios / agencies**: rule-breaking welcome — mono-only, or display-only, or custom-drawn type as voice.
+- **Creative studios / agencies**: rule-breaking welcome. Mono-only, or display-only, or custom-drawn type as voice.
 
 Two families minimum is the rule *only* when the voice needs it. A single well-chosen family with committed weight/size contrast is stronger than a timid display+body pair.
 
@@ -50,37 +62,38 @@ Light text on dark backgrounds: add 0.05–0.1 to line-height. Light type reads
 
 ## Color
 
-Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess — it's voice. A beige-and-muted-slate landing page ignores the register.
+Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess; it's voice. A beige-and-muted-slate landing page ignores the register.
 
 - Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
 - Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
-- When the strategy is Committed or Drenched, the color is load-bearing. Don't hedge with neutrals around the edges — commit.
+- When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit.
 - Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not.
+- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette.
 
 ## Layout
 
 - Asymmetric compositions are one option. Break the grid intentionally for emphasis.
-- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm — generous separations, tight groupings.
-- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed" — the failure mode is splitting the difference into a generic centered stack.
+- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm: generous separations, tight groupings.
+- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed"; the failure mode is splitting the difference into a generic centered stack.
 - Don't default to centering everything. Left-aligned with asymmetric layouts feels more designed; a strict grid reads as confident structure. A centered-stack hero with icon-title-subtitle cards reads as template.
-- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` — breakpoint-free responsiveness.
+- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` for breakpoint-free responsiveness.
 
 ## Imagery
 
 Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
 
-**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse.
+**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
 
-- **For greenfield work without local assets, use stock imagery** — Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `<div>` placeholders.
+- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `<div>` placeholders.
 - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".
 - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one.
 - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish".
 
-Tech / dev-tool brands are the exception where zero imagery can be correct — a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on.
+"Imagery" here is broader than stock photography: product screenshots, custom data visualizations, generated SVG, and canvas/WebGL scenes are all imagery. Text-only pages where typography alone carries the entire visual weight are the failure mode.
 
 ## Motion
 
-- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions — when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
+- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions, when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
 - For collapsing/expanding sections, transition `grid-template-rows` rather than `height`.
 
 ## Brand bans (on top of the shared absolute bans)
@@ -92,6 +105,7 @@ Tech / dev-tool brands are the exception where zero imagery can be correct — a
 - Timid palettes and average layouts. Safe = invisible.
 - Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs.
 - Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic.
+- Repeated tiny uppercase tracked labels above every section heading. A single strong kicker can be voice; repeating it as section grammar is AI scaffolding unless it's a deliberate, named brand system.
 
 ## Brand permissions
 
@@ -100,5 +114,5 @@ Brand can afford things product can't. Take them.
 - Ambitious first-load motion. Reveals, scroll-triggered transitions, typographic choreography.
 - Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing.
 - Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero.
-- Unexpected color strategies. Palette IS voice — a calm brand and a restless brand should not share palette mechanics.
+- Unexpected color strategies. Palette IS voice; a calm brand and a restless brand should not share palette mechanics.
 - Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment.

.claude/skills/impeccable/reference/clarify.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: audience technical level and users' mental state in context.
 
-Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
+Find the unclear, confusing, or poorly written interface text and rewrite it. Vague copy creates support tickets and abandonment; specific copy gets users through the task.
 
 
 ---
@@ -146,7 +146,7 @@ Every piece of copy should follow these rules:
 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
 3. **Be active**: "Save changes" not "Changes will be saved"
 4. **Be human**: "Oops, something went wrong" not "System error encountered"
-5. **Be helpful**: Tell users what to do, not just what happened
+5. **Tell users what to do**, not just what happened
 6. **Be consistent**: Use same terms throughout (don't vary for variety)
 
 **NEVER**:
@@ -171,4 +171,4 @@ Test that copy improvements work:
 - **Consistency**: Does it match terminology elsewhere?
 - **Tone**: Is it appropriate for the situation?
 
-Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
+When the copy reads cleanly, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/codex.md

@@ -0,0 +1,92 @@
+# Codex: Visual Direction & Asset Production
+
+This file is loaded by `/impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose.
+
+Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief.
+
+## Step A: Explore Directions with the User
+
+Before generating anything, run a brief direction conversation grounded in the shape brief.
+
+Ask **2-3 targeted questions** about visual lane, color strategy, atmosphere, and named anchor references. Don't enumerate generic menus; tie each question to the shape brief's answers. Example shape-grounded questions:
+
+- "Brief says 'editorial restraint, Klim-adjacent.' Are we closer to a quiet specimen page or a magazine-spread feel with hero imagery?"
+- "Palette strategy from shape was 'Committed.' Want it warm-grounded (deep oxblood + cream) or cool-grounded (slate + paper white)?"
+
+Stop and wait for answers. These pin the palette before any pixel gets generated.
+
+## Step B: Generate the Brand Palette First
+
+Generate **one** palette artifact before any mocks. This is a small, focused image: typography pairing on the chosen background, primary + accent color swatches, one signature ornament or motif. Single image, single pass.
+
+Why palette first: mocks generated against a vague color sense produce noise that drowns out the structural decisions. A confirmed palette is the first concrete contract for everything downstream.
+
+Show the palette to the user. Ask one question: "This is the palette I'm locking in for the mocks. Confirm, or call out what to shift?"
+
+Wait for confirmation. Do not generate mocks against an unconfirmed palette.
+
+## Step C: Generate 1-3 Visual Mocks Against the Palette
+
+Once the palette is confirmed, generate **1 to 3** high-fidelity north-star comps. Each mock must use the confirmed palette and typography. Mocks differ in *structural* direction (hierarchy, topology, density, composition), not in color or motif.
+
+- Brand work: push visual identity, composition, mood, and signature motifs.
+- Product work: push hierarchy, topology, density, tone, grounded in realistic product structure.
+- Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero.
+
+Use the `image_gen` tool directly (or via the imagegen skill when available). Don't ask the user to install anything.
+
+## Step D: Approval Loop
+
+Show the comps. Ask what carries forward. Iterate until **one direction is approved** or the user explicitly delegates.
+
+If the user delegates, pick the strongest direction and explain it from the brief, not personal taste.
+
+Before moving to assets, summarize what to carry into code and what *not* to literalize from the mock. This is the handoff between visual exploration and semantic implementation.
+
+## Step E: Mock Fidelity Inventory
+
+Inventory the approved mock's major visible ingredients. For each, decide implementation: semantic HTML/CSS/SVG, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission.
+
+Common ingredients to inventory:
+
+- Hero silhouette and dominant composition
+- Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.)
+- Nav and primary CTA treatment
+- Section sequence, especially the second fold
+- Image-native content the concept depends on
+- Typography, density, color/material treatment, motion cues
+
+Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong.
+
+If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, bullets, or copy, stop and fix it. That's a broken implementation, not a harmless interpretation.
+
+Don't substitute a different hero composition or visual driver post-approval without user sign-off.
+
+## Step F: Asset Slicing via the Asset Producer
+
+Raster ingredients identified in Step E need clean production assets. Use the bundled `impeccable_asset_producer` subagent rather than producing inline.
+
+Spawn it as a scoped subagent. If you do not have explicit permission to use agents, stop and ask:
+
+```text
+Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step?
+```
+
+Pass to the agent:
+
+- Approved mock path or screenshot reference
+- Crop paths or a contact sheet with crop ids
+- Output directory
+- Required dimensions, format, transparency needs
+- Avoid list
+- Notes on what should remain semantic HTML/CSS/SVG instead of raster
+
+Attach image generation capability to the spawned agent when the harness supports it. Do **not** load image-generation reference material into the parent thread.
+
+Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode.
+
+Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; reach for real, generated, or stock imagery when the mock or subject matter calls for actual visual content.
+
+## After This File
+
+Once Steps A through F are complete, return to `craft.md` Step 5 (Build to Production Quality). The implementation builds against the confirmed palette, approved mock, and the assets the producer wrote.

.claude/skills/impeccable/reference/cognitive-load.md

@@ -6,17 +6,17 @@ Cognitive load is the total mental effort required to use an interface. Overload
 
 ## Three Types of Cognitive Load
 
-### Intrinsic Load — The Task Itself
+### Intrinsic Load: The Task Itself
 Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it.
 
 **Manage it by**:
 - Breaking complex tasks into discrete steps
 - Providing scaffolding (templates, defaults, examples)
-- Progressive disclosure — show what's needed now, hide the rest
+- Progressive disclosure: show what's needed now, hide the rest
 - Grouping related decisions together
 
-### Extraneous Load — Bad Design
-Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste.
+### Extraneous Load: Bad Design
+Mental effort caused by poor design choices. **Eliminate this ruthlessly.** It's pure waste.
 
 **Common sources**:
 - Confusing navigation that requires mental mapping
@@ -25,8 +25,8 @@ Mental effort caused by poor design choices. **Eliminate this ruthlessly** — i
 - Inconsistent patterns that prevent learning
 - Unnecessary steps between user intent and result
 
-### Germane Load — Learning Effort
-Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery.
+### Germane Load: Learning Effort
+Mental effort spent building understanding. This is *good* cognitive load; it leads to mastery.
 
 **Support it by**:
 - Progressive disclosure that reveals complexity gradually
@@ -58,9 +58,9 @@ Evaluate the interface against these 8 items:
 **Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001).
 
 At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider:
-- **≤4 items**: Within working memory limits — manageable
-- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure
-- **8+ items**: Overloaded — users will skip, misclick, or abandon
+- **≤4 items**: Within working memory limits, manageable
+- **5–7 items**: Pushing the boundary; consider grouping or progressive disclosure
+- **8+ items**: Overloaded; users will skip, misclick, or abandon
 
 **Practical applications**:
 - Navigation menus: ≤5 top-level items (group the rest under clear categories)
@@ -90,7 +90,7 @@ At any decision point, count the number of distinct options, actions, or pieces
 **Fix**: Use plain language. If domain terms are unavoidable, define them inline.
 
 ### 5. The Visual Noise Floor
-**Problem**: Every element has the same visual weight — nothing stands out.
+**Problem**: Every element has the same visual weight; nothing stands out.
 **Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted.
 
 ### 6. The Inconsistent Pattern

.claude/skills/impeccable/reference/color-and-contrast.md

@@ -2,11 +2,11 @@
 
 ## Color Spaces: Use OKLCH
 
-**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
 
-The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness — but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
+The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness, but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
 
-The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex — those are the dominant AI-design defaults, not the right answer for any specific brand.
+The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex; those are the dominant AI-design defaults, not the right answer for any specific brand.
 
 ## Building Functional Palettes
 
@@ -36,8 +36,8 @@ A complete system needs:
 This rule is about **visual weight**, not pixel count:
 
 - **60%**: Neutral backgrounds, white space, base surfaces
-- **30%**: Secondary colors—text, borders, inactive states
-- **10%**: Accent—CTAs, highlights, focus states
+- **30%**: Secondary colors: text, borders, inactive states
+- **10%**: Accent: CTAs, highlights, focus states
 
 The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
 
@@ -59,15 +59,15 @@ The common mistake: using the accent color everywhere because it's "the brand co
 These commonly fail contrast or cause readability issues:
 
 - Light gray text on white (the #1 accessibility fail)
-- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
-- Red text on green background (or vice versa)—8% of men can't distinguish these
+- **Gray text on any colored background**: gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
+- Red text on green background (or vice versa): 8% of men can't distinguish these
 - Blue text on red background (vibrates visually)
 - Yellow text on white (almost always fails)
 - Thin light text on images (unpredictable contrast)
 
 ### Never Use Pure Gray or Pure Black
 
-Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature; real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
 
 ### Testing
 
@@ -88,13 +88,13 @@ You can't just swap colors. Dark mode requires different design decisions:
 | Shadows for depth | Lighter surfaces for depth (no shadows) |
 | Dark text on light | Light text on dark (reduce font weight) |
 | Vibrant accents | Desaturate accents slightly |
-| White backgrounds | Never pure black—use dark gray (oklch 12-18%) |
+| White backgrounds | Never pure black; use dark gray (oklch 12-18%) |
 
-In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project — do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
+In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project; do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
 
 ### Token Hierarchy
 
-Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same.
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer; primitives stay the same.
 
 ## Alpha Is A Design Smell
 

.claude/skills/impeccable/reference/colorize.md

@@ -1,14 +1,14 @@
 > **Additional context needed**: existing brand colors.
 
-Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
+Replace timid grayscale or single-accent designs with a strategic palette: pick a color strategy, choose a hue family that fits the brand, then apply color with intent. More color ≠ better. Strategic color beats rainbow vomit.
 
 ---
 
 ## Register
 
-Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule — that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule; that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
 
-Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators — not decoration. Every color has a consistent meaning across every screen.
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators. Not decoration. Every color has a consistent meaning across every screen.
 
 ---
 
@@ -81,13 +81,13 @@ Add color systematically across these dimensions:
 - **Comparison**: Color coding for different datasets or timeframes
 
 ### Borders & Accents
-- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`)
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes; see the absolute ban on `border-left/right > 1px`)
 - **Underlines**: Color underlines for emphasis or active states
 - **Dividers**: Subtle colored dividers instead of gray lines
 - **Focus rings**: Colored focus indicators matching brand
 - **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
 
-**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe.
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix. Not a side stripe.
 
 ### Typography Color
 - **Colored headings**: Use brand colors for section headings (maintain contrast)
@@ -123,8 +123,8 @@ Ensure color addition improves rather than overwhelms:
 **NEVER**:
 - Use every color in the rainbow (choose 2-4 colors beyond neutrals)
 - Apply color randomly without semantic meaning
-- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead
-- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication
+- Put gray text on colored backgrounds. It looks washed out; use a darker shade of the background color or transparency instead
+- Use pure gray for neutrals. Add subtle color tint (warm or cool) for depth
 - Use pure black (`#000`) or pure white (`#fff`) for large areas
 - Violate WCAG contrast requirements
 - Use color as the only indicator (accessibility issue)
@@ -141,11 +141,11 @@ Test that colorization improves the experience:
 - **Still accessible**: Do all color combinations meet WCAG standards?
 - **Not overwhelming**: Is color balanced and purposeful?
 
-Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
+When the palette earns its place, hand off to `/impeccable polish` for the final pass.
 
 ## Live-mode signature params
 
-When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)` — typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)`, typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
 
 ```json
 {"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}

.claude/skills/impeccable/reference/craft.md

@@ -1,43 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar.
+Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar.
 
-## Build Gate
+Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief.
 
-Craft cannot build until all of these are true:
+Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong.
 
-1. PRODUCT context is valid and current.
-2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief.
-3. Implementation references from the brief are loaded.
-4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved.
-5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable.
+## Step 0: Project Foundation
 
-PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user.
+Before shape, before code: figure out what kind of project you're working in.
 
-Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets.
+Look at the working directory. Run `ls`. Check for:
 
-## Craft Contract
+- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it.
+- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it.
+- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set.
 
-Craft is not a first pass. It is a loop with these required artifacts:
+If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief:
 
-1. Confirmed design brief from `shape`.
-2. Approved visual direction, from generated probes / mocks when image generation is available.
-3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code.
-4. Semantic, functional implementation using the project's real stack and conventions.
-5. Browser evidence across relevant viewports.
-6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects.
+```text
+What should this be built on?
+  - Astro (default for content-led brand sites, landing pages, marketing surfaces)
+  - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity)
+  - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment)
+```
 
-Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood."
+Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task.
 
 ## Step 1: Shape the Design
 
-Run /impeccable shape, passing along whatever feature description the user provided.
+Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction.
 
-Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code.
 
-If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation.
+If the user already supplied a confirmed brief or ran shape separately, use it and skip this step.
 
-If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
+When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient.
 
 ## Step 2: Load References
 
@@ -53,134 +51,51 @@ Then add references based on the brief's needs:
 - Responsive requirements? Consult [responsive-design.md](responsive-design.md)
 - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md)
 
-## Step 3: Land the Visual Direction (Capability-Gated)
+## Step 3: Visual Direction & Assets (Harness-Gated)
 
-Before implementation, generate high-fidelity visual comps when all of these are true:
+If the harness has **native image generation** (currently Codex via `image_gen`), this step is mandatory. **Stop and load [codex.md](codex.md)**. It covers palette generation, mock exploration, the approval loop, mock-fidelity inventory, and asset slicing via the `impeccable_asset_producer` subagent. Follow Steps A-F in that file, then return here for Step 4.
 
-- The work is **net-new** or visually open-ended enough that composition exploration will improve the build.
-- The brief's scope is **mid-fi, high-fi, or production-ready**.
-- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+If the harness lacks native image generation, **state in one line that the visual-direction-by-generation step is being skipped because the harness lacks native image generation, then proceed**. The one-line announcement is required; it forces a conscious decision instead of letting the step quietly evaporate. The brief is your only visual reference. Implement directly from it, treating any named anchor references and the brief's "Design Direction" as the contract.
 
-When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+Whether you generated mocks or not: don't replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. Image-led briefs (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product) need real or sourced imagery in the build, not CSS scenery.
 
-Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
-
-### Purpose
-
-Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone.
-
-### What to generate
-
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration.
-
-- For brand work, push visual identity, composition, and mood aggressively.
-- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states.
-- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero.
-
-The comps must be genuinely different in primary visual direction, not just color variants.
-
-### Approval loop
-
-Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice.
-
-If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste.
-
-Before moving to implementation, summarize:
-
-- What to carry into code
-- What **not** to literalize from the mock
-
-This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
-
-### Mock fidelity inventory
-
-Before building, inventory the approved mock's major visible ingredients:
-
-- Hero silhouette and dominant composition.
-- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects.
-- Nav and primary CTA treatment.
-- Section sequence visible in the mock, especially the second fold.
-- Image-native content the concept depends on.
-- Typography, density, color/material treatment, and motion cues.
-
-For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change.
-
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong.
-
-## Step 4: Asset Extraction (Need-Gated)
-
-If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building.
-
-Good candidates:
-
-- stickers
-- badges
-- seals
-- tickets
-- graphic labels
-- textures
-- abstract objects
-- decorative marks
-- non-semantic scene elements
-
-For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes.
-
-Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code.
-
-Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional.
-
-## Step 5: Build to Production Quality
+## Step 4: Build to Production Quality
 
 Implement the feature following the design brief. Build in passes so structure, visual system, states, motion/media, and responsive behavior each get deliberate attention. The list below is the definition of done, not inspiration.
 
 ### Production bar
 
-- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting.
-- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change.
-- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed.
-- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
-- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes.
-- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant.
-- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality.
-- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles.
-- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace.
-- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.
-- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists.
-- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path.
-- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing.
+- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time.
+- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change.
+- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed.
+- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
+- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width.
+- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run.
+- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality.
+- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix.
+- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve.
+- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about.
+- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace.
+- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.
+- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists.
+- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths.
+- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess.
 
-## Step 6: Browser-Based Iteration
+## Step 5: Iterate Visually
 
-**This step is critical.** Do not stop after the first implementation pass.
+Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation.
 
-Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output.
+If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count.
 
-### Required viewport pass
+For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects.
 
-Check the experience at the viewports that matter for the brief. Default minimum:
+After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix.
 
-- Mobile narrow
-- Tablet or small laptop
-- Desktop wide
+Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review.
 
-For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow.
+Detector or QA output is defect evidence only; never proof the work is finished.
 
-### Critique and fix loop
-
-After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist:
-
-1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies.
-2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects.
-3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention.
-4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink.
-7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment.
-8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason.
-
-The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review.
-
-## Step 7: Present
+## Step 6: Present
 
 Present the result to the user:
 - Show the feature in its primary state
@@ -189,5 +104,3 @@ Present the result to the user:
 - Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients.
 - Note any remaining limitations or follow-up risks honestly
 - Ask: "What's working? What isn't?"
-
-Iterate based on feedback. Good design is rarely right on the first pass.

.claude/skills/impeccable/reference/critique.md

@@ -1,8 +1,26 @@
 > **Additional context needed**: what the interface is trying to accomplish.
 
+### Setup: Resolve Target and Load Ignore List
+
+Before gathering assessments, do two small bookkeeping steps. They cost almost nothing and they're what makes critique iterative across runs.
+
+1. **Resolve the primary artifact.** The user's phrasing ("the homepage", "the pricing flow") is not stable enough to track across runs. Resolve it to a concrete file path or URL: the same one you'd already need to scan code or open in a browser. Examples:
+   - "the homepage" → `site/pages/index.astro` (or `http://localhost:3000/` if you're inspecting live)
+   - "the settings modal" → the primary component file (e.g., `src/components/Settings.tsx`)
+   - "this page" → the URL or the page's source file
+   Prefer the source file path over the dev-server URL when both exist; ports drift between runs (`bun dev` vs `bun preview`), file paths don't.
+
+2. **Compute the slug.** Run:
+   ```bash
+   node .claude/skills/impeccable/scripts/critique-storage.mjs slug "<resolved-path-or-url>"
+   ```
+   Keep the printed slug. It identifies this target's stream across runs. If the command exits non-zero ("no stable slug for input"), skip persistence for this run and tell the user; the trend won't update but the critique still goes ahead.
+
+3. **Read the ignore list** at `.impeccable/critique/ignore.md` if it exists. Plain markdown; each non-empty, non-comment line is something the user has marked as "do not re-raise" (deferred tradeoffs, designer-intended deviations, detector false-positives the user accepts). When a finding's text matches a line here (case-insensitive substring against rule name or snippet), **drop it silently**. Do not mention it in the report. This is the ONLY input critique consumes from prior runs; anchoring on prior findings would defeat the point of independent assessment.
+
 ### Gather Assessments
 
-Launch two independent assessments. **Neither may see the other's output** — this isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
+Launch two independent assessments. **Neither may see the other's output.** This isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
 
 Delegate each assessment to a separate sub-agent (Claude Code's `Agent` tool, Codex's subagent spawning, etc.). Each returns structured findings as text. Do NOT output findings to the user yet.
 
@@ -39,11 +57,11 @@ Return structured findings covering: AI slop verdict, heuristic scores, cognitiv
 
 #### Assessment B: Automated Detection
 
-Run the bundled deterministic detector, which flags 25 specific patterns (AI slop tells + general design quality).
+Run the bundled deterministic detector, which flags 27 specific patterns (AI slop tells + general design quality).
 
 **CLI scan**:
 ```bash
-npx impeccable --json [--fast] [target]
+npx impeccable detect --json [--fast] [target]
 ```
 
 - Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files.
@@ -52,7 +70,7 @@ npx impeccable --json [--fast] [target]
 - For 500+ files, narrow scope or ask the user
 - Exit code 0 = clean, 2 = findings
 
-**Browser visualization** — **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
+**Browser visualization**: **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
 
 The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically.
 
@@ -160,10 +178,40 @@ Provocative questions that might unlock better solutions:
 - Be direct. Vague feedback wastes everyone's time.
 - Be specific. "The submit button," not "some elements."
 - Say what's wrong AND why it matters to users.
-- Give concrete suggestions, not just "consider exploring..."
+- Give concrete suggestions. Cut "consider exploring..." entirely.
 - Prioritize ruthlessly. If everything is important, nothing is.
 - Don't soften criticism. Developers need honest feedback to ship great design.
 
+### Persist the Snapshot
+
+Once the report above is finalized, write it to `.impeccable/critique/` so the user can refer back, and so `/impeccable polish` can pick up the priority issues without a copy-paste.
+
+Skip this step if the Setup slug was null (vague or root-level target).
+
+1. **Write the body to a temp file** so you can pipe it to the helper. Use the full report (heuristic table, anti-patterns verdict, priority issues, persona red flags) but stop before the "Ask the User" / "Recommended Actions" sections that come later.
+
+2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command:
+   ```bash
+   IMPECCABLE_CRITIQUE_META='{"target":"<user phrasing>","total_score":<n>,"p0_count":<n>,"p1_count":<n>}' \
+     node .claude/skills/impeccable/scripts/critique-storage.mjs write <slug> <body-file>
+   ```
+   The helper prints the absolute path it wrote.
+
+3. **Read the trend** for context:
+   ```bash
+   node .claude/skills/impeccable/scripts/critique-storage.mjs trend <slug> 5
+   ```
+   This returns a JSON array of the last 5 frontmatter entries (including the one you just wrote).
+
+4. **Append a single line to the user-visible output**, after the report and before the questions:
+
+   > **Trend for `<slug>` (last 5 runs): 24 → 28 → 32 → 29 → 32**
+   > Wrote `.impeccable/critique/<filename>`.
+
+   If this is the first run for the slug, the trend is just one score; say so: "First run for this target, no trend yet."
+
+This is fire-and-forget. Do not show the user the helper's JSON output; only the human-readable trend line and the written path. Failures here should not block the rest of the flow; print the error and move on.
+
 ### Ask the User
 
 **After presenting findings**, use targeted questions based on what was actually found. STOP and call the AskUserQuestion tool to clarify. These answers will shape the action plan.

.claude/skills/impeccable/reference/delight.md

@@ -1,12 +1,12 @@
 > **Additional context needed**: what's appropriate for the domain (playful vs professional vs quirky vs elegant).
 
-Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
+Find the moments where personality and unexpected polish would turn a functional interface into one users remember and tell other people about. Add only where the moment earns it; delight everywhere reads as noise.
 
 ---
 
 ## Register
 
-Brand: delight can be distributed — copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface.
+Brand: delight can be distributed across copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface.
 
 Product: delight at specific moments, not pages. Completion, first-time actions, error recovery, milestone crossings. Reliability and consistency carry the rest of the experience; delight pushed everywhere reads as noise.
 
@@ -236,14 +236,14 @@ Add personality and joy through these methods:
 - Countdown with encouraging messages
 
 ```
-Loading messages — write ones specific to your product, not generic AI filler:
+Loading messages: write ones specific to your product, not generic AI filler:
 - "Crunching your latest numbers..."
 - "Syncing with your team's changes..."
 - "Preparing your dashboard..."
 - "Checking for updates since yesterday..."
 ```
 
-**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.
+**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy, instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.
 
 ### Celebration Moments
 
@@ -299,4 +299,4 @@ Test that delight actually delights:
 - **Appropriate**: Matches brand and context
 - **Accessible**: Works with reduced motion, screen readers
 
-Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.
+When the moments feel earned, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/distill.md

@@ -1,4 +1,4 @@
-Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
+Strip a design to its essence. Remove anything that doesn't earn its place: redundant elements, repeated information, decorative noise, cosmetic complexity.
 
 
 ---
@@ -23,7 +23,7 @@ Analyze what makes the design feel complex or cluttered:
 
 If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
 
-**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.
+**CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence.
 
 ## Plan Simplification
 
@@ -51,7 +51,7 @@ Systematically remove complexity across these dimensions:
 - **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
 - **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights
 - **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function
-- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards
+- **Flatten structure**: Reduce nesting, remove unnecessary containers; never nest cards inside cards
 - **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead
 - **Consistent spacing**: Use one spacing scale, remove arbitrary gaps
 
@@ -108,4 +108,4 @@ If you removed features or options:
 - Consider if they need alternative access points
 - Note any user feedback to monitor
 
-Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
+When the cuts feel right, hand off to `/impeccable polish` for the final pass. As Antoine de Saint-Exupéry put it: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

.claude/skills/impeccable/reference/document.md

@@ -44,7 +44,7 @@ Rules that matter:
 
 - **Token refs** use `{path.to.token}` (e.g. `{colors.primary}`, `{rounded.md}`). Components may reference primitives; primitives may not reference each other.
 - **Stitch validates colors as hex sRGB only** (`#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`); OKLCH/HSL/P3 trigger a linter warning, not a hard error. YAML accepts the string either way and our own parser is format-agnostic. Choose based on project posture: (a) if the project has an "OKLCH-only" doctrine or uses Display-P3 values that don't round-trip through sRGB, put OKLCH directly in the frontmatter and accept the Stitch linter warning; (b) if the project wants strict Stitch compliance or plans to use their Tailwind/DTCG export pipeline, put hex in the frontmatter and keep OKLCH in prose as the canonical reference. Never split the source of truth without explicit reason.
-- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter — none of those fit. Carry them in the sidecar (Step 4b).
+- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter: none of those fit. Carry them in the sidecar (Step 4b).
 - **Scale keys are open-ended.** Use whatever names the project already uses (`warm-ash-cream`, `surface-container-low`). Don't rename to Material defaults.
 - **Variants are naming convention, not schema.** `button-primary` / `button-primary-hover` / `button-primary-active` as sibling keys.
 
@@ -57,7 +57,7 @@ Rules that matter:
 5. `## Components`
 6. `## Do's and Don'ts`
 
-Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
+Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` (Stitch's own outputs do this), but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
 
 ## When to run
 
@@ -73,7 +73,7 @@ If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user
 - **Scan mode** (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there's code to analyze.
 - **Seed mode**: the project is pre-implementation (fresh teach, nothing built yet). Interview for five high-level answers, write a minimal DESIGN.md marked `<!-- SEED -->`. Re-run in scan mode once there's code.
 
-Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode — don't silently switch. `/impeccable document --seed` forces seed mode regardless of code presence.
+Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode; don't silently switch. `/impeccable document --seed` forces seed mode regardless of code presence.
 
 ## Scan mode (approach C: auto-extract, then confirm descriptive language)
 
@@ -81,29 +81,29 @@ Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no com
 
 Search the codebase in priority order:
 
-1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
-2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
-3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
-4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
-5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
-6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
-7. **Visible rendered output** — if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
+1. **CSS custom properties**: grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
+2. **Tailwind config**: if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
+3. **CSS-in-JS theme files**: styled-components, emotion, vanilla-extract, stitches; look for `theme.ts`, `tokens.ts`, or equivalent.
+4. **Design token files**: `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
+5. **Component library**: scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
+6. **Global stylesheet**: the root CSS file usually has the base typography and color assignments.
+7. **Visible rendered output**: if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
 
 ### Step 2: Auto-extract what can be auto-extracted
 
 Build a structured draft from the discovered tokens. For each token class:
 
-- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
+- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral; omit Secondary and Tertiary rather than inventing them.
 - **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
-- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
+- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer; state it explicitly.
 - **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
 - **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
 
 ### Step 2b: Stage the frontmatter
 
-From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer — what the live panel and Stitch's linter consume.
+From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer: what the live panel and Stitch's linter consume.
 
-- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex — see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
+- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex; see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
 - **Typography**: one entry per role (`display`, `headline`, `title`, `body`, `label`). Typography is an object; include only the props that are real for the project (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`).
 - **Rounded / Spacing**: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (`sm` / `md` / `lg`, or `surface-sm`, or numeric steps).
 - **Components**: one entry per variant (`button-primary`, `button-primary-hover`, `button-ghost`). Reference primitives via `{colors.X}`, `{rounded.Y}`. If a variant needs a property Stitch's 8-prop set doesn't cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead.
@@ -149,7 +149,7 @@ colors:
 ### Primary
 - **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
 
-### Secondary (optional — omit if the project has only one accent)
+### Secondary (optional; omit if the project has only one accent)
 - **[Descriptive Name]** (#HEX): [Role.]
 
 ### Tertiary (optional)
@@ -160,7 +160,7 @@ colors:
 - [...]
 
 ### Named Rules (optional, powerful)
-**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
+**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine, e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
 
 ## 3. Typography
 
@@ -171,7 +171,7 @@ colors:
 **Character:** [1-2 sentence personality description of the pairing.]
 
 ### Hierarchy
-- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
+- **Display** ([weight], [size/clamp], [line-height]): [Purpose; where it appears.]
 - **Headline** ([weight], [size], [line-height]): [Purpose.]
 - **Title** ([weight], [size], [line-height]): [Purpose.]
 - **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
@@ -214,34 +214,34 @@ For each component, lead with a short character line, then specify shape, color
 
 ### Inputs / Fields
 - **Style:** [stroke, background, radius]
-- **Focus:** [treatment — glow, border shift, etc.]
+- **Focus:** [treatment, e.g. glow, border shift, etc.]
 - **Error / Disabled:** [if applicable]
 
 ### Navigation
 - **Style, typography, default/hover/active states, mobile treatment.**
 
-### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
+### [Signature Component] (optional; if the project has a distinctive custom component worth documenting)
 [Description.]
 
 ## 6. Do's and Don'ts
 
-Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name.
+Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific: include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name.
 
 ### Do:
 - **Do** [specific prescription with exact values / named rule].
 - **Do** [...]
 
 ### Don't:
-- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
+- **Don't** [specific prohibition, e.g. "use border-left greater than 1px as a colored stripe"].
 - **Don't** [...]
 - **Don't** [...]
 ```
 
-### Step 4b: Write DESIGN.json sidecar (extensions only)
+### Step 4b: Write .impeccable/design.json sidecar (extensions only)
 
-The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `DESIGN.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
+The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `.impeccable/design.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
 
-Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve DESIGN.md and write only DESIGN.json.
+Regenerate the sidecar whenever you regenerate root `DESIGN.md`. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve `DESIGN.md` and write only `.impeccable/design.json`.
 
 #### Schema
 
@@ -280,7 +280,7 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks
   ],
   "narrative": {
     "northStar": "The Editorial Sanctuary",
-    "overview": "2-3 paragraphs of the philosophy — pulled from DESIGN.md Overview section.",
+    "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.",
     "keyCharacteristics": ["...", "..."],
     "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
     "dos":   ["Do use ..."],
@@ -289,14 +289,14 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks
 }
 ```
 
-**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter — tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints — keyed by the frontmatter token name (`colorMeta.<token-name>`, `typographyMeta.<token-name>`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
+**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter (tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints), keyed by the frontmatter token name (`colorMeta.<token-name>`, `typographyMeta.<token-name>`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
 
 #### Component translation rules
 
-The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly — no post-processing, no framework runtime.
+The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly: no post-processing, no framework runtime.
 
 1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained.
-2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)` — they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
+2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)`; they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
 3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or `<img src="...">`. A typical icon is 16-24px; copy the SVG path data directly.
 4. **States.** Include `:hover`, `:focus-visible`, and (if meaningful) `:active` rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive.
 5. **Reset bloat.** Extract only the component's *distinctive* CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (`box-sizing: border-box`, `line-height: inherit`, `-webkit-font-smoothing`). The panel already has a neutral canvas; don't re-ship resets.
@@ -308,13 +308,13 @@ Aim for a tight set of **5-10 components** that best represent the visual system
 
 - **Canonical primitives (always include if the project has them):** button (each variant as a separate component entry), input/text field, navigation, chip/tag, card.
 - **Signature components (include if distinctive):** hero CTA, featured card, filter pill, any custom pattern the user mentioned as important in PRODUCT.md.
-- **Skip the rest.** Utility components, form building blocks, wrapper layouts — not worth documenting unless visually distinctive.
+- **Skip the rest.** Utility components, form building blocks, wrapper layouts: not worth documenting unless visually distinctive.
 
-If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every DESIGN.json has *something* to render, even on day zero.
+If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every `.impeccable/design.json` has *something* to render, even on day zero.
 
 #### Tonal ramps
 
-For each color token, generate an 8-step `tonalRamp` array — dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
+For each color token, generate an 8-step `tonalRamp` array: dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
 
 #### Narrative mapping
 
@@ -331,7 +331,7 @@ Do not reword. The panel shows these as secondary collapsible context; the same
 ### Step 5: Confirm, refine, and refresh session cache
 
 1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules).
-2. Mention that `DESIGN.json` was also written alongside — the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
+2. Mention that `.impeccable/design.json` was also written alongside; the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
 3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
 4. **Refresh the session cache.** Run `node .claude/skills/impeccable/scripts/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading.
 
@@ -350,24 +350,24 @@ If the user prefers to skip, stop. No file.
 Group into one `AskUserQuestion` interaction. Options must be concrete.
 
 1. **Color strategy.** Pick one:
-   - Restrained — tinted neutrals + one accent ≤10%
-   - Committed — one saturated color carries 30–60% of the surface
-   - Full palette — 3–4 named color roles, each deliberate
-   - Drenched — the surface IS the color
+   - Restrained: tinted neutrals + one accent ≤10%
+   - Committed: one saturated color carries 30–60% of the surface
+   - Full palette: 3–4 named color roles, each deliberate
+   - Drenched: the surface IS the color
    
    Then: one hue family or anchor reference ("deep teal", "mustard", "Klim #ff4500 orange").
 
 2. **Typography direction.** Pick one (specific fonts come later):
    - Serif display + sans body
-   - Single sans (warm / technical / geometric / humanist — pick a feel)
+   - Single sans (warm / technical / geometric / humanist; pick a feel)
    - Display + mono
    - Mono-forward
    - Editorial script + sans
 
 3. **Motion energy.** Pick one:
-   - Restrained — state changes only
-   - Responsive — feedback + transitions, no choreography
-   - Choreographed — orchestrated entrances, scroll-driven sequences
+   - Restrained: state changes only
+   - Responsive: feedback + transitions, no choreography
+   - Choreographed: orchestrated entrances, scroll-driven sequences
 
 4. **Three named references.** Brands, products, printed objects. Not adjectives.
 
@@ -380,19 +380,19 @@ Use the six-section spec from Scan mode. Populate what the interview answers; le
 Lead the file with:
 
 ```markdown
-<!-- SEED — re-run /impeccable document once there's code to capture the actual tokens and components. -->
+<!-- SEED: re-run /impeccable document once there's code to capture the actual tokens and components. -->
 ```
 
 Per-section guidance in seed mode:
 
 - **Overview**: Creative North Star and philosophy phrased from the answers (color strategy + motion energy + references). Reference the user's anti-reference directly.
-- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values — mark as `[to be resolved during implementation]`.
-- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet — `[font pairing to be chosen at implementation]`.
+- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values; mark as `[to be resolved during implementation]`.
+- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet: `[font pairing to be chosen at implementation]`.
 - **Elevation**: inferred from motion energy. Restrained/Responsive → flat by default; Choreographed → layered. One sentence.
-- **Components**: omit entirely — no components exist yet.
+- **Components**: omit entirely; no components exist yet.
 - **Do's and Don'ts**: carry PRODUCT.md's anti-references directly plus the anti-reference named in Q5.
 
-Seed mode writes a minimal frontmatter with `name` and `description` only — no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `DESIGN.json` sidecar in seed mode for the same reason: nothing to render.
+Seed mode writes a minimal frontmatter with `name` and `description` only; no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `.impeccable/design.json` sidecar in seed mode for the same reason: nothing to render.
 
 ### Step 4: Confirm and refresh session cache
 
@@ -402,14 +402,14 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no
 
 ## Style guidelines
 
-- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places — the frontmatter is normative.
+- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places; the frontmatter is normative.
 - **Cite PRODUCT.md anti-references by name** in the Do's and Don'ts section. If PRODUCT.md lists "SaaS landing-page clichés" or "generic AI tool marketing" as anti-references, the DESIGN.md Don'ts should repeat those phrases verbatim so the visual spec enforces the strategic line.
 - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
 - **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
 - **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
-- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
+- **Exact values in parens**: hex codes, px/rem values, font weights; always the number in parens alongside the description.
 - **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
-- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
+- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always", not "consider", "might", "prefer". Match PRODUCT.md's tone.
 - **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
 - **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
 - **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
@@ -417,7 +417,7 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no
 ## Pitfalls
 
 - Don't paste raw CSS class names. Translate to descriptive language.
-- Don't extract every token. Stop at what's actually reused — one-offs pollute the system.
+- Don't extract every token. Stop at what's actually reused; one-offs pollute the system.
 - Don't invent components that don't exist. If the project only has buttons and cards, only document those.
 - Don't overwrite an existing DESIGN.md without asking.
 - Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.

.claude/skills/impeccable/reference/extract.md

@@ -67,4 +67,3 @@ Update design system documentation:
 - Create tokens for every single value (tokens should have semantic meaning)
 - Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate)
 
-Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.

.claude/skills/impeccable/reference/harden.md

@@ -1,4 +1,4 @@
-Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.
+Designs that only work with perfect data aren't production-ready. Harden the interface against the inputs, errors, languages, and network conditions that real users will throw at it.
 
 ## Assess Hardening Needs
 
@@ -344,4 +344,4 @@ Test thoroughly with edge cases:
 - **Errors**: Force API errors, test all error states
 - **Empty**: Remove all data, test empty states
 
-Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
+When edge cases are covered, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/heuristics-scoring.md

@@ -1,6 +1,6 @@
 # Heuristics Scoring Guide
 
-Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough."
+Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest: a 4 means genuinely excellent, not "good enough."
 
 ## Nielsen's 10 Heuristics
 
@@ -18,11 +18,11 @@ Keep users informed about what's happening through timely, appropriate feedback.
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | No feedback — user is guessing what happened |
-| 1 | Rare feedback — most actions produce no visible response |
-| 2 | Partial — some states communicated, major gaps remain |
-| 3 | Good — most operations give clear feedback, minor gaps |
-| 4 | Excellent — every action confirms, progress is always visible |
+| 0 | No feedback; user is guessing what happened |
+| 1 | Rare feedback; most actions produce no visible response |
+| 2 | Partial; some states communicated, major gaps remain |
+| 3 | Good; most operations give clear feedback, minor gaps |
+| 4 | Excellent; every action confirms, progress is always visible |
 
 ### 2. Match Between System and Real World
 
@@ -39,9 +39,9 @@ Speak the user's language. Follow real-world conventions. Information appears in
 | Score | Criteria |
 |-------|----------|
 | 0 | Pure tech jargon, alien to users |
-| 1 | Mostly confusing — requires domain expertise to navigate |
-| 2 | Mixed — some plain language, some jargon leaks through |
-| 3 | Mostly natural — occasional term needs context |
+| 1 | Mostly confusing; requires domain expertise to navigate |
+| 2 | Mixed; some plain language, some jargon leaks through |
+| 3 | Mostly natural; occasional term needs context |
 | 4 | Speaks the user's language fluently throughout |
 
 ### 3. User Control and Freedom
@@ -58,11 +58,11 @@ Users need a clear "emergency exit" from unwanted states without extended dialog
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Users get trapped — no way out without refreshing |
-| 1 | Difficult exits — must find obscure paths to escape |
-| 2 | Some exits — main flows have escape, edge cases don't |
-| 3 | Good control — users can exit and undo most actions |
-| 4 | Full control — undo, cancel, back, and escape everywhere |
+| 0 | Users get trapped; no way out without refreshing |
+| 1 | Difficult exits; must find obscure paths to escape |
+| 2 | Some exits; main flows have escape, edge cases don't |
+| 3 | Good control; users can exit and undo most actions |
+| 4 | Full control; undo, cancel, back, and escape everywhere |
 
 ### 4. Consistency and Standards
 
@@ -78,11 +78,11 @@ Users shouldn't wonder whether different words, situations, or actions mean the
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Inconsistent everywhere — feels like different products stitched together |
-| 1 | Many inconsistencies — similar things look/behave differently |
-| 2 | Partially consistent — main flows match, details diverge |
-| 3 | Mostly consistent — occasional deviation, nothing confusing |
-| 4 | Fully consistent — cohesive system, predictable behavior |
+| 0 | Inconsistent everywhere; feels like different products stitched together |
+| 1 | Many inconsistencies; similar things look/behave differently |
+| 2 | Partially consistent; main flows match, details diverge |
+| 3 | Mostly consistent; occasional deviation, nothing confusing |
+| 4 | Fully consistent; cohesive system, predictable behavior |
 
 ### 5. Error Prevention
 
@@ -98,11 +98,11 @@ Better than good error messages is a design that prevents problems in the first
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Errors easy to make — no guardrails anywhere |
-| 1 | Few safeguards — some inputs validated, most aren't |
-| 2 | Partial prevention — common errors caught, edge cases slip |
-| 3 | Good prevention — most error paths blocked proactively |
-| 4 | Excellent — errors nearly impossible through smart constraints |
+| 0 | Errors easy to make; no guardrails anywhere |
+| 1 | Few safeguards; some inputs validated, most aren't |
+| 2 | Partial prevention; common errors caught, edge cases slip |
+| 3 | Good prevention; most error paths blocked proactively |
+| 4 | Excellent; errors nearly impossible through smart constraints |
 
 ### 6. Recognition Rather Than Recall
 
@@ -118,15 +118,15 @@ Minimize memory load. Make objects, actions, and options visible or easily retri
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Heavy memorization — users must remember paths and commands |
-| 1 | Mostly recall — many hidden features, few visible cues |
-| 2 | Some aids — main actions visible, secondary features hidden |
-| 3 | Good recognition — most things discoverable, few memory demands |
-| 4 | Everything discoverable — users never need to memorize |
+| 0 | Heavy memorization; users must remember paths and commands |
+| 1 | Mostly recall; many hidden features, few visible cues |
+| 2 | Some aids; main actions visible, secondary features hidden |
+| 3 | Good recognition; most things discoverable, few memory demands |
+| 4 | Everything discoverable; users never need to memorize |
 
 ### 7. Flexibility and Efficiency of Use
 
-Accelerators — invisible to novices — speed up expert interaction.
+Accelerators, invisible to novices, speed up expert interaction.
 
 **Check for**:
 - Keyboard shortcuts for common actions
@@ -138,11 +138,11 @@ Accelerators — invisible to novices — speed up expert interaction.
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | One rigid path — no shortcuts or alternatives |
-| 1 | Limited flexibility — few alternatives to the main path |
-| 2 | Some shortcuts — basic keyboard support, limited bulk actions |
-| 3 | Good accelerators — keyboard nav, some customization |
-| 4 | Highly flexible — multiple paths, power features, customizable |
+| 0 | One rigid path; no shortcuts or alternatives |
+| 1 | Limited flexibility; few alternatives to the main path |
+| 2 | Some shortcuts; basic keyboard support, limited bulk actions |
+| 3 | Good accelerators; keyboard nav, some customization |
+| 4 | Highly flexible; multiple paths, power features, customizable |
 
 ### 8. Aesthetic and Minimalist Design
 
@@ -158,11 +158,11 @@ Interfaces should not contain irrelevant or rarely needed information. Every ele
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Overwhelming — everything competes for attention equally |
-| 1 | Cluttered — too much noise, hard to find what matters |
-| 2 | Some clutter — main content clear, periphery noisy |
-| 3 | Mostly clean — focused design, minor visual noise |
-| 4 | Perfectly minimal — every element earns its pixel |
+| 0 | Overwhelming; everything competes for attention equally |
+| 1 | Cluttered; too much noise, hard to find what matters |
+| 2 | Some clutter; main content clear, periphery noisy |
+| 3 | Mostly clean; focused design, minor visual noise |
+| 4 | Perfectly minimal; every element earns its pixel |
 
 ### 9. Help Users Recognize, Diagnose, and Recover from Errors
 
@@ -178,11 +178,11 @@ Error messages should use plain language, precisely indicate the problem, and co
 **Scoring**:
 | Score | Criteria |
 |-------|----------|
-| 0 | Cryptic errors — codes, jargon, or no message at all |
-| 1 | Vague errors — "Something went wrong" with no guidance |
-| 2 | Clear but unhelpful — names the problem but not the fix |
-| 3 | Clear with suggestions — identifies problem and offers next steps |
-| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work |
+| 0 | Cryptic errors; codes, jargon, or no message at all |
+| 1 | Vague errors; "Something went wrong" with no guidance |
+| 2 | Clear but unhelpful; names the problem but not the fix |
+| 3 | Clear with suggestions; identifies problem and offers next steps |
+| 4 | Perfect recovery; pinpoints issue, suggests fix, preserves user work |
 
 ### 10. Help and Documentation
 
@@ -200,9 +200,9 @@ Even if the system is usable without docs, help should be easy to find, task-foc
 |-------|----------|
 | 0 | No help available anywhere |
 | 1 | Help exists but hard to find or irrelevant |
-| 2 | Basic help — FAQ or docs exist, not contextual |
-| 3 | Good documentation — searchable, mostly task-focused |
-| 4 | Excellent contextual help — right info at the right moment |
+| 2 | Basic help; FAQ or docs exist, not contextual |
+| 3 | Good documentation; searchable, mostly task-focused |
+| 4 | Excellent contextual help; right info at the right moment |
 
 ---
 
@@ -212,11 +212,11 @@ Even if the system is usable without docs, help should be easy to find, task-foc
 
 | Score Range | Rating | What It Means |
 |-------------|--------|---------------|
-| 36–40 | Excellent | Minor polish only — ship it |
+| 36–40 | Excellent | Minor polish only; ship it |
 | 28–35 | Good | Address weak areas, solid foundation |
 | 20–27 | Acceptable | Significant improvements needed before users are happy |
-| 12–19 | Poor | Major UX overhaul required — core experience broken |
-| 0–11 | Critical | Redesign needed — unusable in current state |
+| 12–19 | Poor | Major UX overhaul required; core experience broken |
+| 0–11 | Critical | Redesign needed; unusable in current state |
 
 ---
 
@@ -226,7 +226,7 @@ Tag each individual issue found during scoring with a priority level:
 
 | Priority | Name | Description | Action |
 |----------|------|-------------|--------|
-| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper |
+| **P0** | Blocking | Prevents task completion entirely | Fix immediately; this is a showstopper |
 | **P1** | Major | Causes significant difficulty or confusion | Fix before release |
 | **P2** | Minor | Annoyance, but workaround exists | Fix in next pass |
 | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits |

.claude/skills/impeccable/reference/interaction-design.md

@@ -42,11 +42,11 @@ button:focus-visible {
 
 ## Form Design: The Non-Obvious
 
-**Placeholders aren't labels**—they disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
+**Placeholders aren't labels.** They disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
 
 ## Loading States
 
-**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**—they preview content shape and feel faster than generic spinners.
+**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**: they preview content shape and feel faster than generic spinners.
 
 ## Modals: The Inert Approach
 
@@ -158,7 +158,7 @@ Check viewport boundaries before rendering. If the dropdown would overflow the b
 
 ## Destructive Actions: Undo > Confirm
 
-**Undo is better than confirmation dialogs**—users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
+**Undo is better than confirmation dialogs.** Users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
 
 ## Keyboard Navigation Patterns
 

.claude/skills/impeccable/reference/layout.md

@@ -1,10 +1,10 @@
-Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+Space is the most underused design tool. Find the layout's actual problem (monotone spacing, weak hierarchy, identical card grids, the centered-stack default) and fix the structure, not the surface.
 
 ---
 
 ## Register
 
-Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast — tight groupings paired with generous separations.
+Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast: tight groupings paired with generous separations.
 
 Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
 
@@ -20,8 +20,8 @@ Analyze what's weak about the current spatial design:
    - Are related elements grouped tightly, with generous space between groups?
 
 2. **Visual hierarchy**:
-   - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
-   - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+   - Apply the squint test: blur your (metaphorical) eyes. Can you still identify the most important element, second most important, and clear groupings?
+   - Is hierarchy achieved effectively? (Space and weight alone can be enough; is the current approach working?)
    - Does whitespace guide the eye to what matters?
 
 3. **Grid & structure**:
@@ -39,7 +39,7 @@ Analyze what's weak about the current spatial design:
    - Is the layout too sparse? (Excessive whitespace without purpose)
    - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
 
-**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material; use it with intention.
 
 ## Plan Layout Improvements
 
@@ -47,7 +47,7 @@ Consult the [spatial design reference](spatial-design.md) for detailed guidance
 
 Create a systematic plan:
 
-- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Spacing system**: Use a consistent scale (a framework's built-in scale like Tailwind's, rem-based tokens, or a custom system). The specific values matter less than consistency.
 - **Hierarchy strategy**: How will space communicate importance?
 - **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
 - **Rhythm**: Where should spacing be tight vs generous?
@@ -56,17 +56,17 @@ Create a systematic plan:
 
 ### Establish a Spacing System
 
-- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Use a consistent spacing scale (framework scales like Tailwind, rem-based tokens, or a custom scale all work). What matters is that values come from a defined set, not arbitrary numbers.
 - Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
-- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Use `gap` for sibling spacing instead of margins; eliminates margin collapse hacks
 - Apply `clamp()` for fluid spacing that breathes on larger screens
 
 ### Create Visual Rhythm
 
 - **Tight grouping** for related elements (8-12px between siblings)
 - **Generous separation** between distinct sections (48-96px)
-- **Varied spacing** within sections — not every row needs the same gap
-- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+- **Varied spacing** within sections (not every row needs the same gap)
+- **Asymmetric compositions**: break the predictable centered-content pattern when it makes sense
 
 ### Choose the Right Layout Tool
 
@@ -74,40 +74,40 @@ Create a systematic plan:
 - **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
 - **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
 - Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
-- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts; redefine at breakpoints.
 
 ### Break Card Grid Monotony
 
-- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
-- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Don't default to card grids for everything; spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable. Never nest cards inside cards
 - Vary card sizes, span columns, or mix cards with non-card content to break repetition
 
 ### Strengthen Visual Hierarchy
 
-- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
-- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough; generous whitespace around an element draws the eye. Some of the most polished designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow: in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
 - Create clear content groupings through proximity and separation.
 
 ### Manage Depth & Elevation
 
 - Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
-- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Build a consistent shadow scale (sm → md → lg → xl); shadows should be subtle
 - Use elevation to reinforce hierarchy, not as decoration
 
 ### Optical Adjustments
 
-- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+- If an icon looks visually off-center despite being geometrically centered, nudge it. But only if you're confident it actually looks wrong. Don't adjust speculatively.
 
 **NEVER**:
 - Use arbitrary spacing values outside your scale
-- Make all spacing equal — variety creates hierarchy
-- Wrap everything in cards — not everything needs a container
-- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Make all spacing equal (variety creates hierarchy)
+- Wrap everything in cards (not everything needs a container)
+- Nest cards inside cards (use spacing and dividers for hierarchy within)
 - Use identical card grids everywhere (icon + heading + text, repeated)
-- Center everything — left-aligned with asymmetry feels more designed
-- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
-- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
-- Use arbitrary z-index values (999, 9999) — build a semantic scale
+- Center everything (left-aligned with asymmetry feels more designed)
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work, but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler; use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999); build a semantic scale
 
 ## Verify Layout Improvements
 
@@ -118,11 +118,11 @@ Create a systematic plan:
 - **Consistency**: Is the spacing system applied uniformly?
 - **Responsiveness**: Does the layout adapt gracefully across screen sizes?
 
-Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
+When the rhythm and hierarchy land, hand off to `/impeccable polish` for the final pass.
 
 ## Live-mode signature params
 
-Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * <base>)` — paddings, gaps, column widths. Users slide from airy to packed and see layout re-breathe with no regeneration.
+Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * <base>)`: paddings, gaps, column widths. Users slide from airy to packed and see layout re-breathe with no regeneration.
 
 ```json
 {"id":"density","kind":"range","min":0.6,"max":1.4,"step":0.05,"default":1,"label":"Density"}

.claude/skills/impeccable/reference/live.md

@@ -8,17 +8,18 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR
 
 Execute in order. No step skipped, no step reordered.
 
-1. `live.mjs` — boot.
-2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app.
+1. `live.mjs`: boot.
+2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL; it's the helper, not the app.
 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
-4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again.
-5. On `accept` / `discard` — the poll script already cleaned up; just poll again.
-6. On `exit` — run the cleanup at the bottom.
+4. On `generate`: read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again.
+5. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts remain recoverable until you finish cleanup, run `live-complete.mjs --id EVENT_ID`, and only then poll again.
+6. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
 - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell.
-- **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout.
-- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.
+- **Cursor**: run the poll in the **foreground** (blocking shell; not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout.
+- **Codex**: run the poll in the **foreground** (blocking shell; not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.
 - **Other harnesses**: foreground unless you know stdout reliably returns to this session.
 
 Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
@@ -29,7 +30,7 @@ Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodi
 node .claude/skills/impeccable/scripts/live.mjs
 ```
 
-Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath, migrated }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md and DESIGN.md in mind for variant generation — **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** If `migrated: true`, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md`; mention this once and suggest `/impeccable document` for the matching DESIGN.md.
+Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath, migrated }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md and DESIGN.md in mind for variant generation; **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure from existing identity requires an explicit trigger from PRODUCT.md anti-references or the user's freeform prompt. If `migrated: true`, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md`; mention this once and suggest `/impeccable document` for the matching DESIGN.md.
 
 `serverPort` and `serverToken` belong to the small **Impeccable live helper** HTTP server (serves `/live.js`, SSE, and `/poll`). That port is **not** your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the `pageFiles` entries (Vite / Next / Bun / tunnel / LAN hostname).
 
@@ -43,22 +44,40 @@ LOOP:
   Read JSON; dispatch on "type"
 
   "generate"  → Handle Generate; reply done; LOOP
-  "accept"    → Handle Accept; LOOP
+  "accept"    → Handle Accept; complete carbonize cleanup if required; LOOP
   "discard"   → Handle Discard; LOOP
   "prefetch"  → Handle Prefetch; LOOP
   "timeout"   → LOOP
   "exit"      → break → Cleanup
 ```
 
+## Recovery commands
+
+The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
+
+Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
+
+```bash
+node .claude/skills/impeccable/scripts/live-status.mjs
+node .claude/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
+node .claude/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
+```
+
+- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
+- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
+- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
+
+Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
+
 ## Handle `generate`
 
 Event: `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
 
-Speed matters — the user is watching a spinner. Minimize tool calls by using the `wrap` helper and writing all variants in a single edit.
+Speed matters; the user is watching a spinner. Minimize tool calls by using the `wrap` helper and writing all variants in a single edit.
 
 ### 1. Read the screenshot (if present)
 
-`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning** — annotations encode user intent not recoverable from `element.outerHTML` alone.
+`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
 
 When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
 
@@ -66,32 +85,42 @@ When `screenshotPath` is absent, don't ask for one and don't go looking for the
 
 Reading annotations precisely:
 
-- **Comment position is load-bearing.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
+- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
 - **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
-- **Strokes are gestures — read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
+- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
 - **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
 
 ### 2. Wrap the element
 
 ```bash
-node .claude/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div"
+node .claude/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
 ```
 
-Flag mapping — keep them separate, don't collapse into `--query`:
+Flag mapping. Keep them separate, don't collapse into `--query`:
 
 - `--element-id` ← `event.element.id`
 - `--classes` ← `event.element.classes` joined with commas
 - `--tag` ← `event.element.tagName`
+- `--text` ← first ~80 chars of `event.element.textContent` (trim, single-line). **Pass this every call.** When the picked element shares classes + tag with sibling components (a list of `<Card>`s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.
 
-The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only — do not use it for normal element lookups.
+The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only; do not use it for normal element lookups.
 
-Output on success: `{ file, insertLine, commentSyntax }`.
+If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing — accepting a variant into a generated file is silent data loss. Three shapes:
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
 
-- `{ error: "file_is_generated", file, hint }` — user-supplied `--file` points at a generated file.
-- `{ error: "element_not_in_source", generatedMatch, hint }` — element exists only in a generated file (the next build would wipe any edits).
-- `{ error: "element_not_found", hint }` — element isn't in any project file; likely runtime-injected (JS component, data-driven render).
+`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
+
+- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
+- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
+
+Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
+
+**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
+
+- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
+- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
+- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
 
 All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
 
@@ -101,68 +130,118 @@ If `event.action` is `impeccable` (the default freeform action), use SKILL.md's
 
 Any other `event.action` (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): Read `reference/<action>.md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
 
-### 4. Plan three genuinely distinct directions
+### 4. Plan three variants: identity first, then mode, then axes
 
-Before writing a single line of code, name each variant.
+The wrong frame for live mode is "show three different design directions." Live runs on an existing surface; the brand has already been chosen. The job is variation **within identity**, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.
 
-**For freeform (`action` is `impeccable`, or the user supplied a free prompt):** each variant must anchor to a different **archetype** — a real-world design analogue specific enough to be recognizable at a glance. Not "modern landing page." Not "minimal product hero." Examples:
+Four phases. Do them in order.
 
-- *Broadsheet masthead with rule-divided columns* (think NYT print edition)
-- *Klim Type Foundry specimen page* (dense, technical, catalog-driven)
-- *Japanese print-poster minimalism with a single oversize glyph*
-- *Bloomberg Terminal status bar*
-- *Condé Nast Traveler feature layout*
+#### Phase A: Extract the identity (non-skippable)
 
-Then commit each variant to a different **primary axis** of difference:
+The existing surface has an identity already. Read it before planning anything. Sources, in priority order:
 
-1. **Hierarchy** — which element commands the eye?
-2. **Layout topology** — stacked / side-by-side / grid / asymmetric / overlay
-3. **Typographic system** — pairing, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
-5. **Density** — minimal / comfortable / dense
-6. **Structural decomposition** — merge, split, progressive disclosure
+1. **DESIGN.md** if loaded: read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.
+2. **CSS custom properties** in the page's stylesheets (`:root { --color-...; --font-...; ... }`): these are de-facto tokens.
+3. **Computed styles** on the picked element and its parent: colors, fonts, spacing scales, corner radii.
+4. **Sibling components on the page**: what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)
 
-Three variants → three DIFFERENT primary axes, not three riffs on color.
+Write down what you see in **one sentence**. The sentence describes the surface that's actually on screen; it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:
 
-**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for one dark-neutral-accent, one light-drenched, one full-palette-saturated — three color worlds, not three shades of the same.
+- The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").
+- The type pairing: the actual font names loaded, primary first.
+- The layout topology: how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).
+- The surface treatment: corners, borders, shadows, density of decoration.
+- The voice tone you read off the copy itself, not off the aesthetic feel.
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.
 
-> V1: Broadsheet masthead, ruled columns, 24px ink on cream.
-> V2: Enormous italic title, catalog spec rows, heavy monospace data.
-> V3: Card-framed poster with one oversize glyph, magenta veil.
+Do not include adjectives that name an aesthetic family ("editorial-leaning", "terminal-flavored", "brutalist"); those are conclusions, not data. They belong to Phase C lane selection in departure mode, not to identity description. Letting them sneak into Phase A is how the identity-lock collapses into a self-fulfilling prophecy.
 
-If two of them rhyme ("both use big type" / "both are stacks of sections" / "both feature the CTA prominently"), rework the offender. Freeform variants failing the squint test is the primary failure mode of this flow — three-of-the-same with minor styling tweaks.
+This sentence is the **identity lock**. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse; extract from CSS and computed styles instead.
+
+#### Phase B: Pick mode (default vs departure)
+
+**Default mode**: the existing identity is preserved. Variants vary expression axes within it. *This is the right mode for ~90% of live sessions.* The user picked an element on a real product they're shipping; they expect variants of *their* hero, not three different brands' heroes.
+
+**Departure mode**: the existing identity is rejected. Variants propose alternatives consistent with PRODUCT.md voice. Trigger only when at least one is true:
+
+- PRODUCT.md anti-references explicitly call out the current surface ("the current `index.html` is itself an example"; "diffuse away from this"; "the page on screen is the failure"). Generic anti-references that describe what to avoid in general do **not** trigger departure mode; only ones that point at *this* surface specifically.
+- The user's freeform prompt explicitly asks for departure ("rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different").
+
+If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel": recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants": unrecoverable, the user is annoyed.
+
+#### Phase C: Plan three variants
+
+**Default mode.** Each variant commits to a different **primary axis** of difference, while preserving the identity sentence. The six axes:
+
+1. **Hierarchy**: which element commands the eye?
+2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
+3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
+4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
+5. **Density**: minimal / comfortable / dense
+6. **Structural decomposition**: merge, split, progressive disclosure
+
+Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
+
+**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
+
+**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from the brand's stated voice and register in PRODUCT.md. Do NOT pick from a fixed catalog of lane categories. The right three directions for this brand are not the same as the right three for another brand, and picking from a list is itself the training-data reflex (the model selects "Swiss-grid, Terminal, Industrial-signage" every time because those are the furthest-from-editorial items in any enumerated list).
+
+Instead, work from the brand:
+
+1. Read PRODUCT.md's Brand Personality words. What physical, spatial, or material experiences would embody those words if design were not involved? (A personality described as "specific, earned, unmistakable" evokes a hand-stamped letter, a numbered print, a watchmaker's loupe. A personality described as "restless, loud, unfiltered" evokes a concert poster, a spray-painted wall, a megaphone.)
+2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
+3. Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. If you find yourself reaching for "Swiss-grid" or "Terminal" or "Industrial-signage" by reflex, you are pattern-matching a catalog in your training data, not reading the brand. Start over from the personality words.
+4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
+5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
+
+#### Phase D: Squint test
+
+**Default mode squint.** Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident; rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.
+
+**Departure mode squint.** Two passes, family before sentence:
+
+1. **Family pass.** Label each variant with one design-family word of your own choosing (any concrete noun: *exhibition, storefront, cockpit, recipe-card, playbill, field-manual*). If any two variants share a label, or if the label could apply to the other variants equally well, rework. Do not use a fixed vocabulary list for the labels. *This pass is non-negotiable in departure mode and catches the monoculture failure that the sentence pass misses.*
+2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
+
+**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
 
 **For action-specific invocations**, each variant must vary along the dimension the action names:
 
-- `bolder` — amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
-- `quieter` — pull back a different dimension (color / ornament / spacing).
-- `distill` — remove a different class of excess (visual noise / redundant content / nested structure).
-- `polish` — target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
-- `typeset` — different type pairing AND different scale ratio each. Not three riffs on one pairing.
-- `colorize` — different hue family each (not shades of one hue). Vary chroma and contrast strategy.
-- `layout` — different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
-- `adapt` — different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
-- `animate` — different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
-- `delight` — different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
-- `overdrive` — different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step — live mode is non-interactive.
+- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
+- `quieter`: pull back a different dimension (color / ornament / spacing).
+- `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
+- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
+- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
+- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
+- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
+- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
+- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
+- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
+- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
 
 ### 5. Apply the freeform prompt (if present)
 
-`event.freeformPrompt` is the user's ceiling on direction — all variants must honor it — but still explore meaningfully different *interpretations*. "Make it feel like a newspaper front page" → variant 1 = broadsheet masthead + rule-divided columns, variant 2 = tabloid headline + single dominant image, variant 3 = minimalist editorial with oversized drop cap. Not three newspapers in the same voice.
+`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. The interpretations stay within whichever mode you picked in Phase B.
+
+In **default mode**, the prompt narrows the axes you choose, not the identity. *"Make it feel more confident"* → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.
+
+In **departure mode**, the prompt narrows the lanes you draw from, not the families. *"Make it feel like a newspaper front page"* would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.
+
+When the prompt and PRODUCT.md anti-references conflict (the prompt asks for X, the anti-references ban X), the anti-references win; they describe the brand's standing position, the prompt is one moment.
 
 ### 6. Write all variants in a single edit
 
 Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
 
-Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate scoped CSS as a `<style>` tag inside the variant wrapper — `<style>` works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).
+Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).
+
+Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
 
 ```html
 <!-- Variants: insert below this line -->
 <style data-impeccable-css="SESSION_ID">
-  @scope ([data-impeccable-variant="1"]) { ... }
-  @scope ([data-impeccable-variant="2"]) { ... }
+  /* rules matching cssAuthoring.rulePattern */
 </style>
 <div data-impeccable-variant="1">
   <!-- variant 1: full element replacement (single top-level element) -->
@@ -175,11 +254,30 @@ Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Col
 </div>
 ```
 
-**Each variant div contains exactly one top-level element — the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
+**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
 
-The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no scoped CSS, omit the `<style>` tag entirely. Use `@scope` for CSS isolation (Chrome 118+ / Firefox 128+ / Safari 17.4+).
+The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
 
-One edit, all variants — the browser's MutationObserver picks everything up in one pass.
+One edit, all variants; the browser's MutationObserver picks everything up in one pass.
+
+For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
+
+**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
+
+```tsx
+<style data-impeccable-css="SESSION_ID">{`
+  @scope ([data-impeccable-variant="1"]) { ... }
+  @scope ([data-impeccable-variant="2"]) { ... }
+`}</style>
+<div data-impeccable-variant="1">
+  {/* variant 1 */}
+</div>
+<div data-impeccable-variant="2" style={{ display: 'none' }}>
+  {/* variant 2 */}
+</div>
+```
+
+The wrap script already gives you a single-rooted JSX wrapper: a `<div data-impeccable-variants="…">` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
 
 ### 7. Parameters (composition-sized, 0–4 per variant)
 
@@ -189,18 +287,18 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
 
-**Freeform (`action` is `impeccable`) bias.** You did not load `reference/bolder.md` (etc.), so you must **choose** 1–2 signature-like axes yourself. Prefer knobs that sit on the same dimensions as your three directions (e.g. all three riffs on editorial density → expose `density` or a `steps` “air / snug / packed”; two directions differ mostly in chroma → add `color-amount`). A hero, section, or other **large** surface that ships with **0** params needs a one-line reason in your head (e.g. “truly a fixed-point A/B/C comparison, no shared dial”), not a default habit.
+**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
 
 **Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
 
-- **Leaf / tiny** — a single button, icon, input, bare heading, solitary paragraph: **0 params.**
-- **Small composition** — labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
-- **Medium composition** — section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
-- **Large composition** — hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
+- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
+- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
+- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
+- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
 
 **When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
 
-**Hard cap per variant** — at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
+**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
 
 **How to declare.** Put a JSON manifest on the variant wrapper:
 
@@ -220,9 +318,9 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **Three kinds:**
 
-- `range` — smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
-- `steps` — segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
-- `toggle` — on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
+- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
+- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
+- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
 
 **Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
 
@@ -242,10 +340,20 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
 node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
 ```
 
-`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.) — the browser fetches source directly if the dev server lacks HMR.
+`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
 
 Then run `live-poll.mjs` again immediately.
 
+### Aborting an in-flight session
+
+If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
+
+```bash
+node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
+```
+
+Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
+
 ## Handle fallback
 
 When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
@@ -256,9 +364,9 @@ The goal is the same: give the user three variants to choose from AND persist th
 
 Use the error payload:
 
-- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"` — the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
-- `element_not_found` — the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
-- `file_is_generated` with `file: "..."` — user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
+- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
+- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
+- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
 
 Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
 
@@ -266,19 +374,19 @@ Read the candidate source until you're confident where a change to the element w
 
 The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
 
-1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces — `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
+1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
 2. Insert your three variant divs inside it, same shape as the deterministic path.
 3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
 
-This served-file edit is **temporary** — next regen wipes it, and that's fine. The real work happens on accept.
+This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
 
 ### Step 3: On accept, write to true source
 
-When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files — see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
+When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
 
 - Structural change → edit the template / component source.
 - Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
-- Data-driven → update the data source or the render logic.
+- Dynamic from data → update the data source or the render logic.
 
 Then remove the temporary wrapper from the served file if it's still there.
 
@@ -288,45 +396,46 @@ Remove the wrapper you inserted in Step 2. Nothing else to do.
 
 ## Handle `accept`
 
-Event: `{id, variantId, _acceptResult}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically; the browser DOM is already updated.
+Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
 
-- `_acceptResult.handled: true` and `carbonize: false` — nothing to do. Poll again.
-- `_acceptResult.handled: true` and `carbonize: true` — **post-accept cleanup is required before the next poll.** See the "Required after accept (carbonize)" section below. The `event._acceptResult.todo` field and a stderr banner both list the steps explicitly; neither is decorative.
-- `_acceptResult.handled: false, mode: "fallback"` — the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
-- `_acceptResult.handled: false` without `mode` — manual cleanup: read file, find markers, edit.
+- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
+- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
+- `_acceptResult.handled: true` and `carbonize: true`: **post-accept cleanup is required before the next poll.** See the "Required after accept (carbonize)" section below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and a stderr banner all point at this required follow-up; none are decorative. After cleanup, run `live-complete.mjs --id EVENT_ID`, then poll again.
+- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
+- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
 
 ### Required after accept (carbonize)
 
-When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file — all of which accumulate across sessions.
+When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
 
 Do these five steps in the current thread, synchronously, before the next poll. Do not poll again until the file is clean.
 
-1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values — read it first; it drives steps 3 and 4 below.
-2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `public/css/workflow.css` for this repo, or the component's co-located CSS file for a Vite/Next project — pick whichever already owns styling for the surrounding element).
+1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
+2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
 3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it — those are live-mode plumbing, not source.
-5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one — those are dead code now.
+4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it; those are live-mode plumbing, not source.
+5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
 
-Then poll again.
+After the file is clean, run `live-complete.mjs --id SESSION_ID`, verify it reports `phase: "completed"`, then poll again.
 
 A background agent may be used for the rewrite, but the current thread is responsible for verifying the five steps are complete before issuing the next poll. In practice, inline is usually faster and less error-prone.
 
 ## Handle `discard`
 
-Event: `{id, _acceptResult}`. The poll script already restored the original and removed all variant markers. Nothing to do. Poll again.
+Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
 
 ## Handle `prefetch`
 
-Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut — it signals the user is likely about to Go on a page you haven't read yet.
+Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
 
 Resolve `pageUrl` to the underlying file:
 
 - Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
 - Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
 
-Read the file into context, then poll again. No `--reply` — this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
+Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
 
-Dedupe is the browser's job (one prefetch per unique pathname per session) — trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
+Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
 
 ## Exit
 
@@ -343,7 +452,7 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
 node .claude/skills/impeccable/scripts/live-server.mjs stop
 ```
 
-Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `config.json` persists for future sessions.
+Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
 
 Then:
 - Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
@@ -351,7 +460,7 @@ Then:
 
 ## First-time setup (config missing or invalid)
 
-If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write `config.json` at the reported path.
+If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
 
 Schema:
 
@@ -365,7 +474,7 @@ Schema:
 }
 ```
 
-`files` is the inject target — **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
+`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
 
 `exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
 
@@ -383,13 +492,13 @@ Schema:
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
-| Multi-page (separate HTML per route) | `["public/**/*.html"]` — a glob covering the served directory | `</body>` | `html` |
+| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
-For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected — it writes to true source via the fallback flow.
+For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
 
 ### Drift-heal warning
 
@@ -417,7 +526,7 @@ When `configDrift` is present, surface it to the user once per session before en
 >
 > Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
 
-Don't auto-update the config — let the user decide. `configDrift` is `null` when there's no drift.
+Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
 
 ### CSP detection (first-time only)
 
@@ -431,21 +540,21 @@ node .claude/skills/impeccable/scripts/detect-csp.mjs
 
 Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
 
-- **`null`** — no CSP; skip to writing `config.json` with `cspChecked: true`.
-- **`append-arrays`** — CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
+- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
+- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
   - Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
   - SvelteKit `kit.csp.directives`
   - Nuxt `nuxt-security` module's `contentSecurityPolicy`
-- **`append-string`** — CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
+- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
   - Inline `next.config.*` `headers()` with a CSP literal
   - Nuxt `routeRules` / `nitro.routeRules` headers
-- **`middleware`** or **`meta-tag`** — rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
+- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
 
 #### Consent prompt template
 
 Use this phrasing so the experience is consistent across agents:
 
-> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400` — the live picker won't load without an allowance. Here's the change I'd make:
+> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
 >
 > ```diff
 > [file: <patchTarget>]
@@ -472,9 +581,9 @@ const __impeccableLiveDev =
 
 **Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
 
-- **Next.js + monorepo helper** — edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
-- **SvelteKit** — edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
-- **Nuxt + nuxt-security** — edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
+- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
+- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
+- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
 
 Reference outputs:
 - `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
@@ -499,8 +608,8 @@ Then in the CSP value string:
 (Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
 
 Per-framework specifics:
-- **Next.js inline `headers()`** — edit `next.config.*`, splicing the variable into the CSP value.
-- **Nuxt `routeRules`** — edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
+- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
+- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
 
 Reference outputs:
 - `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
@@ -508,6 +617,6 @@ Reference outputs:
 
 ### Troubleshooting
 
-If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `config.json` and re-run `live.mjs` — setup will ask again.
+If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
 
 Then re-run `live.mjs`.

.claude/skills/impeccable/reference/motion-design.md

@@ -11,7 +11,7 @@ Timing matters more than easing. These durations feel right for most UI:
 | **300-500ms** | Layout changes | Accordion, modal, drawer |
 | **500-800ms** | Entrance animations | Page load, hero reveals |
 
-**Exit animations are faster than entrances**—use ~75% of enter duration.
+**Exit animations are faster than entrances.** Use ~75% of enter duration.
 
 ## Easing: Pick the Right Curve
 
@@ -23,7 +23,7 @@ Timing matters more than easing. These durations feel right for most UI:
 | **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
 | **ease-in-out** | State toggles (there → back) | `cubic-bezier(0.65, 0, 0.35, 1)` |
 
-**For micro-interactions, use exponential curves**—they feel natural because they mimic real physics (friction, deceleration):
+**For micro-interactions, use exponential curves.** They feel natural because they mimic real physics (friction, deceleration):
 
 ```css
 /* Quart out - smooth, refined (recommended default) */
@@ -36,7 +36,7 @@ Timing matters more than easing. These durations feel right for most UI:
 --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
 ```
 
-**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop—they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.
+**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop; they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.
 
 ## Premium Motion Materials
 
@@ -54,7 +54,7 @@ The hard rule is not "transform and opacity only." The hard rule is: avoid anima
 
 ## Staggered Animations
 
-Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time**—10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
+Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time**: 10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
 
 ## Reduced Motion
 
@@ -82,19 +82,19 @@ This is not optional. Vestibular disorders affect ~35% of adults over 40.
 }
 ```
 
-**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work—just without spatial movement.
+**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work, just without spatial movement.
 
 ## Perceived Performance
 
-**Nobody cares how fast your site is—just how fast it feels.** Perception can be as effective as actual performance.
+**Nobody cares how fast your site is, just how fast it feels.** Perception can be as effective as actual performance.
 
 **The 80ms threshold**: Our brains buffer sensory input for ~80ms to synchronize perception. Anything under 80ms feels instant and simultaneous. This is your target for micro-interactions.
 
 **Active vs passive time**: Passive waiting (staring at a spinner) feels longer than active engagement. Strategies to shift the balance:
 
 - **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
-- **Early completion**: Show content progressively—don't wait for everything. Video buffering, progressive images, streaming HTML.
-- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Instagram likes work offline—the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.
+- **Early completion**: Show content progressively, don't wait for everything. Video buffering, progressive images, streaming HTML.
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Instagram likes work offline; the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.
 
 **Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances, but ease-in toward a task's end compresses perceived time.
 
@@ -102,7 +102,7 @@ This is not optional. Vestibular disorders affect ~35% of adults over 40.
 
 ## Performance
 
-Don't use `will-change` preemptively—only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
+Don't use `will-change` preemptively, only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
 
 ---
 

.claude/skills/impeccable/reference/onboard.md

@@ -1,6 +1,6 @@
 > **Additional context needed**: the "aha moment" you want users to reach, and users' experience level.
 
-Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
+Get users to first value as fast as possible. Onboarding's job is not to teach the product. Its job is to get people to the moment that proves the product is worth their time.
 
 ## Assess Onboarding Needs
 
@@ -231,4 +231,4 @@ Test with real users:
 - **Completion rate**: Are users completing? (If low, simplify)
 - **Time to value**: How long until users get first value?
 
-Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.
+When users hit the aha moment fast and don't drop off, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/optimize.md

@@ -1,4 +1,4 @@
-Identify and fix performance issues to create faster, smoother user experiences.
+Performance is a feature. Identify the actual bottleneck for THIS interface, fix it, then measure. Don't optimize what isn't slow.
 
 ## Assess Performance Issues
 
@@ -255,4 +255,4 @@ Test that optimizations worked:
 - **No regressions**: Ensure functionality still works
 - **User perception**: Does it *feel* faster?
 
-Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
+When the user-facing numbers move, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/overdrive.md

@@ -30,16 +30,16 @@ Technically ambitious effects almost never work on the first try. You MUST activ
 The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
 
 ### For visual/marketing surfaces
-Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
+Pages, hero sections, landing pages, portfolios: the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
 
 ### For functional UI
-Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
+Tables, forms, dialogs, navigation: the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
 
 ### For performance-critical UI
 The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
 
 ### For data-heavy interfaces
-Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
+Charts and dashboards: the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
 
 **The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
 
@@ -48,36 +48,36 @@ Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering vi
 Organized by what you're trying to achieve, not by technology name.
 
 ### Make transitions feel cinematic
-- **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
-- **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes
-- **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
+- **View Transitions API** (same-document: all browsers; cross-document: no Firefox): shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
+- **`@starting-style`** (all browsers): animate elements from `display: none` to visible with CSS only, including entry keyframes
+- **Spring physics**: natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
 
 ### Tie animation to scroll position
-- **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)
+- **Scroll-driven animations** (`animation-timeline: scroll()`): CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only; always provide a static fallback)
 
 ### Render beyond CSS
-- **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
-- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
-- **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
-- **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
+- **WebGL** (all browsers): shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
+- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only): next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
+- **Canvas 2D / OffscreenCanvas**: custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
+- **SVG filter chains**: displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
 
 ### Make data feel alive
-- **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
-- **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
-- **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
+- **Virtual scrolling**: render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
+- **GPU-accelerated charts**: Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
+- **Animated data transitions**: morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
 
 ### Animate complex properties
-- **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
-- **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
+- **`@property`** (all browsers): register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
+- **Web Animations API** (all browsers): JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
 
 ### Push performance boundaries
-- **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
-- **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background.
-- **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
+- **Web Workers**: move computation off the main thread. Heavy data processing, image manipulation, search indexing: anything that would cause jank.
+- **OffscreenCanvas**: render in a Worker thread. The main thread stays free while complex visuals render in the background.
+- **WASM**: near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
 
 ### Interact with the device
-- **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
-- **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
+- **Web Audio API**: spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
+- **Device APIs**: orientation, ambient light, geolocation. Use sparingly and always with user permission.
 
 **NOTE**: This command is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
 
@@ -102,22 +102,22 @@ else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
 ### Performance rules
 
 - Target 60fps. If dropping below 50, simplify.
-- Respect `prefers-reduced-motion` — always. Provide a beautiful static alternative.
+- Respect `prefers-reduced-motion`, always. Provide a beautiful static alternative.
 - Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
 - Pause off-screen rendering. Kill what you can't see.
 - Test on real mid-range devices, not just your development machine.
 
 ### Polish is the difference
 
-The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.
+The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works; ship the version that feels inevitable.
 
 **NEVER**:
-- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion
+- Ignore `prefers-reduced-motion`. This is an accessibility requirement, not a suggestion
 - Ship effects that cause jank on mid-range devices
 - Use bleeding-edge APIs without a functional fallback
 - Add sound without explicit user opt-in
 - Use technical ambition to mask weak design fundamentals; fix those first with other commands
-- Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
+- Layer multiple competing extraordinary moments. Focus creates impact, excess creates noise
 
 ## Verify the Result
 
@@ -127,4 +127,4 @@ The gap between "cool" and "extraordinary" is in the last 20% of refinement: the
 - **The accessibility test**: Enable reduced motion. Still beautiful?
 - **The context test**: Does this make sense for THIS brand and audience?
 
-Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.
+"Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

.claude/skills/impeccable/reference/personas.md

@@ -2,11 +2,12 @@
 
 Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss.
 
-**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags — not generic concerns.
+**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags, not generic concerns.
 
 ---
 
-## 1. Impatient Power User — "Alex"
+## 1. Impatient Power User: "Alex"
+
 
 **Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave.
 
@@ -33,7 +34,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 2. Confused First-Timer — "Jordan"
+## 2. Confused First-Timer: "Jordan"
 
 **Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out.
 
@@ -60,7 +61,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 3. Accessibility-Dependent User — "Sam"
+## 3. Accessibility-Dependent User: "Sam"
 
 **Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences.
 
@@ -88,7 +89,7 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 4. Deliberate Stress Tester — "Riley"
+## 4. Deliberate Stress Tester: "Riley"
 
 **Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience.
 
@@ -115,12 +116,12 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 
 ---
 
-## 5. Distracted Mobile User — "Casey"
+## 5. Distracted Mobile User: "Casey"
 
 **Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection.
 
 **Behaviors**:
-- Uses thumb only — prefers bottom-of-screen actions
+- Uses thumb only; prefers bottom-of-screen actions
 - Gets interrupted mid-flow and returns later
 - Switches between apps frequently
 - Has limited attention span and low patience
@@ -130,12 +131,12 @@ Test the interface through the eyes of 5 distinct user archetypes. Each persona
 - Are primary actions in the thumb zone (bottom half of screen)?
 - Is state preserved if the user leaves and returns?
 - Does it work on slow connections (3G)?
-- Can forms leverage autocomplete and smart defaults?
+- Can forms use autocomplete and smart defaults?
 - Are touch targets at least 44×44pt?
 
 **Red Flags** (report these specifically):
 - Important actions positioned at the top of the screen (unreachable by thumb)
-- No state persistence — progress lost on tab switch or interruption
+- No state persistence; progress lost on tab switch or interruption
 - Large text inputs required where selection would work
 - Heavy assets loading on every page (no lazy loading)
 - Tiny tap targets or targets too close together
@@ -166,7 +167,7 @@ If `CLAUDE.md` contains a `## Design Context` section (generated by `impeccable
 3. Create a persona following this template:
 
 ```
-### [Role] — "[Name]"
+### [Role]: "[Name]"
 
 **Profile**: [2-3 key characteristics derived from Design Context]
 
@@ -175,4 +176,4 @@ If `CLAUDE.md` contains a `## Design Context` section (generated by `impeccable
 **Red Flags**: [3-4 things that would alienate this specific user type]
 ```
 
-Only generate project-specific personas when real Design Context data is available. Don't invent audience details — use the 5 predefined personas when no context exists.
+Only generate project-specific personas when real Design Context data is available. Don't invent audience details; use the 5 predefined personas when no context exists.

.claude/skills/impeccable/reference/polish.md

@@ -2,15 +2,17 @@
 
 Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
 
+Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path.
+
 ## Design System Discovery
 
 Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work.
 
 1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: design principles, target audience, color tokens, spacing scale, typography styles, component API, motion conventions.
 2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established? What flow shapes are used for comparable actions (modal vs full-page, inline vs route, save-on-blur vs explicit submit)?
-3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category — patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
+3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category: patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
 
-If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask — never guess at design system principles.**
+If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask. Never guess at design system principles.**
 
 ## Pre-Polish Assessment
 
@@ -22,7 +24,7 @@ Understand the current state and goals before touching anything:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish — a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
+2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish; a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
 
 3. **Identify polish areas**:
    - Visual inconsistencies
@@ -33,7 +35,14 @@ Understand the current state and goals before touching anything:
    - Loading and transition smoothness
    - Information architecture and flow drift (does this feature reveal complexity the way neighboring features do?)
 
-4. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent — never perfect one corner while leaving another rough.
+4. **Pull in any prior critique** (optional signal): If `/impeccable critique` has been run on the same target, its priority issues are a useful prior for what to address first. Resolve the target to a file path or URL, then:
+   ```bash
+   slug=$(node .claude/skills/impeccable/scripts/critique-storage.mjs slug "<resolved>")
+   node .claude/skills/impeccable/scripts/critique-storage.mjs latest "$slug"
+   ```
+   Exit 0 with body = found; fold the P0/P1 items into your polish list and mention the snapshot path so the user sees what you read. Exit 2 = no snapshot, continue without it. The critique is one input among many. Do your own pass either way.
+
+5. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent; never perfect one corner while leaving another rough.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -60,7 +69,7 @@ Work through these dimensions methodically:
 Visual polish on a misshapen flow is wasted work. Match the *shape* of the experience to the system, not just the surface.
 
 - **Progressive disclosure**: Match how much is revealed when, compared to neighboring features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift, even if every field is perfectly styled.
-- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere — modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
+- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere: modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
 - **Hierarchy & complexity**: The same conceptual weight gets the same visual weight throughout. Primary actions don't become tertiary in one corner of the product, and tertiary actions don't shout.
 - **Empty, loading, and arrival transitions**: How content arrives, updates, and leaves matches how it does in adjacent features.
 - **Naming and mental model**: The feature uses the same nouns and verbs as the rest of the system. A "Workspace" here shouldn't be a "Project" three screens away.
@@ -82,8 +91,8 @@ Visual polish on a misshapen flow is wasted work. Match the *shape* of the exper
 - **Theme consistency**: Works in all theme variants
 - **Color meaning**: Same colors mean same things throughout
 - **Accessible focus**: Focus indicators visible with sufficient contrast
-- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)
-- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency
+- **Tinted neutrals**: No pure gray or pure black; add subtle color tint (0.01 chroma)
+- **Gray on color**: Never put gray text on colored backgrounds; use a shade of that color or transparency
 
 ### Interaction States
 
@@ -103,7 +112,7 @@ Every interactive element needs all states:
 ### Micro-interactions & Transitions
 
 - **Smooth transitions**: All state changes animated appropriately (150-300ms)
-- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
+- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic; they feel dated.
 - **No jank**: Smooth animations; use atmospheric blur/filter/mask/shadow effects when they add polish, but bound expensive paint areas and avoid casual layout-property animation
 - **Appropriate motion**: Motion serves purpose, not decoration
 - **Reduced motion**: Respects `prefers-reduced-motion`
@@ -198,9 +207,11 @@ Go through systematically:
 
 **IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
 
+Sweat the details. Zoom in until the alignment is right and the spacing reads as deliberate. Then ship.
+
 **NEVER**:
 - Polish before it's functionally complete
-- Polish without aligning to the design system — that's decoration on drift
+- Polish without aligning to the design system; that's decoration on drift
 - Guess at design system principles instead of asking when something is ambiguous
 - Spend hours on polish if it ships in 30 minutes (triage)
 - Introduce bugs while polishing (test thoroughly)
@@ -214,11 +225,12 @@ Go through systematically:
 
 Before marking as done:
 
-- **Use it yourself**: Actually interact with the feature
-- **Test on real devices**: Not just browser DevTools
-- **Ask someone else to review**: Fresh eyes catch things
-- **Compare to design**: Match intended design
-- **Check all states**: Don't just test happy path
+- **Use it yourself**: Actually interact with the feature.
+- **Test on real devices**: Not just browser DevTools.
+- **Ask someone else to review**: Fresh eyes catch things.
+- **Compare to design**: Match intended design.
+- **Check all states**: Don't just test happy path.
+- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished.
 
 ## Clean Up
 
@@ -228,5 +240,3 @@ After polishing, ensure code quality:
 - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.
 - **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
 - **Verify DRYness**: Look for duplication introduced during polishing and consolidate.
-
-Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.

.claude/skills/impeccable/reference/product.md

@@ -4,7 +4,7 @@ When design SERVES the product: app UIs, admin dashboards, settings panels, data
 
 ## The product slop test
 
-Not "would someone say AI made this" — familiarity is often a feature here. The test is: would a user fluent in the category's best tools (Linear, Figma, Notion, Raycast, Stripe come to mind) sit down and trust this interface, or pause at every subtly-off component?
+Not "would someone say AI made this." Familiarity is often a feature here. The test is: would a user fluent in the category's best tools (Linear, Figma, Notion, Raycast, Stripe come to mind) sit down and trust this interface, or pause at every subtly-off component?
 
 Product UI's failure mode isn't flatness, it's strangeness without purpose: over-decorated buttons, mismatched form controls, gratuitous motion, display fonts where labels should be, invented affordances for standard tasks. The bar is earned familiarity. The tool should disappear into the task.
 
@@ -14,19 +14,19 @@ Product UI's failure mode isn't flatness, it's strangeness without purpose: over
 - **One family is often right.** Product UIs don't need display/body pairing. A well-tuned sans carries headings, buttons, labels, body, data.
 - **Fixed rem scale, not fluid.** Clamp-sized headings don't serve product UI. Users view at consistent DPI, and a fluid h1 that shrinks in a sidebar looks worse, not better.
 - **Tighter scale ratio.** 1.125–1.2 between steps is typical. More type elements here than on brand surfaces; exaggerated contrast creates noise.
-- **Line length still applies for prose** (65–75ch). Data and compact UI can run denser — tables at 120ch+ are fine.
+- **Line length still applies for prose** (65–75ch). Data and compact UI can run denser; tables at 120ch+ are fine.
 
 ## Color
 
-Product defaults to Restrained. A single surface can earn Committed — a dashboard where one category color carries a report, an onboarding flow with a drenched welcome screen — but Restrained is the floor.
+Product defaults to Restrained. A single surface can earn Committed (a dashboard where one category color carries a report, an onboarding flow with a drenched welcome screen), but Restrained is the floor.
 
 - State-rich semantic vocabulary: hover, focus, active, disabled, selected, loading, error, warning, success, info. Standardize these.
-- Accent color used for primary actions, current selection, and state indicators only — not decoration.
+- Accent color used for primary actions, current selection, and state indicators only, not decoration.
 - A second neutral layer for sidebars, toolbars, and panels (slightly cooler or warmer than the content surface).
 
 ## Layout
 
-- Predictable grids. Consistency IS an affordance — users navigate faster when the structure is expected.
+- Predictable grids. Consistency IS an affordance; users navigate faster when the structure is expected.
 - Familiar patterns are features. Standard navigation (top bar, side nav), breadcrumbs, tabs, and form layouts have established user expectations. Don't reinvent for flavor.
 - Responsive behavior is structural (collapse sidebar, responsive table, breakpoint-driven columns), not fluid typography.
 
@@ -40,8 +40,8 @@ Every interactive component has: default, hover, focus, active, disabled, loadin
 
 ## Motion
 
-- 150–250 ms on most transitions. Users are in flow — don't make them wait for choreography.
-- Motion conveys state, not decoration. State change, feedback, loading, reveal — nothing else.
+- 150–250 ms on most transitions. Users are in flow; don't make them wait for choreography.
+- Motion conveys state, not decoration. State change, feedback, loading, reveal: nothing else.
 - No orchestrated page-load sequences. Product loads into a task; users don't want to watch it load.
 
 ## Product bans (on top of the shared absolute bans)

.claude/skills/impeccable/reference/quieter.md

@@ -1,12 +1,12 @@
-Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
+Quiet design is harder than bold design. Subtlety needs precision. Reduce visual intensity in designs that are too loud, aggressive, or overstimulating without losing personality or making the result generic.
 
 ---
 
 ## Register
 
-Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated — the POV stays intact.
+Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the POV stays intact.
 
-Product: "quieter" means reducing visual noise — fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
+Product: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
 
 ---
 
@@ -30,18 +30,18 @@ Analyze what makes the design feel too intense:
 
 If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
 
-**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
+**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness.
 
 ## Plan Refinement
 
 Create a strategy to reduce intensity while maintaining impact:
 
-- **Color approach**: Desaturate or shift to more sophisticated tones?
+- **Color approach**: Desaturate or shift to more restrained tones?
 - **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
 - **Simplification approach**: What can be removed entirely?
 - **Sophistication approach**: How can we signal quality through restraint?
 
-**IMPORTANT**: Great quiet design is harder than great bold design. Subtlety requires precision.
+**IMPORTANT**: Subtlety requires precision. Quiet without intent collapses to generic.
 
 ## Refine the Design
 
@@ -49,11 +49,11 @@ Systematically reduce intensity across these dimensions:
 
 ### Color Refinement
 - **Reduce saturation**: Shift from fully saturated to 70-85% saturation
-- **Soften palette**: Replace bright colors with muted, sophisticated tones
+- **Soften palette**: Replace bright colors with muted tones
 - **Reduce color variety**: Use fewer colors more thoughtfully
 - **Neutral dominance**: Let neutrals do more work, use color as accent (10% rule)
 - **Gentler contrasts**: High contrast only where it matters most
-- **Tinted grays**: Use warm or cool tinted grays instead of pure gray—adds sophistication without loudness
+- **Tinted grays**: Use warm or cool tinted grays instead of pure gray. Adds depth without loudness
 - **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead
 
 ### Visual Weight Reduction
@@ -72,7 +72,7 @@ Systematically reduce intensity across these dimensions:
 - **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing
 - **Remove decorative animations**: Keep functional motion, remove flourishes
 - **Subtle micro-interactions**: Replace dramatic effects with gentle feedback
-- **Refined easing**: Use ease-out-quart for smooth, understated motion—never bounce or elastic
+- **Refined easing**: Use ease-out-quart for smooth, understated motion. Never bounce or elastic
 - **Remove animations entirely** if they're not serving a clear purpose
 
 ### Composition Refinement
@@ -94,6 +94,6 @@ Ensure refinement maintains quality:
 - **Still functional**: Can users still accomplish tasks easily?
 - **Still distinctive**: Does it have character, or is it generic now?
 - **Better reading**: Is text easier to read for extended periods?
-- **Sophistication**: Does it feel more refined and premium?
+- **Restrained, not absent**: Does the POV survive the cuts?
 
-Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.
+When the result feels right, hand off to `/impeccable polish` for the final pass.

.claude/skills/impeccable/reference/responsive-design.md

@@ -6,11 +6,11 @@ Start with base styles for mobile, use `min-width` queries to layer complexity.
 
 ## Breakpoints: Content-Driven
 
-Don't chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
+Don't chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
 
 ## Detect Input Method, Not Just Screen Size
 
-**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries:
+**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:
 
 ```css
 /* Fine pointer (mouse, trackpad) */
@@ -95,7 +95,7 @@ When you need different crops/compositions (not just resolutions):
 
 ## Layout Adaptation Patterns
 
-**Navigation**: Three stages—hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
+**Navigation**: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
 
 ## Testing: Don't Trust DevTools Alone
 

.claude/skills/impeccable/reference/shape.md

@@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co
 
 ### Interview cadence
 
-Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
+Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
 
 - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
 - Ask **2-3 questions per round**, then wait for answers.
 - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific.
-- Round 1 should clarify purpose, audience/context, and success or emotional outcome.
-- Round 2 should clarify content/data/states and scope/fidelity.
-- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved.
+- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough.
+- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction.
+- Round 2, when needed, fills in whatever's still genuinely missing.
+
+**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -36,14 +38,15 @@ Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.
 - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
 - What are the edge cases? (Empty state, error state, first-time use, power user)
 - Is any content dynamic? What changes and how often?
+- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets.
 
 ### Design Direction
 
 Force a visual decision on three fronts. Skip anything PRODUCT.md or DESIGN.md already answers; ask only what's missing.
 
 - **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
-- **Theme via scene sentence.** Write one sentence of physical context for this surface — who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
-- **Two or three named anchor references.** Specific products, brands, objects — not adjectives like "modern" or "clean."
+- **Theme via scene sentence.** Write one sentence of physical context for this surface: who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
+- **Two or three named anchor references.** Specific products, brands, objects. Not adjectives like "modern" or "clean."
 
 ### Scope
 
@@ -54,7 +57,7 @@ Always ask. Sketch quality and shipped quality are different outputs; don't gues
 - **Interactivity.** Static visual / interactive prototype / shipped-quality component?
 - **Time intent.** Quick exploration, or polish until it ships?
 
-Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — carry them through the design brief only.
+Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md; carry them through the design brief only.
 
 ### Constraints
 - Are there technical constraints? (Framework, performance budget, browser support)
@@ -72,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes *
 
 - The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
 - The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
-- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling.
 
-When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+When those conditions are met, this step is mandatory. If image generation isn't natively available, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. The one-line announcement is required, not optional; it forces a conscious decision instead of letting the step quietly evaporate.
 
 Use probes to explore visual lanes, not to replace the brief.
 
@@ -104,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi
 - Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
 - Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
 
-If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief.
+If image generation isn't natively available, announce the skip in one line and proceed to the design brief.
 
 ## Phase 2: Design Brief
 
-After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief.
+After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate.
+
+**Choose the brief shape based on how clear the answers are:**
+
+- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt.
+- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight.
+
+Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point.
+
+Present the brief, then **stop and wait for explicit confirmation**. You are not the judge of whether the user already approved. Even when the brief feels obviously right, ask once and wait. The pause is what separates shape from premature implementation.
 
 ### Brief Structure
 
@@ -124,7 +136,7 @@ Color strategy (Restrained / Committed / Full palette / Drenched) + the theme sc
 If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
 
 **4. Scope**
-Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief.
+Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped; these don't persist beyond the brief.
 
 **5. Layout Strategy**
 High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
@@ -136,16 +148,18 @@ List every state the feature needs: default, empty, loading, error, success, edg
 How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
 
 **8. Content Requirements**
-What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges.
+What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission).
 
 **9. Recommended References**
 Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features).
 
 **10. Open Questions**
-Anything unresolved that the implementer should resolve during build.
+Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X.
 
 ---
 
-STOP and call the AskUserQuestion tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed.
+STOP and call the AskUserQuestion tool to clarify. Ask for explicit confirmation of the brief before finishing.
+
+If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction.
 
 Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.)

.claude/skills/impeccable/reference/spatial-design.md

@@ -4,11 +4,11 @@
 
 ### Use 4pt Base, Not 8pt
 
-8pt systems are too coarse—you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+8pt systems are too coarse; you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
 
 ### Name Tokens Semantically
 
-Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks.
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing; it eliminates margin collapse and cleanup hacks.
 
 ## Grid Systems
 
@@ -43,7 +43,7 @@ Don't rely on size alone. Combine:
 
 ### Cards Are Not Required
 
-Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards**—use spacing, typography, and subtle dividers for hierarchy within a card.
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards.** Use spacing, typography, and subtle dividers for hierarchy within a card.
 
 ## Container Queries
 
@@ -67,11 +67,11 @@ Viewport queries are for page layouts. **Container queries are for components**:
 }
 ```
 
-**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands automatically, without viewport hacks.
 
 ## Optical Adjustments
 
-Text at `margin-left: 0` looks indented due to letterform whitespace—use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
+Text at `margin-left: 0` looks indented due to letterform whitespace; use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
 
 ### Touch Targets vs Visual Size
 
@@ -93,7 +93,7 @@ Buttons can look small but need large touch targets (44px minimum). Use padding
 
 ## Depth & Elevation
 
-Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle—if you can clearly see it, it's probably too strong.
+Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle. If you can clearly see it, it's probably too strong.
 
 ---
 

.claude/skills/impeccable/reference/teach.md

@@ -2,8 +2,8 @@
 
 Gathers design context for a project and writes two complementary files at the project root:
 
-- **PRODUCT.md** (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
-- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+- **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
 
 Every other impeccable command reads these files before doing any work.
 
@@ -19,7 +19,7 @@ The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migr
 
 Decision tree:
 - **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
-- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `/impeccable document` for DESIGN.md.
 - **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
 - **Both exist**: STOP and call the AskUserQuestion tool to clarify. Ask which file to refresh. Skip the one the user doesn't want changed.
 - **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
@@ -44,7 +44,7 @@ Also form a **register hypothesis** from what you find:
 - Brand signals: `/`, `/about`, `/pricing`, `/blog/*`, `/docs/*`, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
 - Product signals: `/app/*`, `/dashboard`, `/settings`, `/(auth)`, forms, data tables, side/top nav, app-shell components.
 
-Register is a hypothesis at this point, not a decision — Step 3 confirms it.
+Register is a hypothesis at this point, not a decision; Step 3 confirms it.
 
 Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
@@ -67,11 +67,11 @@ If the repo is empty or the user's brief is sparse, run a short interview before
 
 Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
 
-### Register (ask first — it shapes everything below)
+### Register (ask first; it shapes everything below)
 
-Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboards, tools — design SERVES the product).
+Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboards, tools: design SERVES the product).
 
-If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface — does that match your intent, or should we treat it differently?"*
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
 
 If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and call the AskUserQuestion tool to clarify. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
 
@@ -84,7 +84,7 @@ If the signal is genuinely split (e.g. a product with a big marketing landing),
 ### Brand & Personality
 - How would you describe the brand personality in 3 words?
 - Reference sites or apps that capture the right feel? What specifically about them?
-  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.) — not generic "modern" adjectives.
+  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.), not generic "modern" adjectives.
   - For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
 - What should this explicitly NOT look like? Any anti-references?
 
@@ -92,7 +92,7 @@ If the signal is genuinely split (e.g. a product with a big marketing landing),
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here.** Those belong in DESIGN.md, not PRODUCT.md.
 
 ## Step 4: Write PRODUCT.md
 
@@ -120,7 +120,7 @@ product
 [What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
 ## Design Principles
-[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence". NOT visual rules like "use OKLCH" or "magenta accent".]
 
 ## Accessibility & Inclusion
 [WCAG level, known user needs, considerations]
@@ -128,7 +128,7 @@ product
 
 Register is either `brand` or `product` as a bare value. No prose, no commentary.
 
-Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
 
 ## Step 5: Decide on DESIGN.md
 

.claude/skills/impeccable/reference/typeset.md

@@ -1,4 +1,4 @@
-Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+Typography carries most of the information on the page. Replace generic defaults (Inter, Roboto, system fallback at flat scale) with type that reflects the brand and scales with intentional contrast.
 
 ---
 
@@ -39,7 +39,7 @@ Analyze what's weak or generic about the current type:
    - Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
    - Is letter-spacing intentional or default everywhere?
 
-**CRITICAL**: The goal isn't to make text "fancier" — it's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
+**CRITICAL**: The goal isn't to make text "fancier." It's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
 
 ## Plan Typography Improvements
 
@@ -49,7 +49,7 @@ Create a systematic plan:
 
 - **Font selection**: Do fonts need replacing? What fits the brand/context?
 - **Type scale**: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
-- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings — or whatever fits)
+- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings, or whatever fits)
 - **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
 
 ## Improve Typography Systematically
@@ -58,7 +58,7 @@ Create a systematic plan:
 
 If fonts need replacing:
 - Choose fonts that reflect the brand personality
-- Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights
+- Pair with genuine contrast (serif + sans, geometric + humanist), or use a single family in multiple weights
 - Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks)
 
 ### Establish Hierarchy
@@ -66,7 +66,7 @@ If fonts need replacing:
 Build a clear type scale:
 - **5 sizes cover most needs**: caption, secondary, body, subheading, heading
 - **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
-- **Combine dimensions**: Size + weight + color + space for strong hierarchy — don't rely on size alone
+- **Combine dimensions**: Size + weight + color + space for strong hierarchy. Don't rely on size alone
 - **App UIs**: Use a fixed `rem`-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
 - **Marketing / content pages**: Use fluid sizing via `clamp(min, preferred, max)` for headings and display text. Keep body text fixed
 
@@ -92,11 +92,11 @@ Build a clear type scale:
 
 **NEVER**:
 - Use more than 2-3 font families
-- Pick sizes arbitrarily — commit to a scale
+- Pick sizes arbitrarily; commit to a scale
 - Set body text below 16px
 - Use decorative/display fonts for body text
 - Disable browser zoom (`user-scalable=no`)
-- Use `px` for font sizes — use `rem` to respect user settings
+- Use `px` for font sizes; use `rem` to respect user settings
 - Default to Inter/Roboto/Open Sans when personality matters
 - Pair fonts that are similar but not identical (two geometric sans-serifs)
 
@@ -109,7 +109,7 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
-Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.
+When the type carries the hierarchy on its own, hand off to `/impeccable polish` for the final pass.
 
 ## Live-mode signature params
 

.claude/skills/impeccable/reference/typography.md

@@ -4,7 +4,7 @@
 
 ### Vertical Rhythm
 
-Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.
+Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony; text and space share a mathematical foundation.
 
 ### Modular Scale & Hierarchy
 
@@ -24,7 +24,7 @@ Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth).
 
 ### Readability & Measure
 
-Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length: narrow columns need tighter leading, wide columns need more.
 
 **Non-obvious**: Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05–0.1, add a touch of letter-spacing (0.01–0.02em), and optionally step the body weight up one notch (regular → medium). The perceived weight drops across all three; fix all three.
 
@@ -93,11 +93,11 @@ Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these override
 
 ### Fluid Type
 
-Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
+Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate (higher vw = faster scaling). Add a rem offset so it doesn't collapse to 0 on small screens.
 
 **Use fluid type for**: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.
 
-**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI — fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
+**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI; fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
 
 **Bound your clamp()**: keep `max-size ≤ ~2.5 × min-size`. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.
 

.claude/skills/impeccable/reference/ux-writing.md

@@ -40,7 +40,7 @@ Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the va
 
 ## Voice vs Tone
 
-**Voice** is your brand's personality—consistent everywhere.
+**Voice** is your brand's personality, consistent everywhere.
 **Tone** adapts to the moment.
 
 | Moment | Tone Shift |
@@ -54,7 +54,7 @@ Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the va
 
 ## Writing for Accessibility
 
-**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
+**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
 
 ## Writing for Translation
 
@@ -96,7 +96,7 @@ Be specific: "Saving your draft..." not "Loading...". For long waits, set expect
 
 ## Confirmation Dialogs: Use Sparingly
 
-Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
 
 ## Form Instructions
 

.claude/skills/impeccable/scripts/critique-storage.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Critique persistence helper.
+ *
+ * Each run of /impeccable critique writes a per-target snapshot to
+ *   .impeccable/critique/<timestamp>__<slug>.md
+ * with a small YAML frontmatter carrying the score + P0/P1 counts.
+ *
+ * /impeccable polish reads the latest matching snapshot at start as its
+ * fix backlog. No other skill auto-reads critique output.
+ *
+ * The slug is derived mechanically from the *resolved* primary artifact
+ * (file path or URL), never from the user's natural-language phrasing.
+ * Slug stability across runs is what lets the trend display work.
+ *
+ * CLI entry points (called from skill instructions):
+ *   node critique-storage.mjs slug <resolved-target>
+ *   node critique-storage.mjs write <slug> <snapshot-body-file>
+ *   node critique-storage.mjs latest <slug>
+ *   node critique-storage.mjs trend <slug> [limit]
+ *
+ * Note: there is intentionally no `ignore` subcommand. ignore.md is a plain
+ * markdown file; the model reads it directly with its file-read tool. This
+ * helper only exists for operations the model can't trivially do inline
+ * (normalizing paths, generating filenames, globbing + parsing frontmatter).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCritiqueDir } from './impeccable-paths.mjs';
+
+const SLUG_MAX = 50;
+
+/**
+ * Mechanically derive a slug from a resolved target. Returns null if the
+ * input doesn't look like a stable identifier (empty, project root, etc).
+ *
+ * Accepts file paths and URLs. The model resolves "the homepage" to a
+ * concrete artifact before calling this — we never slug a natural-language
+ * phrase.
+ */
+export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
+  if (!resolved || typeof resolved !== 'string') return null;
+  const trimmed = resolved.trim();
+  if (!trimmed) return null;
+
+  // URL
+  if (/^https?:\/\//i.test(trimmed)) {
+    let url;
+    try { url = new URL(trimmed); } catch { return null; }
+    const hostPath = `${url.hostname}${url.pathname}`;
+    return kebab(hostPath);
+  }
+
+  // File path. Make it project-relative so two devs critiquing the same
+  // checkout get the same slug regardless of where their repo is cloned.
+  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+  let rel = path.relative(cwd, abs);
+  // If the target is outside cwd, fall back to the basename so we still
+  // produce a stable slug (vs the absolute path, which would include
+  // home dirs / usernames).
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    rel = path.basename(abs);
+  }
+  if (!rel || rel === '.' || rel === '') return null;
+  return kebab(rel);
+}
+
+function kebab(s) {
+  const slug = s
+    .toLowerCase()
+    .replace(/[/\\.]+/g, '-')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!slug) return null;
+  // Cap from the tail — the tail (filename) is more identifying than the
+  // top-level directory.
+  return slug.length <= SLUG_MAX ? slug : slug.slice(slug.length - SLUG_MAX).replace(/^-/, '');
+}
+
+/**
+ * Filename-safe UTC ISO timestamp: hyphens for separators, trailing Z.
+ * Plain colons aren't allowed on Windows filesystems.
+ */
+export function nowFilenameStamp(date = new Date()) {
+  const iso = date.toISOString();           // 2026-05-12T18:30:00.123Z
+  return iso.replace(/[:.]/g, '-').replace(/-\d+Z$/, 'Z');
+}
+
+/**
+ * Write a snapshot for `slug`. `meta` carries the small structured frontmatter
+ * keys read back by readTrend(). `body` is the human-readable critique
+ * report (everything below the frontmatter).
+ *
+ * Returns the absolute path written.
+ */
+export function writeSnapshot({ slug, meta, body, cwd = process.cwd(), now = new Date() }) {
+  if (!slug) throw new Error('writeSnapshot requires a slug');
+  const dir = getCritiqueDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const timestamp = nowFilenameStamp(now);
+  const filePath = path.join(dir, `${timestamp}__${slug}.md`);
+  // Spread `meta` first so internally computed `timestamp` and `slug`
+  // always win. Otherwise a caller-supplied meta blob (parsed from the
+  // IMPECCABLE_CRITIQUE_META env var) could clobber them, leaving the
+  // filename in disagreement with its frontmatter and corrupting trends.
+  const front = serializeFrontmatter({ ...meta, timestamp, slug });
+  fs.writeFileSync(filePath, `${front}\n${body.trim()}\n`, 'utf-8');
+  return filePath;
+}
+
+function serializeFrontmatter(obj) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined || value === null) continue;
+    const str = typeof value === 'string' ? value : String(value);
+    // Quote strings that contain : or # to keep parsing simple.
+    const needsQuotes = typeof value === 'string' && /[:#]/.test(str);
+    lines.push(`${key}: ${needsQuotes ? JSON.stringify(str) : str}`);
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (/^".*"$/.test(value)) {
+      try { value = JSON.parse(value); } catch { /* leave as-is */ }
+    } else if (/^-?\d+$/.test(value)) {
+      value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Return all snapshot files for `slug`, sorted oldest → newest.
+ */
+function listSnapshotsForSlug(slug, cwd) {
+  const dir = getCritiqueDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  const suffix = `__${slug}.md`;
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith(suffix))
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+/**
+ * Return the most recent snapshot for `slug`, or null. Polish reads this
+ * to find its fix backlog when the slug matches.
+ */
+export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
+  const all = listSnapshotsForSlug(slug, cwd);
+  if (!all.length) return null;
+  const latest = all[all.length - 1];
+  const body = fs.readFileSync(latest, 'utf-8');
+  return { path: latest, body, meta: parseFrontmatter(body) };
+}
+
+/**
+ * Return the last `limit` snapshots' frontmatter, oldest → newest.
+ * Critique appends a one-line trend to its output using this.
+ */
+export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
+  const all = listSnapshotsForSlug(slug, cwd);
+  const slice = all.slice(-limit);
+  return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
+}
+
+// ---- CLI ---------------------------------------------------------------
+
+function main(argv) {
+  const [cmd, ...args] = argv;
+  switch (cmd) {
+    case 'slug': {
+      const slug = slugFromTarget(args[0]);
+      if (!slug) { process.stderr.write('no stable slug for input\n'); process.exit(1); }
+      process.stdout.write(`${slug}\n`);
+      return;
+    }
+    case 'write': {
+      const [slug, bodyFile] = args;
+      if (!slug || !bodyFile) { process.stderr.write('usage: write <slug> <body-file>\n'); process.exit(1); }
+      const raw = fs.readFileSync(bodyFile, 'utf-8');
+      // The body file may be a full report. The caller passes the meta as
+      // a JSON object on stdin if it wants structured frontmatter; otherwise
+      // we write with minimal metadata.
+      let meta = {};
+      const metaArg = process.env.IMPECCABLE_CRITIQUE_META;
+      if (metaArg) {
+        try { meta = JSON.parse(metaArg); } catch { /* ignore */ }
+      }
+      const out = writeSnapshot({ slug, meta, body: raw });
+      process.stdout.write(`${out}\n`);
+      return;
+    }
+    case 'latest': {
+      const latest = readLatestSnapshot(args[0]);
+      if (!latest) { process.exit(2); }
+      process.stdout.write(latest.body);
+      return;
+    }
+    case 'trend': {
+      const rows = readTrend(args[0], { limit: args[1] ? Number(args[1]) : 5 });
+      process.stdout.write(JSON.stringify(rows, null, 2) + '\n');
+      return;
+    }
+    default:
+      process.stderr.write('usage: critique-storage.mjs <slug|write|latest|trend> [args]\n');
+      process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2));
+}

.claude/skills/impeccable/scripts/impeccable-paths.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const IMPECCABLE_DIR = '.impeccable';
+export const LIVE_DIR = 'live';
+export const CRITIQUE_DIR = 'critique';
+
+export function getImpeccableDir(cwd = process.cwd()) {
+  return path.join(cwd, IMPECCABLE_DIR);
+}
+
+export function getDesignSidecarPath(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), 'design.json');
+}
+
+export function getDesignSidecarCandidates(cwd = process.cwd(), contextDir = cwd) {
+  const candidates = [
+    getDesignSidecarPath(cwd),
+    path.join(cwd, 'DESIGN.json'),
+  ];
+  const contextLegacy = path.join(contextDir, 'DESIGN.json');
+  if (!candidates.includes(contextLegacy)) candidates.push(contextLegacy);
+  return candidates;
+}
+
+export function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd) {
+  return firstExisting(getDesignSidecarCandidates(cwd, contextDir));
+}
+
+export function getLiveDir(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), LIVE_DIR);
+}
+
+export function getLiveConfigPath(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'config.json');
+}
+
+export function getLegacyLiveConfigPath(scriptsDir) {
+  return path.join(scriptsDir, 'config.json');
+}
+
+export function resolveLiveConfigPath({ cwd = process.cwd(), scriptsDir, env = process.env } = {}) {
+  if (env.IMPECCABLE_LIVE_CONFIG && env.IMPECCABLE_LIVE_CONFIG.trim()) {
+    const configured = env.IMPECCABLE_LIVE_CONFIG.trim();
+    return path.isAbsolute(configured) ? configured : path.resolve(cwd, configured);
+  }
+  const primary = getLiveConfigPath(cwd);
+  if (fs.existsSync(primary)) return primary;
+  if (scriptsDir) {
+    const legacy = getLegacyLiveConfigPath(scriptsDir);
+    if (fs.existsSync(legacy)) return legacy;
+  }
+  return primary;
+}
+
+export function getLiveServerPath(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'server.json');
+}
+
+export function getLegacyLiveServerPath(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live.json');
+}
+
+export function readLiveServerInfo(cwd = process.cwd()) {
+  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
+    try {
+      return { info: JSON.parse(fs.readFileSync(filePath, 'utf-8')), path: filePath };
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+export function writeLiveServerInfo(cwd = process.cwd(), info) {
+  const filePath = getLiveServerPath(cwd);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(info));
+  return filePath;
+}
+
+export function removeLiveServerInfo(cwd = process.cwd()) {
+  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
+    try { fs.unlinkSync(filePath); } catch {}
+  }
+}
+
+export function getLiveSessionsDir(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'sessions');
+}
+
+export function getLegacyLiveSessionsDir(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live', 'sessions');
+}
+
+export function getLiveAnnotationsDir(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'annotations');
+}
+
+export function getCritiqueDir(cwd = process.cwd()) {
+  return path.join(getImpeccableDir(cwd), CRITIQUE_DIR);
+}
+
+export function getLegacyLiveAnnotationsDir(cwd = process.cwd()) {
+  return path.join(cwd, '.impeccable-live', 'annotations');
+}
+
+function firstExisting(paths) {
+  return paths.find((filePath) => fs.existsSync(filePath)) || null;
+}

.claude/skills/impeccable/scripts/live-accept.mjs

@@ -105,15 +105,22 @@ function handleDiscard(id, lines, targetFile) {
   if (!block) return { handled: false, error: 'Markers not found' };
 
   const original = extractOriginal(lines, block);
-  const indent = lines[block.start].match(/^(\s*)/)[1];
+  const isJsx = detectCommentSyntax(targetFile).open === '{/*';
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
 
-  // De-indent the original content back to the marker's indentation level
+  // Restore at the line we're actually replacing FROM, not the marker line.
+  // For JSX wrappers the marker comments live INSIDE the outer `<div>`, so
+  // `block.start` sits 2 spaces deeper than the original element. Using that
+  // as the deindent base would push the restored content 2 spaces too far
+  // right on every JSX/TSX session. `replaceRange.start` is the outer wrapper
+  // line, which is at the original element's indent for both HTML and JSX.
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
   const restored = deindentContent(original, indent);
 
   const newLines = [
-    ...lines.slice(0, block.start),
+    ...lines.slice(0, replaceRange.start),
     ...restored,
-    ...lines.slice(block.end + 1),
+    ...lines.slice(replaceRange.end + 1),
   ];
   fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
   return {};
@@ -127,8 +134,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const block = findMarkerBlock(id, lines);
   if (!block) return { handled: false, error: 'Markers not found' };
 
-  const indent = lines[block.start].match(/^(\s*)/)[1];
   const commentSyntax = detectCommentSyntax(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  // Anchor indent on the line we're replacing FROM (the outer wrapper),
+  // not on `block.start` — for JSX that's the marker comment 2 spaces
+  // deeper than the original element. See handleDiscard for the full
+  // rationale.
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
 
   // Extract the chosen variant's inner content
   const variantContent = extractVariant(lines, block, variantNum);
@@ -149,7 +162,6 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const replacement = [];
 
   if (cssContent) {
-    const isJsx = commentSyntax.open === '{/*';
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
     // JSX targets need the CSS body wrapped in a template literal so that the
     // `{` and `}` in CSS rules don't get parsed as JSX expressions.
@@ -177,7 +189,6 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // need the object form, otherwise React 19 throws "Failed to set indexed
   // property [0] on CSSStyleDeclaration" while parsing the string char-by-char.
   if (cssContent) {
-    const isJsx = commentSyntax.open === '{/*';
     const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
     replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
@@ -187,9 +198,9 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   }
 
   const newLines = [
-    ...lines.slice(0, block.start),
+    ...lines.slice(0, replaceRange.start),
     ...replacement,
-    ...lines.slice(block.end + 1),
+    ...lines.slice(replaceRange.end + 1),
   ];
   fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
 
@@ -218,6 +229,72 @@ function findMarkerBlock(id, lines) {
   return (start !== -1 && end !== -1) ? { start, end } : null;
 }
 
+/**
+ * Compute the line range to REPLACE (vs. just the marker range to extract
+ * from). For JSX/TSX wrappers, live-wrap places the marker comments INSIDE
+ * the `<div data-impeccable-variants="ID">` outer wrapper so the picked
+ * element's JSX slot keeps a single child — a Fragment `<></>` would have
+ * solved the multi-sibling case but failed inside `asChild` / cloneElement
+ * parents with "Invalid prop supplied to React.Fragment".
+ *
+ * That means the marker block is enclosed by the wrapper `<div>` opener
+ * (with `data-impeccable-variants="ID"`) and its matching `</div>`. We
+ * walk back to the opener and forward to the closer so accept/discard
+ * remove the entire scaffold, not just the inner markers.
+ *
+ * Marker lines themselves stay where they were so extractOriginal /
+ * extractVariant / extractCss continue to walk the same range.
+ */
+function expandReplaceRange(block, lines, isJsx) {
+  if (!isJsx) return { start: block.start, end: block.end };
+
+  let { start, end } = block;
+
+  // Walk back for the wrapper `<div data-impeccable-variants="..."` opener.
+  // The attr may sit on a continuation line of a multi-line opening tag, so
+  // also walk to the line that actually contains `<div`.
+  for (let i = start - 1; i >= Math.max(0, start - 12); i--) {
+    if (/data-impeccable-variants=/.test(lines[i])) {
+      let opener = i;
+      while (opener > 0 && !/<div\b/.test(lines[opener])) opener--;
+      start = opener;
+      break;
+    }
+  }
+
+  // Walk forward to the matching `</div>` by div-depth tracking from the
+  // wrapper opener. Operate on JOINED text instead of per-line: a
+  // multi-line self-closing JSX `<div\n  className="spacer"\n/>` would
+  // fool per-line regex tracking (the `<div` line matches openRe but the
+  // `/>` line never matches selfCloseRe since it needs `<div` on the same
+  // line). That left depth permanently over-counted and the wrapper's
+  // outer `</div>` orphaned after accept/discard. Single regex with
+  // `[^>]*?` (which spans newlines in JS) handles either form correctly.
+  const joined = lines.slice(start).join('\n');
+  // Match either `<div … />` (self-close, group 1 is `/`), `<div … >`
+  // (open, group 1 is empty), or `</div>`.
+  const tagRe = /<div\b[^>]*?(\/?)>|<\/div\s*>/g;
+  let depth = 0;
+  let m;
+  while ((m = tagRe.exec(joined)) !== null) {
+    const isClose = m[0].startsWith('</');
+    const isSelfClose = !isClose && m[1] === '/';
+    if (isClose) depth--;
+    else if (!isSelfClose) depth++;
+    if (depth <= 0) {
+      // m.index is offset within `joined`; convert back to a file line.
+      const linesBefore = joined.slice(0, m.index + m[0].length).split('\n').length - 1;
+      const candidateEnd = start + linesBefore;
+      if (candidateEnd >= end) {
+        end = candidateEnd;
+        break;
+      }
+    }
+  }
+
+  return { start, end };
+}
+
 /**
  * Join wrapper lines into a single string with `<style>` elements removed so
  * marker matching and div-depth tracking aren't confused by:
@@ -345,7 +422,7 @@ function extractCss(lines, block, id) {
       // Same-line open + close: extract inner text.
       const sameLine = line.match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/);
       if (sameLine) {
-        const inner = sameLine[1];
+        const inner = stripJsxTemplateWrap(sameLine[1]);
         return inner.length > 0 ? inner.split('\n') : null;
       }
       inStyle = true;
@@ -362,7 +439,60 @@ function extractCss(lines, block, id) {
     }
   }
 
-  return content.length > 0 ? content : null;
+  if (content.length === 0) return null;
+  return stripJsxTemplateLines(content);
+}
+
+/**
+ * Strip a JSX template-literal wrap (`{` … `}`) from CSS extracted out of a
+ * `<style>` element in a JSX/TSX file. The agent may write the wrap with
+ * `{` and `}` directly attached to the `<style>` tags, on their own lines,
+ * or attached to the first/last CSS lines — all three are JSX-legal.
+ *
+ * Stripping is required because handleAccept re-wraps the CSS itself when
+ * carbonizing. Without this, two consecutive accepts (or a previously-
+ * accepted variants block being carbonized) would produce nested
+ * `{` `{` … `}` `}`, which oxc rejects with "Expected `}` but found `@`".
+ */
+function stripJsxTemplateLines(content) {
+  const out = content.slice();
+
+  // Drop any leading blank lines so we don't miss a `{` line buried below
+  // them; same for trailing.
+  while (out.length > 0 && out[0].trim() === '') out.shift();
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+  if (out.length === 0) return null;
+
+  // Leading `{`: own line, or attached to the first CSS line.
+  const firstTrim = out[0].trimStart();
+  if (firstTrim === '{`') {
+    out.shift();
+  } else if (firstTrim.startsWith('{`')) {
+    const idx = out[0].indexOf('{`');
+    out[0] = out[0].slice(0, idx) + out[0].slice(idx + 2);
+    if (out[0].trim() === '') out.shift();
+  }
+  if (out.length === 0) return null;
+
+  // Trailing `` ` `` `}`: own line, or attached to the last CSS line.
+  const lastIdx = out.length - 1;
+  const lastTrim = out[lastIdx].trimEnd();
+  if (lastTrim === '`}') {
+    out.pop();
+  } else if (lastTrim.endsWith('`}')) {
+    const text = out[lastIdx];
+    const idx = text.lastIndexOf('`}');
+    out[lastIdx] = text.slice(0, idx) + text.slice(idx + 2);
+    if (out[lastIdx].trim() === '') out.pop();
+  }
+
+  return out.length > 0 ? out : null;
+}
+
+function stripJsxTemplateWrap(text) {
+  const lines = text.split('\n');
+  const stripped = stripJsxTemplateLines(lines);
+  return stripped ? stripped.join('\n') : '';
 }
 
 /**

.claude/skills/impeccable/scripts/live-browser-session.js

@@ -0,0 +1,123 @@
+/**
+ * Browser-side durable session helpers for Impeccable live mode.
+ *
+ * Kept separate from live-browser.js so recovery state can be tested without
+ * booting the full overlay UI. Served before live-browser.js and attached to
+ * window.__IMPECCABLE_LIVE_SESSION__.
+ */
+(function (root) {
+  'use strict';
+
+  function createLiveBrowserSessionState({ prefix, storage, idFactory }) {
+    if (!prefix) throw new Error('prefix required');
+    const store = storage || root.localStorage;
+    const makeId = idFactory || function () { return Math.random().toString(16).slice(2, 10); };
+    const sessionKey = prefix + '-session';
+    const handledKey = sessionKey + '-handled';
+    const scrollKey = sessionKey + '-scroll';
+    let checkpointRevision = 0;
+    const owner = makeId();
+
+    function safeRead(key) {
+      try { return store.getItem(key); } catch { return null; }
+    }
+
+    function safeWrite(key, value) {
+      try { store.setItem(key, value); } catch { /* quota exceeded or private mode */ }
+    }
+
+    function safeRemove(key) {
+      try { store.removeItem(key); } catch { /* unavailable storage */ }
+    }
+
+    function loadSession() {
+      try {
+        const raw = safeRead(sessionKey);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (Number.isInteger(parsed.checkpointRevision)) {
+          checkpointRevision = Math.max(checkpointRevision, parsed.checkpointRevision);
+        }
+        return parsed;
+      } catch { return null; }
+    }
+
+    function saveSession(session) {
+      if (!session || !session.id) return;
+      const payload = {
+        ...session,
+        checkpointRevision,
+      };
+      safeWrite(sessionKey, JSON.stringify(payload));
+    }
+
+    function clearSession() {
+      safeRemove(sessionKey);
+    }
+
+    function nextCheckpointRevision() {
+      checkpointRevision += 1;
+      const existing = loadSession();
+      if (existing?.id) saveSession(existing);
+      return checkpointRevision;
+    }
+
+    function seedCheckpointRevision(value) {
+      if (Number.isInteger(value)) checkpointRevision = Math.max(checkpointRevision, value);
+      return checkpointRevision;
+    }
+
+    function currentCheckpointRevision() {
+      return checkpointRevision;
+    }
+
+    function markHandled(id) {
+      if (!id) return;
+      safeWrite(handledKey, id);
+    }
+
+    function isHandled(id) {
+      return !!id && safeRead(handledKey) === id;
+    }
+
+    function clearHandled() {
+      safeRemove(handledKey);
+    }
+
+    function writeScrollY(y) {
+      safeWrite(scrollKey, String(y));
+    }
+
+    function readScrollY() {
+      const raw = safeRead(scrollKey);
+      if (raw == null) return null;
+      const n = parseFloat(raw);
+      return isFinite(n) ? n : null;
+    }
+
+    function clearScrollY() {
+      safeRemove(scrollKey);
+    }
+
+    return {
+      owner,
+      sessionKey,
+      handledKey,
+      scrollKey,
+      saveSession,
+      loadSession,
+      clearSession,
+      nextCheckpointRevision,
+      seedCheckpointRevision,
+      currentCheckpointRevision,
+      markHandled,
+      isHandled,
+      clearHandled,
+      writeScrollY,
+      readScrollY,
+      clearScrollY,
+    };
+  }
+
+  root.__IMPECCABLE_LIVE_SESSION__ = { createLiveBrowserSessionState };
+})(typeof window !== 'undefined' ? window : globalThis);

.claude/skills/impeccable/scripts/live-browser.js

@@ -50,6 +50,16 @@
   const Z = { highlight: 100001, bar: 100005, picker: 100007, toast: 100010 };
   const EASE = 'cubic-bezier(0.22, 1, 0.36, 1)'; // ease-out-quint
   const PREFIX = 'impeccable-live';
+  const sessionState = window.__IMPECCABLE_LIVE_SESSION__?.createLiveBrowserSessionState({
+    prefix: PREFIX,
+    storage: localStorage,
+    idFactory: () => crypto.randomUUID().replace(/-/g, '').slice(0, 8),
+  });
+  if (!sessionState) {
+    console.error('[impeccable] live-browser-session.js was not loaded. Live mode cannot start safely.');
+    window.__IMPECCABLE_LIVE_INIT__ = false;
+    return;
+  }
   const HIGHLIGHT_TRANSITION =
     'top 140ms ' + EASE +
     ', left 140ms ' + EASE +
@@ -112,6 +122,8 @@
   let hasProjectContext = false;
   let selectedAction = 'impeccable';
   let selectedCount = 3;
+  const browserOwner = sessionState.owner;
+  let checkpointTimer = null;
 
   // Scroll lock — holds window.scrollY at a fixed value while the session is
   // active, so HMR DOM patches and variant swaps can't drift the page. See
@@ -126,21 +138,9 @@
   // (Previously: saveSession wrote scrollY alongside state, so every call
   // during resume overwrote the pre-reload value with whatever the browser
   // had landed on, typically 0.)
-  const SCROLL_KEY_SUFFIX = '-scroll';
-  function writeScrollY(y) {
-    try { localStorage.setItem(LS_KEY + SCROLL_KEY_SUFFIX, String(y)); } catch {}
-  }
-  function readScrollY() {
-    try {
-      const raw = localStorage.getItem(LS_KEY + SCROLL_KEY_SUFFIX);
-      if (raw == null) return null;
-      const n = parseFloat(raw);
-      return isFinite(n) ? n : null;
-    } catch { return null; }
-  }
-  function clearScrollY() {
-    try { localStorage.removeItem(LS_KEY + SCROLL_KEY_SUFFIX); } catch {}
-  }
+  function writeScrollY(y) { sessionState.writeScrollY(y); }
+  function readScrollY() { return sessionState.readScrollY(); }
+  function clearScrollY() { sessionState.clearScrollY(); }
 
   // Pre-empt the browser: apply manual scroll restoration and jump to the
   // saved scrollY at script-parse time. Retries on fonts.ready and load
@@ -1585,6 +1585,7 @@
           paramsCurrentValues[p.id] = v;
           readout.textContent = formatRangeValue(input);
           applyParamValue(variantEl, p, v);
+          queueCheckpoint('param_changed');
         });
         row.appendChild(input);
       } else if (p.kind === 'toggle') {
@@ -1615,6 +1616,7 @@
           knob.style.left = next ? '18px' : '2px';
           readout.textContent = next ? 'On' : 'Off';
           applyParamValue(variantEl, p, next);
+          queueCheckpoint('param_changed');
         });
         row.appendChild(track);
       } else if (p.kind === 'steps') {
@@ -1651,6 +1653,7 @@
               btn.style.color = on ? 'oklch(98% 0 0)' : P.text;
             });
             applyParamValue(variantEl, p, o.value);
+            queueCheckpoint('param_changed');
           });
           segRow.appendChild(b);
           segBtns.push({ btn: b, val: o.value });
@@ -1872,19 +1875,26 @@
           return;
         }
 
+        const previousVisibleVariant = currentSessionId === sessionId ? visibleVariant : 0;
+
         // Replace the live element with the full wrapper from source
         const wrapper = srcWrapper.cloneNode(true);
         liveEl.parentElement.replaceChild(wrapper, liveEl);
 
-        // Update state: count variants, show the first one
+        // Update state: count variants, preserving the user's current variant
+        // when a late HMR/source reinjection lands after they have cycled.
         const variants = wrapper.querySelectorAll('[data-impeccable-variant]:not([data-impeccable-variant="original"])');
         arrivedVariants = variants.length;
         expectedVariants = parseInt(wrapper.dataset.impeccableVariantCount || arrivedVariants);
-        visibleVariant = 1;
-        showVariantInDOM(sessionId, 1);
+        const saved = loadSession();
+        const savedVisibleVariant = saved && saved.id === sessionId ? saved.visible : 0;
+        visibleVariant = previousVisibleVariant > 0 && previousVisibleVariant <= arrivedVariants
+          ? previousVisibleVariant
+          : (savedVisibleVariant > 0 && savedVisibleVariant <= arrivedVariants ? savedVisibleVariant : 1);
+        showVariantInDOM(sessionId, visibleVariant);
 
         // Update selectedElement to the visible variant's content
-        selectedElement = pickVariantContent(wrapper, 1) || wrapper.parentElement;
+        selectedElement = pickVariantContent(wrapper, visibleVariant) || wrapper.parentElement;
 
         state = 'CYCLING';
         hideShaderOverlay();
@@ -1907,6 +1917,7 @@
     updateSelectedElement();
     updateBarContent('cycling');
     saveSession();
+    queueCheckpoint('variant_changed');
   }
 
   function updateSelectedElement() {
@@ -1917,6 +1928,18 @@
     if (visEl) selectedElement = visEl;
   }
 
+  function readVisibleVariantFromDOM(sessionId) {
+    const wrapper = document.querySelector('[data-impeccable-variants="' + sessionId + '"]');
+    if (!wrapper) return 0;
+    const variants = wrapper.querySelectorAll('[data-impeccable-variant]:not([data-impeccable-variant="original"])');
+    for (const variant of variants) {
+      if (variant.style.display === 'none') continue;
+      const idx = parseInt(variant.dataset.impeccableVariant || '0', 10);
+      if (idx > 0) return idx;
+    }
+    return 0;
+  }
+
   // Resolve the element that represents the variant's visible content.
   // Contract: each variant div should contain exactly one top-level element
   // (the full replacement). In practice a model may ship loose siblings or
@@ -2107,8 +2130,10 @@
       updating = true;
       arrivedVariants = count;
       if (visibleVariant === 0 && arrivedVariants > 0) {
-        visibleVariant = 1;
-        showVariantInDOM(sessionId, 1);
+        const saved = loadSession();
+        const savedVisibleVariant = saved && saved.id === sessionId ? saved.visible : 0;
+        visibleVariant = savedVisibleVariant > 0 && savedVisibleVariant <= arrivedVariants ? savedVisibleVariant : 1;
+        showVariantInDOM(sessionId, visibleVariant);
         // showVariantInDOM hid the original (display:none); if we were still
         // anchored to the original's content, its boundingRect is now zero
         // and the bar snaps to (0,0). Re-point at the visible variant instead.
@@ -2128,6 +2153,7 @@
         updateBarContent('generating');
       }
       saveSession();
+      queueCheckpoint(state === 'CYCLING' ? 'variants_ready' : 'variants_progress');
       updating = false;
     });
 
@@ -2236,6 +2262,7 @@
 
   /** Server died or became unreachable. Reset UI to a clean state. */
   function handleServerLost() {
+    const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
       showToast('Live server disconnected. Session ended.', 5000);
     }
@@ -2246,21 +2273,61 @@
     stopScrollTracking();
     if (variantObserver) { variantObserver.disconnect(); variantObserver = null; }
     stopScrollLock();
-    clearScrollY();
-    clearSession();
+    // Preserve local session state on server loss. The durable journal is the
+    // source of truth, but localStorage plus the variant wrapper lets the UI
+    // resume after a helper restart or page reload instead of treating a
+    // transient disconnect as an explicit discard.
     selectedElement = null;
-    currentSessionId = null;
     selectedAction = 'impeccable';
-    state = 'IDLE';
+    state = recoveryState;
+    if (currentSessionId) saveSession();
   }
 
-  function sendEvent(msg) {
+  function sendEvent(msg, opts) {
     msg.token = TOKEN;
-    fetch('http://localhost:' + PORT + '/events', {
+    function handleFailure(err) {
+      console.error('[impeccable] Failed to send event:', err);
+      if (opts && opts.throwOnError) throw err;
+      return null;
+    }
+    return fetch('http://localhost:' + PORT + '/events', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(msg),
-    }).catch(err => console.error('[impeccable] Failed to send event:', err));
+    }).then(res => {
+      if (res.ok) return res;
+      return handleFailure(new Error('HTTP ' + res.status + ' ' + res.statusText));
+    }).catch(handleFailure);
+  }
+
+  function checkpointPayload(reason) {
+    return {
+      type: 'checkpoint',
+      id: currentSessionId,
+      revision: sessionState.nextCheckpointRevision(),
+      owner: browserOwner,
+      phase: String(state || '').toLowerCase(),
+      reason,
+      pageUrl: location.pathname,
+      expectedVariants,
+      arrivedVariants,
+      visibleVariant,
+      paramValues: { ...paramsCurrentValues },
+    };
+  }
+
+  function sendCheckpoint(reason) {
+    if (!currentSessionId) return Promise.resolve(null);
+    return sendEvent(checkpointPayload(reason)).catch(() => null);
+  }
+
+  function queueCheckpoint(reason) {
+    if (!currentSessionId) return;
+    if (checkpointTimer) clearTimeout(checkpointTimer);
+    checkpointTimer = setTimeout(() => {
+      checkpointTimer = null;
+      sendCheckpoint(reason);
+    }, 120);
   }
 
   // ---------------------------------------------------------------------------
@@ -2496,6 +2563,7 @@
     state = 'GENERATING';
     showBar('generating');
     saveSession();
+    sendCheckpoint('generate_started');
     writeScrollY(window.scrollY);
     if (variantObserver) variantObserver.disconnect();
     variantObserver = startVariantObserver(currentSessionId);
@@ -2622,11 +2690,15 @@
       if (!isTransparentColor(cs.backgroundColor)) return cs.backgroundColor;
       node = node.parentElement;
     }
-    return (
-      getComputedStyle(document.body).backgroundColor ||
-      getComputedStyle(document.documentElement).backgroundColor ||
-      '#ffffff'
-    );
+    // The walk already passed through <body> and <html>; if they had been
+    // opaque we would have returned. Falling through with the previous
+    // `getComputedStyle(body).backgroundColor || …` chain is a trap: that
+    // call returns the literal string `"rgba(0, 0, 0, 0)"` for a page that
+    // never set its own bg, which is truthy and short-circuits the chain to
+    // transparent-black — modern-screenshot then renders the capture on a
+    // black canvas and the shader overlay flashes solid black during load.
+    // The browser canvas defaults to white, so we do too.
+    return '#ffffff';
   }
 
   // Capture the element (with current annotations baked in) and return a PNG
@@ -2916,13 +2988,12 @@ void main() {
 
   function handleAccept() {
     if (!currentSessionId || arrivedVariants === 0) return;
+    const domVisibleVariant = readVisibleVariantFromDOM(currentSessionId);
+    if (domVisibleVariant > 0) visibleVariant = domVisibleVariant;
     const acceptPayload = { type: 'accept', id: currentSessionId, variantId: String(visibleVariant) };
     if (Object.keys(paramsCurrentValues).length > 0) {
       acceptPayload.paramValues = { ...paramsCurrentValues };
     }
-    sendEvent(acceptPayload);
-    markSessionHandled();
-
     // The accepted variant is already the only visible child of the wrapper
     // (all other variants are display:none). HMR from the source rewrite will
     // replace the wrapper imminently. Don't eagerly replaceChild here — React
@@ -2932,9 +3003,28 @@ void main() {
     const acceptedSessionId = currentSessionId;
     const acceptedVariant = visibleVariant;
 
-    state = 'CONFIRMED';
-    updateBarContent('confirmed');
-    setTimeout(function() {
+    state = 'SAVING';
+    updateBarContent('saving');
+
+    sendEvent(acceptPayload, { throwOnError: true })
+      .then(() => {
+        markSessionHandled();
+        confirmAcceptAfterReceipt();
+      })
+      .catch(() => {
+        state = 'CYCLING';
+        updateBarContent('cycling');
+        showToast('Could not confirm accept with the live server. Session kept for recovery; try Accept again.', 5000);
+      });
+
+    function confirmAcceptAfterReceipt() {
+      state = 'CONFIRMED';
+      updateBarContent('confirmed');
+      scheduleAcceptCleanup();
+    }
+
+    function scheduleAcceptCleanup() {
+      setTimeout(function() {
       hideBar();
       hideHighlight();
       stopScrollTracking();
@@ -2963,50 +3053,46 @@ void main() {
         accepted.style.display = 'contents';
         parent.replaceChild(accepted, wrapper);
       }
-    }, 2000);
+      }, 2000);
+    }
   }
 
   function handleDiscard() {
     if (!currentSessionId) return;
-    sendEvent({ type: 'discard', id: currentSessionId });
-    markSessionHandled();
-    // Instant DOM restore + fire-and-forget (script handles file cleanup)
-    cleanup();
+    sendEvent({ type: 'discard', id: currentSessionId }, { throwOnError: true })
+      .then(() => {
+        markSessionHandled();
+        cleanup();
+      })
+      .catch(() => showToast('Could not confirm discard with the live server. Session kept for recovery.', 5000));
   }
 
   // ---------------------------------------------------------------------------
-  // Session persistence via localStorage
+  // Session persistence via live-browser-session.js
   // ---------------------------------------------------------------------------
   // Survives page reloads, browser close/reopen, HMR, and accidental refreshes.
 
-  const LS_KEY = PREFIX + '-session';
-
   function saveSession() {
     if (!currentSessionId) return;
     // NOTE: scrollY is stored under a separate key (writeScrollY). Storing
     // it here would overwrite the Go-time value every time state changes.
-    try {
-      localStorage.setItem(LS_KEY, JSON.stringify({
-        id: currentSessionId,
-        state: state,
-        action: selectedAction,
-        count: selectedCount,
-        expected: expectedVariants,
-        arrived: arrivedVariants,
-        visible: visibleVariant,
-      }));
-    } catch { /* quota exceeded or private mode */ }
+    sessionState.saveSession({
+      id: currentSessionId,
+      state,
+      action: selectedAction,
+      count: selectedCount,
+      expected: expectedVariants,
+      arrived: arrivedVariants,
+      visible: visibleVariant,
+    });
   }
 
   function loadSession() {
-    try {
-      const raw = localStorage.getItem(LS_KEY);
-      return raw ? JSON.parse(raw) : null;
-    } catch { return null; }
+    return sessionState.loadSession();
   }
 
   function clearSession() {
-    try { localStorage.removeItem(LS_KEY); } catch {}
+    sessionState.clearSession();
   }
 
   /** Mark session as handled (accepted/discarded). The agent will clean up
@@ -3014,19 +3100,15 @@ void main() {
    *  prevents resumeSession from picking it up again after reload. */
   function markSessionHandled() {
     if (!currentSessionId) return;
-    try {
-      localStorage.setItem(LS_KEY + '-handled', currentSessionId);
-    } catch {}
+    sessionState.markHandled(currentSessionId);
   }
 
   function isSessionHandled(id) {
-    try {
-      return localStorage.getItem(LS_KEY + '-handled') === id;
-    } catch { return false; }
+    return sessionState.isHandled(id);
   }
 
   function clearHandled() {
-    try { localStorage.removeItem(LS_KEY + '-handled'); } catch {}
+    sessionState.clearHandled();
   }
 
   function cleanup() {
@@ -3157,6 +3239,7 @@ void main() {
     // hid. Now that state is CYCLING, re-fire.
     if (state === 'CYCLING') refreshParamsPanel();
     saveSession();
+    queueCheckpoint('browser_resumed');
 
     // Start observing for more variants AFTER initial setup
     if (variantObserver) variantObserver.disconnect();
@@ -3613,7 +3696,7 @@ void main() {
   }
 
   // ---------------------------------------------------------------------------
-  // Design System Panel — visualizes the project's DESIGN.json sidecar
+  // Design System Panel — visualizes the project's .impeccable/design.json sidecar
   // ---------------------------------------------------------------------------
 
   const DESIGN_PREFS_KEY = 'impeccable-live-design-panel';
@@ -3625,7 +3708,7 @@ void main() {
     open: false,
     tab: 'visual',          // 'visual' | 'raw'
     parsed: null,           // parseDesignMd output (frontmatter + body sections)
-    sidecar: null,          // DESIGN.json v2 payload (extensions + components + narrative)
+    sidecar: null,          // .impeccable/design.json v2 payload (extensions + components + narrative)
     hasMd: false,
     hasSidecar: false,
     present: null,          // true/false once fetch resolves
@@ -4126,7 +4209,7 @@ void main() {
     box.className = 'stale';
     box.innerHTML = `
       <span class="stale-dot"></span>
-      <span class="stale-text"><strong>DESIGN.md is newer than DESIGN.json.</strong> Run <code>/impeccable document</code> to refresh the sidecar.</span>
+      <span class="stale-text"><strong>DESIGN.md is newer than .impeccable/design.json.</strong> Run <code>/impeccable document</code> to refresh the sidecar.</span>
     `;
     return box;
   }
@@ -4134,7 +4217,7 @@ void main() {
   function renderParsedMdCta() {
     const box = document.createElement('div');
     box.className = 'parsed-md-cta';
-    box.innerHTML = `<strong>Basic view</strong>This panel reads the tokens in your <code>DESIGN.md</code> frontmatter. Running <code>/impeccable document</code> also generates a <code>DESIGN.json</code> sidecar with your project's actual component snippets (button, input, nav) and tonal ramps, rendered live below the tokens.`;
+    box.innerHTML = `<strong>Basic view</strong>This panel reads the tokens in your <code>DESIGN.md</code> frontmatter. Running <code>/impeccable document</code> also generates a <code>.impeccable/design.json</code> sidecar with your project's actual component snippets (button, input, nav) and tonal ramps, rendered live below the tokens.`;
     return box;
   }
 
@@ -4594,7 +4677,7 @@ void main() {
 
   function cssSafe(v) {
     // Strip anything outside valid CSS value chars to prevent injection via
-    // DESIGN.json values rendered into inline style strings.
+    // .impeccable/design.json values rendered into inline style strings.
     return String(v).replace(/[<>"'`\n]/g, '');
   }
 

.claude/skills/impeccable/scripts/live-complete.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Canonical durable completion acknowledgement for Impeccable live sessions.
+ */
+
+import { createLiveSessionStore } from './live-session-store.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
+
+function parseArgs(argv) {
+  const out = { status: 'complete' };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--id') out.id = argv[++i];
+    else if (arg.startsWith('--id=')) out.id = arg.slice('--id='.length);
+    else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
+    else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
+    else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
+    else if (arg === '--help' || arg === '-h') out.help = true;
+  }
+  return out;
+}
+
+export async function completeCli() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.id) {
+    console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
+    process.exit(args.help ? 0 : 1);
+  }
+
+  const serverInfo = readServerInfo();
+  const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
+  if (serverResult?.ok) {
+    const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
+    const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
+    console.log(JSON.stringify({ ok: true, id: args.id, phase: snapshot?.phase || args.status, snapshot }, null, 2));
+    return;
+  }
+
+  const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
+  const event = args.status === 'discarded'
+    ? { type: 'discarded', id: args.id }
+    : args.status === 'agent_error'
+      ? { type: 'agent_error', id: args.id, message: args.message || 'unknown error' }
+      : { type: 'complete', id: args.id };
+  const snapshot = store.appendEvent(event);
+  console.log(JSON.stringify({ ok: true, id: args.id, phase: snapshot.phase, snapshot }, null, 2));
+}
+
+function readServerInfo() {
+  return readLiveServerInfo(process.cwd())?.info || null;
+}
+
+async function completeThroughServer(info, args) {
+  const type = args.status === 'discarded'
+    ? 'discarded'
+    : args.status === 'agent_error'
+      ? 'error'
+      : 'complete';
+  try {
+    const res = await fetch(`http://localhost:${info.port}/poll`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token: info.token, id: args.id, type, message: args.message }),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
+  completeCli();
+}

.claude/skills/impeccable/scripts/live-completion.mjs

@@ -0,0 +1,18 @@
+export function completionTypeForAcceptResult(eventType, acceptResult) {
+  if (eventType === 'discard') return acceptResult?.handled === true ? 'discarded' : 'error';
+  if (acceptResult?.handled === true && acceptResult?.carbonize === true) return 'agent_done';
+  if (acceptResult?.handled === true) return 'complete';
+  if (acceptResult?.mode === 'error') return 'error';
+  return 'agent_done';
+}
+
+export function completionAckForAcceptResult(eventId, completionType, acceptResult) {
+  const ack = { ok: true, type: completionType };
+  if (acceptResult?.handled === true && acceptResult?.carbonize === true) {
+    ack.final = false;
+    ack.requiresComplete = true;
+    ack.nextCommand = `live-complete.mjs --id ${eventId}`;
+    ack.message = 'Carbonize cleanup must be verified, then the session must be completed explicitly before polling again.';
+  }
+  return ack;
+}

.claude/skills/impeccable/scripts/live-inject.mjs

@@ -2,23 +2,24 @@
  * CLI helper: insert/remove the live variant mode script tag in the project's
  * main HTML entry point.
  *
- * On first live run, the agent generates `config.json` in this script's
- * directory with the project's insertion target (framework-specific). On
+ * On first live run, the agent generates `.impeccable/live/config.json`
+ * with the project's insertion target (framework-specific). On
  * every subsequent run, this script handles insert/remove deterministically
  * with zero LLM involvement.
  *
  * Usage:
  *   node live-inject.mjs --port PORT   # Insert the live script tag
  *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether config.json exists
+ *   node live-inject.mjs --check       # Check whether live config exists
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveLiveConfigPath } from './impeccable-paths.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_PATH = process.env.IMPECCABLE_LIVE_CONFIG || path.join(__dirname, 'config.json');
+const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
 const MARKER_OPEN_TEXT = 'impeccable-live-start';
 const MARKER_CLOSE_TEXT = 'impeccable-live-end';
 
@@ -39,12 +40,12 @@ export async function injectCli() {
     console.log(`Usage: node live-inject.mjs [options]
 
 Insert or remove the live mode script tag in the project's HTML entry point.
-Reads configuration from config.json (in this same directory).
+Reads configuration from .impeccable/live/config.json.
 
 Modes:
   --port PORT   Insert script tag pointing at http://localhost:PORT/live.js
   --remove      Remove the script tag (if present)
-  --check       Print whether config.json exists and its content
+  --check       Print whether .impeccable/live/config.json exists and its content
 
 Output (JSON):
   { ok, file, inserted|removed, config? }`);
@@ -388,7 +389,16 @@ export function patchCspMeta(content, port) {
 
     const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
     const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
-    const newAttrs = attrs.replace(contentAttr.full, newContentAttr) + ' ' + marker;
+    // The tagRe captures any whitespace between the last attribute and the
+    // closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
+    // a replace would land it BEFORE that trailing space, leaving a double
+    // space inside attrs and clobbering the space before `/>`. Split off
+    // the trailing whitespace, splice the marker into the attribute body,
+    // and re-append the original trailing whitespace so a self-closing
+    // `<meta … />` round-trips byte-for-byte.
+    const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
+    const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
+    const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
     const newTag = tag.full.replace(attrs, newAttrs);
 
     result = result.slice(0, tag.start) + newTag + result.slice(tag.end);