fix(extension): popup scan stuck on Scanning after page reload (v1.0.2)

The service worker's webNavigation.onCompleted handler only cleared
csInjected when DevTools was open. The popup-only flow never
registered the tab in devtoolsTabs, so a page reload left a stale
csInjected: true even though the content script had been destroyed.
The next popup scan saw the stale flag, skipped re-injection, and
silently sent its scan request to a tab with no listener — popup
UI got stuck on "Scanning..." indefinitely.

Reset is now unconditional (page reload always destroys the content
script regardless of which UI is open). Auto-rescan stays gated to
DevTools, since the popup is strictly user-driven.

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

.agents/skills/impeccable/SKILL.md

@@ -7,11 +7,30 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 ## Setup (non-optional)
 
-Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| 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. |
+
+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.
 
 ### 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.
@@ -22,13 +41,13 @@ 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.
 
-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 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.
 
 If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed.
 
@@ -101,7 +120,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
 
@@ -141,6 +163,8 @@ Plus two management commands — `pin <command>` and `unpin <command>`, detailed
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
 
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
 ## Pin / Unpin
 
 **Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

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

@@ -29,7 +29,7 @@ Analyze where motion would improve the experience:
    - Who's the audience? (Motion-sensitive users? Power users who want speed?)
    - What matters most? (One hero animation vs many micro-interactions?)
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
 
@@ -122,7 +122,8 @@ Use appropriate techniques for each animation:
 /* Prefer for simple, declarative animations */
 - transitions for state changes
 - @keyframes for complex sequences
-- transform + opacity only (GPU-accelerated)
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
 ```
 
 ### JavaScript Animation
@@ -134,9 +135,10 @@ Use appropriate techniques for each animation:
 ```
 
 ### Performance
-- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - **will-change**: Add sparingly for known expensive animations
-- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
 ### Accessibility
@@ -152,7 +154,7 @@ Use appropriate techniques for each animation:
 
 **NEVER**:
 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
-- Animate layout properties (width, height, top, left)—use transform instead
+- 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

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

@@ -22,7 +22,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 **Check for**:
 - **Layout thrashing**: Reading/writing layout properties in loops
-- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
 - **Bundle size**: Unnecessary imports, unused dependencies
 - **Render performance**: Unnecessary re-renders, missing memoization

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

@@ -28,7 +28,7 @@ Analyze what makes the design feel too safe or boring:
    - Who's the audience? (What will resonate?)
    - What are the constraints? (Brand guidelines, accessibility, performance)
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
 

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

@@ -29,6 +29,16 @@ 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:

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

@@ -30,7 +30,7 @@ Analyze the current state and identify opportunities:
    - **Wayfinding**: Helping users navigate and understand structure
    - **Delight**: Moments of visual interest and personality
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
 

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

@@ -1,12 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful.
+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 Gate
+
+Craft cannot build until all of these are true:
+
+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.
+
+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.
+
+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.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+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.
+
+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."
 
 ## Step 1: Shape the Design
 
 Run $impeccable shape, passing along whatever feature description the user provided.
 
-Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+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.
+
+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 has already run $impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
 
@@ -24,15 +53,17 @@ 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: North Star Mock (Capability-Gated)
+## Step 3: Land the Visual Direction (Capability-Gated)
 
-Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+Before implementation, generate high-fidelity visual comps when all of these are true:
 
 - 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.
 
-When those conditions are met, this step is the default for **both brand and product work**.
+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.
+
+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
 
@@ -40,25 +71,43 @@ Use the mock step to find a stronger visual lane than code-first generation woul
 
 ### What to generate
 
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+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.
 
-### After generation
+### Approval loop
 
-Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+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
 
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
 
-## Step 4: Asset Extraction (Optional)
+### 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.
 
@@ -74,53 +123,71 @@ Good candidates:
 - 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.
+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
+## Step 5: Build to Production Quality
 
-Implement the feature following the design brief. Work in this order:
+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.
 
-1. **Structure first**: HTML/semantic structure for the primary state. No styling yet.
-2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy.
-3. **Typography and color**: Apply the type scale and color system.
-4. **Interactive states**: Hover, focus, active, disabled.
-5. **Edge case states**: Empty, loading, error, overflow, first-run.
-6. **Motion**: Purposeful transitions and animations (if appropriate).
-7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context.
+### Production bar
 
-### During Build
-- Test with real (or realistic) data at every step, not placeholder text
-- Check each state as you build it, not all at the end
-- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief or the chosen north-star direction
-- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
-- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
+- 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.
 
-## Step 6: Visual Iteration
+## Step 6: Browser-Based Iteration
 
 **This step is critical.** Do not stop after the first implementation pass.
 
-Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback.
+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.
 
-Iterate through these checks visually:
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+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.
+
+### 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 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.
-3. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink?
-6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing.
+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.
 
-After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
+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
 
 Present the result to the user:
 - Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
 - Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
+- 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

@@ -166,7 +166,7 @@ Provocative questions that might unlock better solutions:
 
 ### Ask the User
 
-**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan.
+**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.
 
 Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions):
 

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

@@ -37,7 +37,7 @@ Identify where delight would enhance (not distract from) the experience:
    - **Helpful surprises**: Anticipating needs before users ask (productivity tools)
    - **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far.
 

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

@@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered:
    - What can be removed, hidden, or combined?
    - What's the 20% that delivers 80% of value?
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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.
 

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

@@ -66,7 +66,7 @@ Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] P
 - An existing `DESIGN.md` is stale (the design has drifted).
 - Before a large redesign, to capture the current state as a reference.
 
-If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
+If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. whether to refresh, overwrite, or merge.
 
 ## Two paths
 

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

@@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons
 
 Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions.
 
-**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first.
+**CRITICAL**: If no design system exists, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. before creating one. Understand the preferred location and structure first.
 
 ## Step 2: Identify Patterns
 

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

@@ -29,7 +29,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).
 
@@ -74,7 +74,7 @@ Reading annotations precisely:
 ### 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`:
@@ -82,9 +82,12 @@ 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.
 
+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.
+
 Output on success: `{ file, insertLine, commentSyntax }`.
 
 **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:
@@ -101,38 +104,81 @@ 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. **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?)
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+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, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+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 primary axes, not three riffs on color.
+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.
 
-**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.
+**Departure mode.** Each variant anchors to a different **aesthetic lane**, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+- Tech-minimal (Stripe / Linear / Vercel-restraint)
+- Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)
+- Terminal-native (actual code surface, syntax-highlighted UI as the design)
+- Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)
+- Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)
+- Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)
+- Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)
 
-> 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.
+Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. *Editorial-typographic is currently a reflex-reject lane* — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.
 
-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.
+#### 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: *editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal*. If any two variants share a family label, rework. *This pass is non-negotiable in departure mode and catches the editorial-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:
 
@@ -150,7 +196,13 @@ If two of them rhyme ("both use big type" / "both are stacks of sections" / "bot
 
 ### 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
 
@@ -181,6 +233,25 @@ The first variant has no `display: none` (visible by default). All others do. If
 
 One edit, all variants — the browser's MutationObserver picks everything up in one pass.
 
+**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 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)
 
 Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
@@ -246,6 +317,16 @@ node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --fil
 
 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.

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

@@ -38,9 +38,19 @@ Timing matters more than easing. These durations feel right for most UI:
 
 **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.
 
-## The Only Two Properties You Should Animate
+## Premium Motion Materials
 
-**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties: blur reveals, backdrop-filter panels, saturation or brightness shifts, shadow bloom, SVG filters, masks, clip paths, gradient-position movement, and variable font or shader-driven effects.
+
+Use the right material for the effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography.
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances, atmospheric transitions.
+- **Clip path / masks**: wipes, reveals, editorial cropping, product-like transitions.
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state.
+- **Grid-template rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly.
+
+The hard rule is not "transform and opacity only." The hard rule is: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify in-browser that the result is smooth on the target viewports. If blur/filter makes the interaction feel significantly more premium and remains smooth, use it.
 
 ## Staggered Animations
 

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

@@ -109,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 

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

@@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects
 This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
 
 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
-2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
+2. **STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
 3. Only proceed with the direction the user confirms.
 
 Skipping this step risks building something embarrassing that needs to be thrown away.

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

@@ -4,17 +4,17 @@ Perform a meticulous final pass to catch all the small details that separate goo
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+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: color tokens, spacing scale, typography styles, component API.
-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?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+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.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+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
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -22,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+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
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - 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.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -50,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+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.
+- **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.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -89,7 +104,7 @@ Every interactive element needs all states:
 
 - **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.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **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`
 
@@ -158,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -183,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- 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)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 

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

@@ -28,7 +28,7 @@ Analyze what makes the design feel too intense:
    - What's working? (Don't throw away good ideas)
    - What's the core message? (Preserve what matters)
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+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.
 

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

@@ -12,7 +12,18 @@ Most AI-generated UIs fail not because of bad code, but because of skipped think
 
 **Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
 
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
+
+### 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.
+
+- 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.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -63,7 +74,11 @@ After the discovery interview, generate a small set of visual direction probes *
 - 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.
 
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
+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.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
 
 ### What to generate
 
@@ -89,11 +104,11 @@ 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 and proceed directly to the design brief.
+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.
 
 ## Phase 2: Design Brief
 
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
+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.
 
 ### Brief Structure
 
@@ -131,6 +146,6 @@ Anything unresolved that the implementer should resolve during build.
 
 ---
 
-ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
+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.
 
 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/teach.md

@@ -21,11 +21,13 @@ 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 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**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **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.
 
 Never silently overwrite an existing file. Always confirm first.
 
+If teach was invoked as a setup blocker by another command, such as `$impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
 ## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
@@ -48,7 +50,22 @@ Note what you've learned and what remains unclear. This exploration feeds both P
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer 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. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- 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.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+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)
 
@@ -56,7 +73,7 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 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), ask the user directly to clarify what you cannot infer. which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+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.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
@@ -79,6 +96,8 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
 Synthesize into a strategic document:
 
 ```markdown
@@ -134,4 +153,4 @@ Summarize:
 
 If teach was invoked as a blocker by another impeccable command (e.g. the user ran `$impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
 
-Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.
+Optionally 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 whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.agents/skills/impeccable/scripts/command-metadata.json

@@ -1,10 +1,10 @@
 {
   "craft": {
-    "description": "Full shape-then-build flow with visual iteration. Plans the UX with /impeccable shape, loads the right reference files, then builds and iterates visually until the result is delightful. Use when building a new feature end-to-end.",
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
     "argumentHint": ""
   },
   "document": {
@@ -84,7 +84,7 @@
     "argumentHint": "[target]"
   },
   "shape": {
-    "description": "Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written.",
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
     "argumentHint": "[feature to shape]"
   },
   "typeset": {

.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);
@@ -150,12 +163,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
 
   if (cssContent) {
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
-    replacement.push(indent + '<style data-impeccable-css="' + id + '">');
+    // 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.
+    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
     // Re-indent CSS content to match
     for (const cssLine of cssContent) {
       replacement.push(indent + cssLine.trimStart());
     }
-    replacement.push(indent + '</style>');
+    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
     if (paramValues && Object.keys(paramValues).length > 0) {
       // Preserve the user's knob positions for the carbonize-cleanup agent
       // to bake into the final CSS when it collapses scoped rules.
@@ -169,8 +184,13 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // in a data-impeccable-variant="N" div with `display: contents` (so layout
   // isn't affected). The carbonize agent strips this attribute + wrapper when
   // it moves the CSS to a proper stylesheet.
+  //
+  // Style attribute syntax has to follow the host file's flavor — JSX files
+  // 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) {
-    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" style="display: contents">');
+    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
     replacement.push(indent + '</div>');
   } else {
@@ -178,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');
 
@@ -209,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:
@@ -336,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;
@@ -344,12 +430,69 @@ function extractCss(lines, block, id) {
     }
 
     if (inStyle) {
-      if (line.trimStart().startsWith('</style>')) break;
+      // Detect </style> anywhere on the line — JSX template-literal closes
+      // (`}</style>`) put the close mid-line, and we don't want to absorb the
+      // template-literal punctuation as CSS content.
+      const closeIdx = line.indexOf('</style>');
+      if (closeIdx !== -1) break;
       content.push(line);
     }
   }
 
-  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.js

@@ -197,6 +197,45 @@
 
   function id8() { return crypto.randomUUID().replace(/-/g, '').slice(0, 8); }
 
+  // Modal-aware chrome: keep our floating UI clickable inside Radix /
+  // Headless UI / vaul portals.
+  //
+  // Two host-page behaviors break us when the picked element lives inside a
+  // modal dialog:
+  //
+  //   1. Modal scroll-lock disables outside pointer events. Radix's
+  //      `DismissableLayer` sets `document.body.style.pointerEvents = 'none'`
+  //      while a modal is open and only restores `auto` on the layer. Our
+  //      chrome inherits `none` from <body> and becomes unclickable.
+  //   2. The dialog's outside-interaction handler (Radix's
+  //      `usePointerDownOutside`) listens at document level and dismisses
+  //      the dialog whenever a `pointerdown` lands outside the layer node.
+  //      Our chrome is a sibling of <body>, so Radix classifies our clicks
+  //      as outside and tears the dialog down mid-task.
+  //
+  // We can't reliably re-parent our chrome into the dialog subtree (z-index
+  // stacking, scroll containers, theming all become host-page concerns), so
+  // we defang both behaviors at our root:
+  //
+  //   - `pointer-events: auto !important` overrides the inherited `none`.
+  //   - Stop `pointerdown` / `mousedown` propagation so the document-level
+  //     dismiss listener never fires for our clicks.
+  //   - Stop `focusin` propagation so any focus shifts inside our chrome
+  //     don't read as "focus moved outside the dialog" to focus traps.
+  //
+  // Click events still bubble normally — only the early pointer/focus
+  // signals that drive outside-interaction detection are silenced.
+  function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+    if (!rootEl) return;
+    if (setPointerEvents) {
+      rootEl.style.setProperty('pointer-events', 'auto', 'important');
+    }
+    const stop = (e) => e.stopPropagation();
+    rootEl.addEventListener('pointerdown', stop);
+    rootEl.addEventListener('mousedown', stop);
+    rootEl.addEventListener('focusin', stop);
+  }
+
   // ---------------------------------------------------------------------------
   // Highlight overlay
   // ---------------------------------------------------------------------------
@@ -336,6 +375,11 @@
     annotOverlayEl.addEventListener('pointerup', onAnnotUp);
     annotOverlayEl.addEventListener('pointercancel', onAnnotUp);
     document.body.appendChild(annotOverlayEl);
+    // Modal-host friendliness: pointer-events is already 'auto' on this
+    // overlay; we only need to silence the host's outside-interaction
+    // listeners. Don't override pointer-events here (the overlay toggles
+    // visibility via display:none, which is fine).
+    defangOutsideHandlers(annotOverlayEl, { setPointerEvents: false });
   }
 
   function updateClearChip() {
@@ -811,6 +855,7 @@
       maxWidth: '520px', minWidth: '320px',
     });
     document.body.appendChild(barEl);
+    defangOutsideHandlers(barEl);
   }
 
   function positionBar() {
@@ -905,7 +950,12 @@
     pill.addEventListener('click', (e) => { e.stopPropagation(); toggleActionPicker(); });
     row.appendChild(pill);
 
-    // Freeform input
+    // Freeform input. Focus state shows an accent-colored border only —
+    // an earlier version tinted the background with `BP.accentSoft`, which
+    // composited against the dark bar surface to a murky purple where the
+    // browser's default placeholder gray was unreadable. Placeholder color
+    // is set explicitly via a one-shot stylesheet keyed off this input's id
+    // so it picks up the bar's `textDim` token in both themes.
     const input = document.createElement('input');
     input.id = PREFIX + '-input';
     input.type = 'text';
@@ -916,15 +966,20 @@
       border: '1px solid transparent', background: 'transparent',
       fontFamily: FONT, fontSize: '12px', color: BP.text,
       outline: 'none',
-      transition: 'border-color 0.15s ease, background 0.15s ease',
+      transition: 'border-color 0.15s ease',
     });
+    if (!document.getElementById(PREFIX + '-input-style')) {
+      const s = document.createElement('style');
+      s.id = PREFIX + '-input-style';
+      s.textContent =
+        '#' + PREFIX + '-input::placeholder { color: ' + BP.textDim + '; opacity: 1; }';
+      document.head.appendChild(s);
+    }
     input.addEventListener('focus', () => {
-      input.style.borderColor = BP.hairline;
-      input.style.background = BP.accentSoft;
+      input.style.borderColor = BP.accent;
     });
     input.addEventListener('blur', () => {
       input.style.borderColor = 'transparent';
-      input.style.background = 'transparent';
     });
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') { e.stopPropagation(); e.preventDefault(); handleGo(); return; }
@@ -1320,6 +1375,7 @@
 
     pickerEl.appendChild(grid);
     document.body.appendChild(pickerEl);
+    defangOutsideHandlers(pickerEl);
 
     // Cache the palette on the picker so toggleActionPicker's state refresh
     // uses the same theme-aware colors when it repaints chips.
@@ -1433,6 +1489,10 @@
 
     paramsPanelEl.appendChild(paramsPanelBody);
     document.body.appendChild(paramsPanelEl);
+    // Don't override pointer-events: the panel toggles between 'none' (closed,
+    // click-through) and 'auto' (open) on its own. Just silence the host's
+    // outside-interaction listeners while the panel is open.
+    defangOutsideHandlers(paramsPanelEl, { setPointerEvents: false });
     paramsPanelInner = paramsPanelEl; // compatibility alias for the rest of the code
   }
 
@@ -2011,7 +2071,16 @@
       for (const m of mutations) {
         if (m.target.closest?.('[data-impeccable-variants]')) { dominated = true; break; }
         for (const n of m.addedNodes) {
-          if (n.nodeType === 1 && (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant)) {
+          if (n.nodeType !== 1) continue;
+          // Direct hit: the added node itself is the wrapper or a variant.
+          if (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant) {
+            dominated = true; break;
+          }
+          // Subtree hit: framework HMR (notably SvelteKit) sometimes replaces
+          // a whole subtree where the wrapper is a descendant of the added
+          // node. Without this check, the observer ignores those mutations
+          // and the session stays in GENERATING forever.
+          if (n.querySelector?.('[data-impeccable-variants],[data-impeccable-variant]')) {
             dominated = true; break;
           }
         }
@@ -2126,17 +2195,20 @@
             }
             break;
           }
-          // HMR didn't propagate in time. Give it a 2s grace window, then
-          // reload the page. resumeSession counts variants off the rendered
-          // DOM on load and transitions straight to CYCLING — reload is the
-          // one universal recovery path: HTML, JSX/TSX, Vue, Svelte, static
-          // servers, anything. We used to try DOMParser on the raw source,
-          // but JSX expressions aren't valid HTML and the parse fails.
+          // Variants are in source but not in the DOM yet. Common when the
+          // picked element lived inside conditional render (closed modal,
+          // hidden tab, a route the user navigated away from). The variant
+          // MutationObserver stays armed and auto-transitions to CYCLING
+          // the moment the wrapper actually mounts. Nudge the user toward
+          // that path with a toast — better than the prior force-reload
+          // which reset framework state and left the session stuck.
           setTimeout(() => {
             if (arrivedVariants >= expectedVariants && expectedVariants > 0) return;
             if (state !== 'GENERATING') return;
-            saveSession();
-            window.location.reload();
+            showToast(
+              "Variants ready. If the picked element isn't visible, retrace the path that revealed it — they'll appear automatically.",
+              15000,
+            );
           }, 2000);
           break;
         case 'error':
@@ -2236,6 +2308,60 @@
     showBar('configure');
     startScrollTracking();
     maybePrefetchPage();
+    maybeWarnConditionalAncestor(selectedElement);
+  }
+
+  /**
+   * Surface a brief, non-blocking heads-up when the picked element lives
+   * inside a container whose visibility is gated by ephemeral state — modals,
+   * collapsible panels, popovers, off-screen tab panels. If HMR remounts the
+   * parent during generation (Vite Fast Refresh, SvelteKit page reload), the
+   * variants land in source but stay invisible until the user re-opens the
+   * container. Telling the user upfront is much friendlier than the silent
+   * timeout-then-toast that they'd otherwise hit.
+   *
+   * Heuristic, intentionally narrow — only fires for unambiguous cases so
+   * we don't cry wolf on every nested element.
+   */
+  function maybeWarnConditionalAncestor(el) {
+    let node = el?.parentElement;
+    let depth = 0;
+    while (node && depth < 12) {
+      // 1. Active dialog / modal
+      if (node.getAttribute && node.getAttribute('role') === 'dialog'
+          && node.getAttribute('aria-modal') === 'true') {
+        showToast('Heads up: this element lives inside a dialog. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 2. Common Radix / shadcn / headless-ui open-state attribute
+      if (node.dataset && node.dataset.state === 'open') {
+        showToast('Heads up: this element lives inside an open panel. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 3. Tab panel — only meaningful when the page also shows ANOTHER
+      // tab as selected. A single tabpanel with no tablist is just a static
+      // section in disguise and isn't conditional.
+      if (node.getAttribute && node.getAttribute('role') === 'tabpanel') {
+        const list = document.querySelector('[role="tablist"]');
+        if (list) {
+          const tabs = list.querySelectorAll('[role="tab"]');
+          if (tabs.length > 1) {
+            showToast('Heads up: this element lives in a tab panel. If state resets during generation, switch back to this tab.', 6000);
+            return;
+          }
+        }
+      }
+      // 4. Collapsible: aria-expanded sibling. Look for the trigger button.
+      if (node.id) {
+        const trigger = document.querySelector(`[aria-controls="${CSS.escape(node.id)}"][aria-expanded="true"]`);
+        if (trigger) {
+          showToast('Heads up: this element lives inside an expandable section. If state resets during generation, re-expand it.', 6000);
+          return;
+        }
+      }
+      node = node.parentElement;
+      depth++;
+    }
   }
 
   // Fire a lightweight prefetch event the first time the user selects an
@@ -2496,11 +2622,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
@@ -2694,7 +2824,13 @@ void main() {
       const img = document.createElement('img');
       img.src = URL.createObjectURL(blob);
       img.id = PREFIX + '-shader';
-      Object.assign(img.style, canvas.style, { outline: '2px dashed ' + C.brand, outlineOffset: '-2px' });
+      // Copy positioning via cssText. Object.assign across CSSStyleDeclaration
+      // throws in modern Chromium because the source's indexed properties
+      // (style[0], [1], ...) are read-only and the engine forbids writing
+      // them on the destination.
+      img.style.cssText = canvas.style.cssText;
+      img.style.outline = '2px dashed ' + C.brand;
+      img.style.outlineOffset = '-2px';
       document.body.appendChild(img);
       shaderState = { canvas: img, gl: null, program: null, texture: null, rafId: 0, startTime: 0 };
       return;
@@ -2942,8 +3078,16 @@ void main() {
 
   function showToast(message, duration) {
     if (toastEl) toastEl.remove();
+    // Stack the toast above the global bar (which sits at bottom:14px) so
+    // the two never overlap. Read the bar's actual rect — its height varies
+    // with hover-expanded labels — and fall back to a sensible default
+    // when the bar isn't mounted yet.
+    const barRect = globalBarEl?.getBoundingClientRect();
+    const barTopFromBottom = barRect && barRect.height > 0
+      ? Math.max(16, window.innerHeight - barRect.top + 12)
+      : 16;
     toastEl = el('div', {
-      position: 'fixed', bottom: '16px', left: '50%',
+      position: 'fixed', bottom: barTopFromBottom + 'px', left: '50%',
       transform: 'translateX(-50%) translateY(8px)',
       background: C.ink, color: C.white,
       fontFamily: FONT, fontSize: '12px',
@@ -3066,13 +3210,33 @@ void main() {
       // page bg. Used for screenshots and theme QA.
       const override = localStorage.getItem('impeccable-dev-theme');
       if (override === 'light' || override === 'dark') return override;
-      const bg = getComputedStyle(document.body).backgroundColor
-        || getComputedStyle(document.documentElement).backgroundColor;
-      const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-      if (!m) return 'light';
-      const [, r, g, b] = m;
+
+      // Walk body → html, taking the first opaque background. The browser's
+      // default body / html background is `rgba(0, 0, 0, 0)`, which a naive
+      // regex would read as black and mislabel a perfectly white page as
+      // dark. Honoring alpha avoids that — and falling through to <html>
+      // catches the common pattern of a bg only on <html> (or only on body).
+      function readOpaque(el) {
+        if (!el) return null;
+        const bg = getComputedStyle(el).backgroundColor;
+        const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/);
+        if (!m) return null;
+        const alpha = m[4] == null ? 1 : parseFloat(m[4]);
+        if (alpha < 0.5) return null; // transparent / nearly transparent → skip
+        return [+m[1], +m[2], +m[3]];
+      }
+
+      const rgb = readOpaque(document.body) || readOpaque(document.documentElement);
+      // Both transparent → fall back to the browser's effective canvas color.
+      // White is the universal default; only one in a thousand sites swaps it
+      // via `color-scheme: dark` on <html>, and `prefers-color-scheme` lets
+      // us catch that case.
+      if (!rgb) {
+        return matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      const [r, g, b] = rgb;
       // Perceptual luminance (Rec. 709)
-      const L = (0.2126 * +r + 0.7152 * +g + 0.0722 * +b) / 255;
+      const L = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
       return L > 0.55 ? 'light' : 'dark';
     } catch { return 'light'; }
   }
@@ -3275,15 +3439,24 @@ void main() {
     });
     inner.appendChild(divider);
 
-    // Exit (subtle × on the right) — SVG for baseline-free centering
+    // Exit × on the right — intentionally subtle (textDim at rest, text on
+    // hover) so it sits behind the active toggles in visual hierarchy.
+    //
+    // Explicit padding + box-sizing here is load-bearing: a host page like
+    // `button { padding: 0.5rem 1rem; }` (very common in resets) would
+    // otherwise inflate this 24x24 button into 56x40 and push the SVG out
+    // of the visible bar — the X stays invisible even though the styles in
+    // DevTools look fine. Every other chrome button sets padding inline;
+    // this one needed it too.
     const exitBtn = el('button', {
       display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
-      width: '26px', height: '26px', borderRadius: '6px',
+      padding: '0', boxSizing: 'border-box',
+      width: '24px', height: '24px', borderRadius: '6px',
       border: 'none', background: 'transparent',
       color: P.textDim, fontFamily: FONT, fontSize: '0', lineHeight: '0',
       cursor: 'pointer', transition: 'color 0.12s ease, background 0.12s ease',
     });
-    exitBtn.innerHTML = '<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="2.5" y1="2.5" x2="9.5" y2="9.5"/><line x1="9.5" y1="2.5" x2="2.5" y2="9.5"/></svg>';
+    exitBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><line x1="3" y1="3" x2="11" y2="11"/><line x1="11" y1="3" x2="3" y2="11"/></svg>';
     exitBtn.title = 'Exit live mode';
     exitBtn.addEventListener('mouseenter', () => { exitBtn.style.color = P.text; exitBtn.style.background = P.exitHover; });
     exitBtn.addEventListener('mouseleave', () => { exitBtn.style.color = P.textDim; exitBtn.style.background = 'transparent'; });
@@ -3301,6 +3474,7 @@ void main() {
     });
 
     document.body.appendChild(globalBarEl);
+    defangOutsideHandlers(globalBarEl);
 
     requestAnimationFrame(() => {
       globalBarEl.style.opacity = '1';
@@ -3513,6 +3687,11 @@ void main() {
     designShadow.appendChild(root);
 
     document.body.appendChild(designHost);
+    // The host is pointer-events: none; the panel inside the shadow DOM
+    // manages its own auto/none. Events bubble through the shadow boundary,
+    // so attaching here silences host-page outside-interaction handlers
+    // without touching the host's click-through behavior.
+    defangOutsideHandlers(designHost, { setPointerEvents: false });
 
     loadDesignPrefs();
     renderDesignChrome();
@@ -4577,6 +4756,18 @@ void main() {
     // Check for an active session to resume (variant wrapper already in DOM after HMR)
     if (!resumeSession()) {
       console.log('[impeccable] Live variant mode ready. Hover over elements to pick one.');
+      // SvelteKit (and any framework that hydrates after HTML parse) may add
+      // the variant wrapper AFTER init runs. Watch for it and retry resume
+      // once it appears. Disconnect on first hit.
+      const scout = new MutationObserver(() => {
+        const wrapper = document.querySelector('[data-impeccable-variants]');
+        if (!wrapper) return;
+        scout.disconnect();
+        if (resumeSession()) {
+          console.log('[impeccable] Resumed deferred session ' + currentSessionId + ' (post-hydration).');
+        }
+      });
+      scout.observe(document.body, { childList: true, subtree: true });
     } else {
       console.log('[impeccable] Resumed active variant session ' + currentSessionId + ' (' + arrivedVariants + '/' + expectedVariants + ' variants).');
     }

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

@@ -88,10 +88,15 @@ Output (JSON):
       const absFile = path.resolve(process.cwd(), relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
       const content = fs.readFileSync(absFile, 'utf-8');
-      const updated = removeTag(content, config.commentSyntax);
+      const detagged = removeTag(content, config.commentSyntax);
+      const updated = revertCspMeta(detagged);
       if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
       fs.writeFileSync(absFile, updated, 'utf-8');
-      return { file: relFile, removed: true };
+      return {
+        file: relFile,
+        removed: detagged !== content,
+        cspReverted: updated !== detagged,
+      };
     });
     console.log(JSON.stringify({ ok: true, results }));
     return;
@@ -109,11 +114,18 @@ Output (JSON):
     const absFile = path.resolve(process.cwd(), relFile);
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
-    const withoutOld = removeTag(content, config.commentSyntax);
-    const updated = insertTag(withoutOld, config, port);
-    if (updated === withoutOld) return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
+    const withTag = insertTag(withoutOld, config, port);
+    if (withTag === withoutOld) {
+      return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    }
+    const updated = patchCspMeta(withTag, port);
     fs.writeFileSync(absFile, updated, 'utf-8');
-    return { file: relFile, inserted: true };
+    return {
+      file: relFile,
+      inserted: true,
+      cspPatched: updated !== withTag,
+    };
   });
   const anyInserted = results.some((r) => r.inserted);
   console.log(JSON.stringify({ ok: anyInserted, port, results }));
@@ -296,6 +308,130 @@ function removeTag(content, _syntax) {
   return content;
 }
 
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // 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);
+  }
+  return result;
+}
+
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-execute
 // ---------------------------------------------------------------------------
@@ -306,3 +442,4 @@ if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs
 }
 
 export { insertTag, removeTag, validateConfig, buildTagBlock };
+// patchCspMeta + revertCspMeta are exported above where they're defined.

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

@@ -8,7 +8,7 @@
  *   npx impeccable poll --reply <id> error "msg" # Reply with error
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -146,13 +146,12 @@ 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());

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

@@ -21,11 +21,16 @@ 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';
 
 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 / DESIGN.json live wherever load-context.mjs resolves.
+// Keeps live-server in sync with the loader when users keep the docs in
+// .agents/context/, docs/, or a path set via IMPECCABLE_CONTEXT_DIR.
+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
 
@@ -113,7 +118,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 +136,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 +160,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 +169,7 @@ 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 'exit':
       return null;
     case 'prefetch':
@@ -315,8 +330,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 = path.join(CONTEXT_DIR, 'DESIGN.json');
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 

.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,17 +120,67 @@ 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;
@@ -133,17 +188,48 @@ The agent should insert variant HTML at insertLine.`);
   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,13 +249,24 @@ 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,
     originalLineCount: originalLines.length,
@@ -310,6 +407,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 +443,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/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 / DESIGN.json 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,12 +12,12 @@
     {
       "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.0",
+      "version": "3.0.5",
       "author": {
         "name": "Paul Bakaus",
         "email": "paul@paulbakaus.com"
       },
-      "source": "./",
+      "source": "./plugin",
       "category": "design",
       "homepage": "https://impeccable.style",
       "tags": ["design", "frontend", "ui", "ux", "skills", "commands"]

.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "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.0",
+  "version": "3.0.5",
   "author": {
     "name": "Paul Bakaus",
     "email": "paul@paulbakaus.com"
   },
   "homepage": "https://impeccable.style",
   "repository": "https://github.com/pbakaus/impeccable",
-  "skills": "./.claude/skills"
+  "skills": "./.claude/skills/"
 }

.claude/agents/anti-patterns.md

@@ -1,257 +0,0 @@
----
-name: anti-patterns
-description: Use when adding, modifying, or debugging an anti-pattern detection rule in this repo. Walks through the TDD recipe, the rule schema, all five plug-in points, jsdom constraints, and the post-implementation checklist. Trigger this for any work touching src/detect-antipatterns.mjs, tests/fixtures/antipatterns/, or extension/detector/.
-tools: Read, Edit, Write, Glob, Grep, Bash, mcp__claude-in-chrome__navigate, mcp__claude-in-chrome__javascript_tool, mcp__claude-in-chrome__tabs_context_mcp, mcp__claude-in-chrome__tabs_create_mcp
----
-
-# Anti-Pattern Engine Maintenance
-
-This agent handles every step of adding or modifying an anti-pattern detection rule in the impeccable repo. The rule engine is wired into many places — tests, browser bundle, extension detector, extension panel JSON, homepage count, and the skill content — and missing a step causes silent drift between them.
-
-## The five things that need to stay in sync
-
-When you add a rule, all of these update or get regenerated:
-
-| Where | What | How it stays in sync |
-|---|---|---|
-| `src/detect-antipatterns.mjs` `ANTIPATTERNS` | Rule metadata (id, category, name, description, skillSection, skillGuideline) and the detection logic (`checkXxx`) | **Hand-edited.** Source of truth. |
-| `src/detect-antipatterns-browser.js` | Browser-bundled engine for the public site overlay | Generated by `bun run build:browser` |
-| `extension/detector/detect.js` | Browser-bundled engine for the Chrome extension | Generated by `bun run build:extension` |
-| `extension/detector/antipatterns.json` | Rule list (id, name, category, description) for the extension's devtools panel — drives rule toggles UI | Generated by `bun run build:extension` |
-| `public/js/generated/counts.js` | `DETECTION_COUNT` integer for homepage display | Generated by `bun run build` |
-| `source/skills/impeccable/SKILL.md` and `reference/*.md` | Design guidance that a human or LLM reads. Can reference anti-patterns in its own voice. | **Hand-edited**, alongside the rule. Drift is a code-review concern, not a programmatic one. |
-
-The CLI (`bin/cli.js`) imports `ANTIPATTERNS` directly from `src/detect-antipatterns.mjs` — no separate sync needed.
-
-## Rule schema
-
-Each entry in the `ANTIPATTERNS` array (around src/detect-antipatterns.mjs:77) looks like this:
-
-```js
-{
-  id: 'icon-tile-stack',                          // kebab-case, unique, stable
-  category: 'slop',                                // 'slop' or 'quality' (see below)
-  name: 'Icon tile stacked above heading',        // human-readable, used in extension UI
-  description:                                     // 1–2 sentences. Used in CLI output, extension tooltips, web overlay labels
-    'A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container.',
-  skillSection: 'Typography',                      // OPTIONAL. The logical skill section this rule maps to; used for /docs/impeccable deep-links.
-  skillGuideline: 'large icons with rounded corners above every heading',  // OPTIONAL. Canonical short phrasing for the rule; used in CLI output and as a linkable fragment.
-}
-```
-
-### Categories
-
-- **`slop`** = "AI tells". Patterns that scream *AI generated this*. Things like purple gradients, gradient text, dark glow accents, thick side borders, icon-tile-stacks. Flagging these is about taste and freshness, not correctness.
-- **`quality`** = real design or accessibility issues regardless of who wrote the code. WCAG contrast, line length, padding, line height, justified text, skipped headings, etc.
-
-If you're not sure, ask: *"would a human designer who's careful and tasteful still ship this?"* If no, it's `quality`. If they would (because it works fine, it just looks templated), it's `slop`.
-
-### `skillSection` values
-
-The value is used by `scripts/build-sub-pages.js` to build deep links into the impeccable docs page. Use one of the logical sections the skill groups rules under (e.g. `Typography`, `Color`, `Layout`, `Motion`, `Visual Details`). If the section you pick matches an `### Heading` somewhere in the skill body, the deep link will land precisely; otherwise it falls back to the section's top. Omit entirely for rules that don't have a natural home in the skill.
-
-### `skillGuideline` phrasing
-
-Canonical short phrasing for the rule (3–6 words). Used as the CLI output label when `npx impeccable detect` reports a violation, and as human-readable text in the extension's devtools panel. The skill's prose may or may not echo this phrasing verbatim — the skill is the design-guidance document, not a rule manifest.
-
-Examples: `'AI color palette'`, `'large icons with rounded corners above every heading'`, `'WCAG AA contrast'`.
-
-Omit if the rule doesn't need a short label (rare — only niche a11y-only rules).
-
-## The TDD recipe (always do it in this order)
-
-This order is non-negotiable. Fixture and failing test before implementation. The full suite must run between the rule going in and you committing.
-
-### 1. Write the fixture (two-column convention)
-
-A single HTML file at `tests/fixtures/antipatterns/{rule-id}.html` with two columns: left = should-flag, right = should-pass. Each test case carries a unique heading text so the test can match snippets back to expectations.
-
-Convention skeleton:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <style>
-    .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 32px; max-width: 960px; margin: 0 auto; padding: 24px; }
-    .col h2 { font-size: 14px; text-transform: uppercase; }
-    /* ... per-case styles with EXPLICIT pixel dimensions (jsdom can't lay out) ... */
-  </style>
-</head>
-<body>
-  <div class="grid">
-    <div class="col" data-col="flag">
-      <h2>Should flag</h2>
-      <!-- 4–6 cases that should be flagged, each with a unique <h3> text -->
-    </div>
-    <div class="col" data-col="pass">
-      <h2>Should pass</h2>
-      <!-- 5–8 cases that should NOT be flagged: cover every false-positive shape you can think of -->
-    </div>
-  </div>
-  <script src="/js/detect-antipatterns-browser.js"></script>
-</body>
-</html>
-```
-
-The script tag at the bottom is critical — it lets you load the fixture in the browser via `http://localhost:3000/fixtures/antipatterns/{rule-id}.html` (served by `server/index.js:62` route for `/fixtures/*`).
-
-**Should-pass cases must cover the false-positive shapes you can think of in advance.** A good fixture has 5+ pass cases. The icon-tile-stack fixture covers: round avatar, wide thumbnail, side-by-side, no-icon, too-tiny, too-huge.
-
-### 2. Write the failing test
-
-Add to `tests/detect-antipatterns-fixtures.test.mjs` in its own `describe` block. Use the snippet-substring matching pattern — the test parses heading text out of each finding's snippet and asserts membership against expected lists:
-
-```js
-describe('detectHtml — {rule-id}', () => {
-  const SHOULD_FLAG = ['Heading One', 'Heading Two', /* ... */];
-  const SHOULD_PASS = ['Pass Heading One', /* ... */];
-
-  it('{rule-id}: flags only the should-flag column', async () => {
-    const f = await detectHtml(path.join(FIXTURES, '{rule-id}.html'));
-    const flagged = new Set();
-    for (const r of f) {
-      if (r.antipattern !== '{rule-id}') continue;
-      const m = (r.snippet || '').match(/"([^"]+)"/);
-      if (m) flagged.add(m[1]);
-    }
-    for (const text of SHOULD_FLAG) {
-      assert.ok(flagged.has(text), `expected "${text}" to be flagged`);
-    }
-    for (const text of SHOULD_PASS) {
-      assert.ok(!flagged.has(text), `"${text}" should NOT be flagged`);
-    }
-  });
-});
-```
-
-For this to work, the rule's snippet **must include the heading text in quotes**. See "Snippet conventions" below.
-
-Run `node --test tests/detect-antipatterns-fixtures.test.mjs` and **watch it fail**. If it doesn't fail, your test is wrong.
-
-### 3. Add the rule definition
-
-Add a new entry to the `ANTIPATTERNS` array in `src/detect-antipatterns.mjs`. Place it in the right category section (slop or quality). Fill in all fields including `skillSection` and `skillGuideline`.
-
-### 4. Implement the pure check function
-
-Add a `checkXxx(opts)` function alongside the others (`checkColors`, `checkBorders`, `checkMotion`, `checkGlow`, `checkIconTile`, etc.). The pure function takes a plain options object — no DOM access — and returns an array of `{ id, snippet }`. This makes it testable and reusable across the browser/Node adapters.
-
-Example shape (see `checkIconTile` in src/detect-antipatterns.mjs for a real one):
-
-```js
-function checkXxx(opts) {
-  const { tag, /* whatever fields the rule needs */ } = opts;
-  if (SAFE_TAGS.has(tag)) return [];
-  // ... your detection logic ...
-  if (matches) {
-    return [{ id: 'rule-id', snippet: `... "${headingText}"` }];
-  }
-  return [];
-}
-```
-
-### 5. Add the two adapters
-
-Two adapters wrap the pure function with environment-specific input gathering:
-
-- **`checkElementXxxDOM(el)`** — for the browser. Uses `getComputedStyle(el)` and `el.getBoundingClientRect()`.
-- **`checkElementXxx(el, tag, window)`** — for jsdom (Node). Uses `window.getComputedStyle(el)` and **must read explicit pixel dimensions from `parseFloat(style.width)`** instead of bounding rects, because **jsdom does not lay out** — `getBoundingClientRect()` returns 0×0 for everything.
-
-If your rule needs vertical positioning info (e.g. "icon must be above heading"), that check is browser-only — gate it behind `if (headingTop && siblingBottom)` so the Node path skips it. The structural checks alone (sizes, sibling identity, classes) are enough for the fixture.
-
-### 6. Wire into both element-iteration loops
-
-Two loops iterate every element on the page. You need to add your DOM-adapter call to **both**:
-
-- **Browser loop** at src/detect-antipatterns.mjs:1837 (`for (const el of document.querySelectorAll('*'))` with the `findings` spread). Add a line like:
-  ```js
-  ...checkElementXxxDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
-  ```
-- **Node (jsdom) loop** at src/detect-antipatterns.mjs:2058 (in `detectHtml`). Add a block like:
-  ```js
-  for (const f of checkElementXxx(el, tag, window)) {
-    findings.push(finding(f.id, filePath, f.snippet));
-  }
-  ```
-
-Forgetting one of these is the most common mistake — the test passes but the live page doesn't show anything (or vice versa).
-
-### 7. Decide whether the skill needs an update
-
-If the rule introduces a new design concept not already covered by the impeccable skill, update `source/skills/impeccable/SKILL.md` (or the appropriate register file in `reference/editorial.md` / `reference/product.md`) to teach the concept. The skill is a design-guidance document — it doesn't need to echo every rule verbatim, and one skill line can cover multiple engine rules. Only add prose if there's a real gap in the guidance.
-
-### 8. Run the build (regenerates everything)
-
-```bash
-bun run build && bun run build:browser && bun run build:extension
-```
-
-This regenerates:
-- `src/detect-antipatterns-browser.js` (public-site detector)
-- `extension/detector/detect.js` (extension detector)
-- `extension/detector/antipatterns.json` (extension rule list, includes description)
-- `public/js/generated/counts.js` (DETECTION_COUNT)
-
-### 9. Run the test suite
-
-```bash
-bun run test
-```
-
-166 unit tests + N fixture tests, including your new one. All should be green.
-
-### 10. Verify on a live page in the browser
-
-Don't skip this. The jsdom path uses `parseFloat(style.width)` and the browser path uses `getBoundingClientRect()` — they can disagree. The fixture test catches one path; manual browser verification catches the other.
-
-```
-http://localhost:3000/fixtures/antipatterns/{rule-id}.html
-http://localhost:3000/antipattern-examples/{your-example}.html  (if relevant)
-http://localhost:3000/                                           (no false positives on real pages)
-```
-
-Use the chrome MCP tools (`mcp__claude-in-chrome__navigate` + `mcp__claude-in-chrome__javascript_tool`) to inject `window.impeccableScan()` and read `.impeccable-overlay` / `.impeccable-label` from the DOM to verify. Don't try to screenshot — the overlays are decorative; read them programmatically.
-
-## Snippet conventions
-
-The fixture-test convention extracts the heading text from a finding's snippet using regex `/"([^"]+)"/` — so **wrap the identifying heading text in straight double quotes** in your snippet. Examples:
-
-- `'80x80px icon tile above h3 "Lightning Fast"'`
-- `'4.5:1 (need 4.5:1) — text #808080 on #3b82f6'`  ← uses element identifiers instead, since this rule isn't anchored to a heading
-
-If your rule isn't naturally anchored to a heading, pick another stable identifier (a class name, the parent element's text, etc.) and document the test pattern in the test itself.
-
-## jsdom constraints (the most common gotcha)
-
-- **No layout.** `getBoundingClientRect()` returns `0×0` always. Read `parseFloat(style.width)` and `parseFloat(style.height)` instead — jsdom does honor explicit pixel widths in `<style>` and inline styles.
-- **`background:` shorthand isn't decomposed.** `style.backgroundColor` and `style.backgroundImage` may be empty even when `style="background: ..."` is set. The existing `resolveBackground()` and `resolveGradientStops()` helpers (src/detect-antipatterns.mjs:631 and src/detect-antipatterns.mjs:670) handle this — use them.
-- **Computed colors are normalized in real browsers, not in jsdom.** A browser returns `rgb(59, 130, 246)`; jsdom may return the original hex. The `parseGradientColors()` helper handles both.
-- **No SAFE_TAGS skipping for parent walks.** When walking ancestors, you don't get the `SAFE_TAGS` filter the main loop applies — be explicit.
-
-## Where to find concrete example rules to learn from
-
-- Simplest border check: **`side-tab`** — `checkBorders()` at src/detect-antipatterns.mjs:312
-- Color/contrast with gradient handling: **`low-contrast`** — `checkColors()` at src/detect-antipatterns.mjs:339
-- Element-relationship check (siblings): **`icon-tile-stack`** — `checkIconTile()` at src/detect-antipatterns.mjs:425
-- Page-level / cross-element: **`flat-type-hierarchy`** — `checkPageTypography()` at src/detect-antipatterns.mjs:1080
-- Motion/animation: **`bounce-easing`** — `checkMotion()` at src/detect-antipatterns.mjs:425
-
-## Pre-commit checklist
-
-Before you commit a new rule:
-
-- [ ] Test passes: `bun run test` is green
-- [ ] Build passes: `bun run build && bun run build:browser && bun run build:extension` is green
-- [ ] Live verification: rule fires on a real page and produces zero false positives on the homepage `http://localhost:3000/`
-- [ ] Both element loops were updated (browser DOM at line ~1846 + Node jsdom at line ~2058)
-- [ ] Snippet format matches the test's extraction regex
-- [ ] Fixture covers ≥4 should-flag and ≥5 should-pass cases
-- [ ] Skill reviewed: if the rule introduces a new design concept, the relevant skill file teaches it
-- [ ] Commit only the relevant files — `git status` will show many unrelated stale skill builds; do not stage them
-
-## Things that have bitten previous sessions
-
-- **Forgot to run `bun run build:extension`** — extension JSON went stale, missing the new rule. Symptom: extension panel doesn't show toggle for new rule. Fix: always run all three build commands.
-- **Forgot to update both loops** — test passed in jsdom but live browser was silent (or vice versa). Fix: grep for an existing rule's adapter call and copy its placement.
-- **Wrote the fixture without explicit pixel dimensions** — jsdom returned 0×0 and the rule never matched. Fix: always set `width: Npx; height: Npx` in CSS for fixture elements, or use inline style attributes.

.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.0
+version: 3.0.5
 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.
@@ -13,11 +13,30 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 ## Setup (non-optional)
 
-Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| 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. |
+
+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.
 
 ### 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.
@@ -28,13 +47,13 @@ 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.
 
-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 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.
 
 If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed.
 
@@ -107,7 +126,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
 
@@ -147,6 +169,8 @@ Plus two management commands — `pin <command>` and `unpin <command>`, detailed
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
 ## Pin / Unpin
 
 **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

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

@@ -122,7 +122,8 @@ Use appropriate techniques for each animation:
 /* Prefer for simple, declarative animations */
 - transitions for state changes
 - @keyframes for complex sequences
-- transform + opacity only (GPU-accelerated)
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
 ```
 
 ### JavaScript Animation
@@ -134,9 +135,10 @@ Use appropriate techniques for each animation:
 ```
 
 ### Performance
-- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - **will-change**: Add sparingly for known expensive animations
-- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
 ### Accessibility
@@ -152,7 +154,7 @@ Use appropriate techniques for each animation:
 
 **NEVER**:
 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
-- Animate layout properties (width, height, top, left)—use transform instead
+- 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

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

@@ -22,7 +22,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 **Check for**:
 - **Layout thrashing**: Reading/writing layout properties in loops
-- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
 - **Bundle size**: Unnecessary imports, unused dependencies
 - **Render performance**: Unnecessary re-renders, missing memoization

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

@@ -29,6 +29,16 @@ 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:

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

@@ -1,12 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful.
+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 Gate
+
+Craft cannot build until all of these are true:
+
+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.
+
+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.
+
+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.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+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.
+
+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."
 
 ## Step 1: Shape the Design
 
 Run /impeccable shape, passing along whatever feature description the user provided.
 
-Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+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.
+
+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 has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
 
@@ -24,15 +53,17 @@ 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: North Star Mock (Capability-Gated)
+## Step 3: Land the Visual Direction (Capability-Gated)
 
-Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+Before implementation, generate high-fidelity visual comps when all of these are true:
 
 - 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.
 
-When those conditions are met, this step is the default for **both brand and product work**.
+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.
+
+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
 
@@ -40,25 +71,43 @@ Use the mock step to find a stronger visual lane than code-first generation woul
 
 ### What to generate
 
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+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.
 
-### After generation
+### Approval loop
 
-Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+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
 
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
 
-## Step 4: Asset Extraction (Optional)
+### 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.
 
@@ -74,53 +123,71 @@ Good candidates:
 - 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.
+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
+## Step 5: Build to Production Quality
 
-Implement the feature following the design brief. Work in this order:
+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.
 
-1. **Structure first**: HTML/semantic structure for the primary state. No styling yet.
-2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy.
-3. **Typography and color**: Apply the type scale and color system.
-4. **Interactive states**: Hover, focus, active, disabled.
-5. **Edge case states**: Empty, loading, error, overflow, first-run.
-6. **Motion**: Purposeful transitions and animations (if appropriate).
-7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context.
+### Production bar
 
-### During Build
-- Test with real (or realistic) data at every step, not placeholder text
-- Check each state as you build it, not all at the end
-- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief or the chosen north-star direction
-- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
-- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
+- 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.
 
-## Step 6: Visual Iteration
+## Step 6: Browser-Based Iteration
 
 **This step is critical.** Do not stop after the first implementation pass.
 
-Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback.
+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.
 
-Iterate through these checks visually:
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+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.
+
+### 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 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.
-3. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink?
-6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing.
+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.
 
-After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
+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
 
 Present the result to the user:
 - Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
 - Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
+- 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/live.md

@@ -29,7 +29,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).
 
@@ -74,7 +74,7 @@ Reading annotations precisely:
 ### 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`:
@@ -82,9 +82,12 @@ 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.
 
+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.
+
 Output on success: `{ file, insertLine, commentSyntax }`.
 
 **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:
@@ -101,38 +104,81 @@ 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. **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?)
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+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, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+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 primary axes, not three riffs on color.
+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.
 
-**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.
+**Departure mode.** Each variant anchors to a different **aesthetic lane**, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+- Tech-minimal (Stripe / Linear / Vercel-restraint)
+- Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)
+- Terminal-native (actual code surface, syntax-highlighted UI as the design)
+- Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)
+- Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)
+- Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)
+- Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)
 
-> 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.
+Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. *Editorial-typographic is currently a reflex-reject lane* — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.
 
-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.
+#### 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: *editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal*. If any two variants share a family label, rework. *This pass is non-negotiable in departure mode and catches the editorial-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:
 
@@ -150,7 +196,13 @@ If two of them rhyme ("both use big type" / "both are stacks of sections" / "bot
 
 ### 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
 
@@ -181,6 +233,25 @@ The first variant has no `display: none` (visible by default). All others do. If
 
 One edit, all variants — the browser's MutationObserver picks everything up in one pass.
 
+**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 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)
 
 Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
@@ -246,6 +317,16 @@ node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --fil
 
 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.

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

@@ -38,9 +38,19 @@ Timing matters more than easing. These durations feel right for most UI:
 
 **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.
 
-## The Only Two Properties You Should Animate
+## Premium Motion Materials
 
-**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties: blur reveals, backdrop-filter panels, saturation or brightness shifts, shadow bloom, SVG filters, masks, clip paths, gradient-position movement, and variable font or shader-driven effects.
+
+Use the right material for the effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography.
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances, atmospheric transitions.
+- **Clip path / masks**: wipes, reveals, editorial cropping, product-like transitions.
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state.
+- **Grid-template rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly.
+
+The hard rule is not "transform and opacity only." The hard rule is: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify in-browser that the result is smooth on the target viewports. If blur/filter makes the interaction feel significantly more premium and remains smooth, use it.
 
 ## Staggered Animations
 

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

@@ -109,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 

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

@@ -4,17 +4,17 @@ Perform a meticulous final pass to catch all the small details that separate goo
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+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: color tokens, spacing scale, typography styles, component API.
-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?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+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.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+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
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -22,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+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
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - 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.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -50,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+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.
+- **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.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -89,7 +104,7 @@ Every interactive element needs all states:
 
 - **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.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **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`
 
@@ -158,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -183,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- 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)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 

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

@@ -12,7 +12,18 @@ Most AI-generated UIs fail not because of bad code, but because of skipped think
 
 **Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
 
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and call the AskUserQuestion tool to clarify.
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and call the AskUserQuestion tool to clarify.
+
+### 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.
+
+- 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.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -63,7 +74,11 @@ After the discovery interview, generate a small set of visual direction probes *
 - 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.
 
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
+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.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
 
 ### What to generate
 
@@ -89,11 +104,11 @@ 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 and proceed directly to the design brief.
+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.
 
 ## Phase 2: Design Brief
 
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
+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.
 
 ### Brief Structure
 
@@ -131,6 +146,6 @@ Anything unresolved that the implementer should resolve during build.
 
 ---
 
-STOP and call the AskUserQuestion tool to clarify. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
+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.
 
 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/teach.md

@@ -21,11 +21,13 @@ 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 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. which to refresh. Skip the one the user doesn't want changed.
+- **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.
 
 Never silently overwrite an existing file. Always confirm first.
 
+If teach was invoked as a setup blocker by another command, such as `/impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
 ## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
@@ -48,7 +50,22 @@ Note what you've learned and what remains unclear. This exploration feeds both P
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase.
+STOP and call the AskUserQuestion tool to clarify. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- 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.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+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)
 
@@ -56,7 +73,7 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 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. which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+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.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
@@ -79,6 +96,8 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
 Synthesize into a strategic document:
 
 ```markdown
@@ -134,4 +153,4 @@ Summarize:
 
 If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
 
-Optionally STOP and call the AskUserQuestion tool to clarify. whether they'd like a brief summary of PRODUCT.md appended to CLAUDE.md for easier agent reference. If yes, append a short **Design Context** pointer section there.
+Optionally STOP and call the AskUserQuestion tool to clarify. Ask whether they'd like a brief summary of PRODUCT.md appended to CLAUDE.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.claude/skills/impeccable/scripts/command-metadata.json

@@ -1,10 +1,10 @@
 {
   "craft": {
-    "description": "Full shape-then-build flow with visual iteration. Plans the UX with /impeccable shape, loads the right reference files, then builds and iterates visually until the result is delightful. Use when building a new feature end-to-end.",
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
     "argumentHint": ""
   },
   "document": {
@@ -84,7 +84,7 @@
     "argumentHint": "[target]"
   },
   "shape": {
-    "description": "Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written.",
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
     "argumentHint": "[feature to shape]"
   },
   "typeset": {

.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);
@@ -150,12 +163,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
 
   if (cssContent) {
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
-    replacement.push(indent + '<style data-impeccable-css="' + id + '">');
+    // 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.
+    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
     // Re-indent CSS content to match
     for (const cssLine of cssContent) {
       replacement.push(indent + cssLine.trimStart());
     }
-    replacement.push(indent + '</style>');
+    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
     if (paramValues && Object.keys(paramValues).length > 0) {
       // Preserve the user's knob positions for the carbonize-cleanup agent
       // to bake into the final CSS when it collapses scoped rules.
@@ -169,8 +184,13 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // in a data-impeccable-variant="N" div with `display: contents` (so layout
   // isn't affected). The carbonize agent strips this attribute + wrapper when
   // it moves the CSS to a proper stylesheet.
+  //
+  // Style attribute syntax has to follow the host file's flavor — JSX files
+  // 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) {
-    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" style="display: contents">');
+    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
     replacement.push(indent + '</div>');
   } else {
@@ -178,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');
 
@@ -209,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:
@@ -336,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;
@@ -344,12 +430,69 @@ function extractCss(lines, block, id) {
     }
 
     if (inStyle) {
-      if (line.trimStart().startsWith('</style>')) break;
+      // Detect </style> anywhere on the line — JSX template-literal closes
+      // (`}</style>`) put the close mid-line, and we don't want to absorb the
+      // template-literal punctuation as CSS content.
+      const closeIdx = line.indexOf('</style>');
+      if (closeIdx !== -1) break;
       content.push(line);
     }
   }
 
-  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.js

@@ -197,6 +197,45 @@
 
   function id8() { return crypto.randomUUID().replace(/-/g, '').slice(0, 8); }
 
+  // Modal-aware chrome: keep our floating UI clickable inside Radix /
+  // Headless UI / vaul portals.
+  //
+  // Two host-page behaviors break us when the picked element lives inside a
+  // modal dialog:
+  //
+  //   1. Modal scroll-lock disables outside pointer events. Radix's
+  //      `DismissableLayer` sets `document.body.style.pointerEvents = 'none'`
+  //      while a modal is open and only restores `auto` on the layer. Our
+  //      chrome inherits `none` from <body> and becomes unclickable.
+  //   2. The dialog's outside-interaction handler (Radix's
+  //      `usePointerDownOutside`) listens at document level and dismisses
+  //      the dialog whenever a `pointerdown` lands outside the layer node.
+  //      Our chrome is a sibling of <body>, so Radix classifies our clicks
+  //      as outside and tears the dialog down mid-task.
+  //
+  // We can't reliably re-parent our chrome into the dialog subtree (z-index
+  // stacking, scroll containers, theming all become host-page concerns), so
+  // we defang both behaviors at our root:
+  //
+  //   - `pointer-events: auto !important` overrides the inherited `none`.
+  //   - Stop `pointerdown` / `mousedown` propagation so the document-level
+  //     dismiss listener never fires for our clicks.
+  //   - Stop `focusin` propagation so any focus shifts inside our chrome
+  //     don't read as "focus moved outside the dialog" to focus traps.
+  //
+  // Click events still bubble normally — only the early pointer/focus
+  // signals that drive outside-interaction detection are silenced.
+  function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+    if (!rootEl) return;
+    if (setPointerEvents) {
+      rootEl.style.setProperty('pointer-events', 'auto', 'important');
+    }
+    const stop = (e) => e.stopPropagation();
+    rootEl.addEventListener('pointerdown', stop);
+    rootEl.addEventListener('mousedown', stop);
+    rootEl.addEventListener('focusin', stop);
+  }
+
   // ---------------------------------------------------------------------------
   // Highlight overlay
   // ---------------------------------------------------------------------------
@@ -336,6 +375,11 @@
     annotOverlayEl.addEventListener('pointerup', onAnnotUp);
     annotOverlayEl.addEventListener('pointercancel', onAnnotUp);
     document.body.appendChild(annotOverlayEl);
+    // Modal-host friendliness: pointer-events is already 'auto' on this
+    // overlay; we only need to silence the host's outside-interaction
+    // listeners. Don't override pointer-events here (the overlay toggles
+    // visibility via display:none, which is fine).
+    defangOutsideHandlers(annotOverlayEl, { setPointerEvents: false });
   }
 
   function updateClearChip() {
@@ -811,6 +855,7 @@
       maxWidth: '520px', minWidth: '320px',
     });
     document.body.appendChild(barEl);
+    defangOutsideHandlers(barEl);
   }
 
   function positionBar() {
@@ -905,7 +950,12 @@
     pill.addEventListener('click', (e) => { e.stopPropagation(); toggleActionPicker(); });
     row.appendChild(pill);
 
-    // Freeform input
+    // Freeform input. Focus state shows an accent-colored border only —
+    // an earlier version tinted the background with `BP.accentSoft`, which
+    // composited against the dark bar surface to a murky purple where the
+    // browser's default placeholder gray was unreadable. Placeholder color
+    // is set explicitly via a one-shot stylesheet keyed off this input's id
+    // so it picks up the bar's `textDim` token in both themes.
     const input = document.createElement('input');
     input.id = PREFIX + '-input';
     input.type = 'text';
@@ -916,15 +966,20 @@
       border: '1px solid transparent', background: 'transparent',
       fontFamily: FONT, fontSize: '12px', color: BP.text,
       outline: 'none',
-      transition: 'border-color 0.15s ease, background 0.15s ease',
+      transition: 'border-color 0.15s ease',
     });
+    if (!document.getElementById(PREFIX + '-input-style')) {
+      const s = document.createElement('style');
+      s.id = PREFIX + '-input-style';
+      s.textContent =
+        '#' + PREFIX + '-input::placeholder { color: ' + BP.textDim + '; opacity: 1; }';
+      document.head.appendChild(s);
+    }
     input.addEventListener('focus', () => {
-      input.style.borderColor = BP.hairline;
-      input.style.background = BP.accentSoft;
+      input.style.borderColor = BP.accent;
     });
     input.addEventListener('blur', () => {
       input.style.borderColor = 'transparent';
-      input.style.background = 'transparent';
     });
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') { e.stopPropagation(); e.preventDefault(); handleGo(); return; }
@@ -1320,6 +1375,7 @@
 
     pickerEl.appendChild(grid);
     document.body.appendChild(pickerEl);
+    defangOutsideHandlers(pickerEl);
 
     // Cache the palette on the picker so toggleActionPicker's state refresh
     // uses the same theme-aware colors when it repaints chips.
@@ -1433,6 +1489,10 @@
 
     paramsPanelEl.appendChild(paramsPanelBody);
     document.body.appendChild(paramsPanelEl);
+    // Don't override pointer-events: the panel toggles between 'none' (closed,
+    // click-through) and 'auto' (open) on its own. Just silence the host's
+    // outside-interaction listeners while the panel is open.
+    defangOutsideHandlers(paramsPanelEl, { setPointerEvents: false });
     paramsPanelInner = paramsPanelEl; // compatibility alias for the rest of the code
   }
 
@@ -2011,7 +2071,16 @@
       for (const m of mutations) {
         if (m.target.closest?.('[data-impeccable-variants]')) { dominated = true; break; }
         for (const n of m.addedNodes) {
-          if (n.nodeType === 1 && (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant)) {
+          if (n.nodeType !== 1) continue;
+          // Direct hit: the added node itself is the wrapper or a variant.
+          if (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant) {
+            dominated = true; break;
+          }
+          // Subtree hit: framework HMR (notably SvelteKit) sometimes replaces
+          // a whole subtree where the wrapper is a descendant of the added
+          // node. Without this check, the observer ignores those mutations
+          // and the session stays in GENERATING forever.
+          if (n.querySelector?.('[data-impeccable-variants],[data-impeccable-variant]')) {
             dominated = true; break;
           }
         }
@@ -2126,17 +2195,20 @@
             }
             break;
           }
-          // HMR didn't propagate in time. Give it a 2s grace window, then
-          // reload the page. resumeSession counts variants off the rendered
-          // DOM on load and transitions straight to CYCLING — reload is the
-          // one universal recovery path: HTML, JSX/TSX, Vue, Svelte, static
-          // servers, anything. We used to try DOMParser on the raw source,
-          // but JSX expressions aren't valid HTML and the parse fails.
+          // Variants are in source but not in the DOM yet. Common when the
+          // picked element lived inside conditional render (closed modal,
+          // hidden tab, a route the user navigated away from). The variant
+          // MutationObserver stays armed and auto-transitions to CYCLING
+          // the moment the wrapper actually mounts. Nudge the user toward
+          // that path with a toast — better than the prior force-reload
+          // which reset framework state and left the session stuck.
           setTimeout(() => {
             if (arrivedVariants >= expectedVariants && expectedVariants > 0) return;
             if (state !== 'GENERATING') return;
-            saveSession();
-            window.location.reload();
+            showToast(
+              "Variants ready. If the picked element isn't visible, retrace the path that revealed it — they'll appear automatically.",
+              15000,
+            );
           }, 2000);
           break;
         case 'error':
@@ -2236,6 +2308,60 @@
     showBar('configure');
     startScrollTracking();
     maybePrefetchPage();
+    maybeWarnConditionalAncestor(selectedElement);
+  }
+
+  /**
+   * Surface a brief, non-blocking heads-up when the picked element lives
+   * inside a container whose visibility is gated by ephemeral state — modals,
+   * collapsible panels, popovers, off-screen tab panels. If HMR remounts the
+   * parent during generation (Vite Fast Refresh, SvelteKit page reload), the
+   * variants land in source but stay invisible until the user re-opens the
+   * container. Telling the user upfront is much friendlier than the silent
+   * timeout-then-toast that they'd otherwise hit.
+   *
+   * Heuristic, intentionally narrow — only fires for unambiguous cases so
+   * we don't cry wolf on every nested element.
+   */
+  function maybeWarnConditionalAncestor(el) {
+    let node = el?.parentElement;
+    let depth = 0;
+    while (node && depth < 12) {
+      // 1. Active dialog / modal
+      if (node.getAttribute && node.getAttribute('role') === 'dialog'
+          && node.getAttribute('aria-modal') === 'true') {
+        showToast('Heads up: this element lives inside a dialog. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 2. Common Radix / shadcn / headless-ui open-state attribute
+      if (node.dataset && node.dataset.state === 'open') {
+        showToast('Heads up: this element lives inside an open panel. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 3. Tab panel — only meaningful when the page also shows ANOTHER
+      // tab as selected. A single tabpanel with no tablist is just a static
+      // section in disguise and isn't conditional.
+      if (node.getAttribute && node.getAttribute('role') === 'tabpanel') {
+        const list = document.querySelector('[role="tablist"]');
+        if (list) {
+          const tabs = list.querySelectorAll('[role="tab"]');
+          if (tabs.length > 1) {
+            showToast('Heads up: this element lives in a tab panel. If state resets during generation, switch back to this tab.', 6000);
+            return;
+          }
+        }
+      }
+      // 4. Collapsible: aria-expanded sibling. Look for the trigger button.
+      if (node.id) {
+        const trigger = document.querySelector(`[aria-controls="${CSS.escape(node.id)}"][aria-expanded="true"]`);
+        if (trigger) {
+          showToast('Heads up: this element lives inside an expandable section. If state resets during generation, re-expand it.', 6000);
+          return;
+        }
+      }
+      node = node.parentElement;
+      depth++;
+    }
   }
 
   // Fire a lightweight prefetch event the first time the user selects an
@@ -2496,11 +2622,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
@@ -2694,7 +2824,13 @@ void main() {
       const img = document.createElement('img');
       img.src = URL.createObjectURL(blob);
       img.id = PREFIX + '-shader';
-      Object.assign(img.style, canvas.style, { outline: '2px dashed ' + C.brand, outlineOffset: '-2px' });
+      // Copy positioning via cssText. Object.assign across CSSStyleDeclaration
+      // throws in modern Chromium because the source's indexed properties
+      // (style[0], [1], ...) are read-only and the engine forbids writing
+      // them on the destination.
+      img.style.cssText = canvas.style.cssText;
+      img.style.outline = '2px dashed ' + C.brand;
+      img.style.outlineOffset = '-2px';
       document.body.appendChild(img);
       shaderState = { canvas: img, gl: null, program: null, texture: null, rafId: 0, startTime: 0 };
       return;
@@ -2942,8 +3078,16 @@ void main() {
 
   function showToast(message, duration) {
     if (toastEl) toastEl.remove();
+    // Stack the toast above the global bar (which sits at bottom:14px) so
+    // the two never overlap. Read the bar's actual rect — its height varies
+    // with hover-expanded labels — and fall back to a sensible default
+    // when the bar isn't mounted yet.
+    const barRect = globalBarEl?.getBoundingClientRect();
+    const barTopFromBottom = barRect && barRect.height > 0
+      ? Math.max(16, window.innerHeight - barRect.top + 12)
+      : 16;
     toastEl = el('div', {
-      position: 'fixed', bottom: '16px', left: '50%',
+      position: 'fixed', bottom: barTopFromBottom + 'px', left: '50%',
       transform: 'translateX(-50%) translateY(8px)',
       background: C.ink, color: C.white,
       fontFamily: FONT, fontSize: '12px',
@@ -3066,13 +3210,33 @@ void main() {
       // page bg. Used for screenshots and theme QA.
       const override = localStorage.getItem('impeccable-dev-theme');
       if (override === 'light' || override === 'dark') return override;
-      const bg = getComputedStyle(document.body).backgroundColor
-        || getComputedStyle(document.documentElement).backgroundColor;
-      const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-      if (!m) return 'light';
-      const [, r, g, b] = m;
+
+      // Walk body → html, taking the first opaque background. The browser's
+      // default body / html background is `rgba(0, 0, 0, 0)`, which a naive
+      // regex would read as black and mislabel a perfectly white page as
+      // dark. Honoring alpha avoids that — and falling through to <html>
+      // catches the common pattern of a bg only on <html> (or only on body).
+      function readOpaque(el) {
+        if (!el) return null;
+        const bg = getComputedStyle(el).backgroundColor;
+        const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/);
+        if (!m) return null;
+        const alpha = m[4] == null ? 1 : parseFloat(m[4]);
+        if (alpha < 0.5) return null; // transparent / nearly transparent → skip
+        return [+m[1], +m[2], +m[3]];
+      }
+
+      const rgb = readOpaque(document.body) || readOpaque(document.documentElement);
+      // Both transparent → fall back to the browser's effective canvas color.
+      // White is the universal default; only one in a thousand sites swaps it
+      // via `color-scheme: dark` on <html>, and `prefers-color-scheme` lets
+      // us catch that case.
+      if (!rgb) {
+        return matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      const [r, g, b] = rgb;
       // Perceptual luminance (Rec. 709)
-      const L = (0.2126 * +r + 0.7152 * +g + 0.0722 * +b) / 255;
+      const L = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
       return L > 0.55 ? 'light' : 'dark';
     } catch { return 'light'; }
   }
@@ -3275,15 +3439,24 @@ void main() {
     });
     inner.appendChild(divider);
 
-    // Exit (subtle × on the right) — SVG for baseline-free centering
+    // Exit × on the right — intentionally subtle (textDim at rest, text on
+    // hover) so it sits behind the active toggles in visual hierarchy.
+    //
+    // Explicit padding + box-sizing here is load-bearing: a host page like
+    // `button { padding: 0.5rem 1rem; }` (very common in resets) would
+    // otherwise inflate this 24x24 button into 56x40 and push the SVG out
+    // of the visible bar — the X stays invisible even though the styles in
+    // DevTools look fine. Every other chrome button sets padding inline;
+    // this one needed it too.
     const exitBtn = el('button', {
       display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
-      width: '26px', height: '26px', borderRadius: '6px',
+      padding: '0', boxSizing: 'border-box',
+      width: '24px', height: '24px', borderRadius: '6px',
       border: 'none', background: 'transparent',
       color: P.textDim, fontFamily: FONT, fontSize: '0', lineHeight: '0',
       cursor: 'pointer', transition: 'color 0.12s ease, background 0.12s ease',
     });
-    exitBtn.innerHTML = '<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="2.5" y1="2.5" x2="9.5" y2="9.5"/><line x1="9.5" y1="2.5" x2="2.5" y2="9.5"/></svg>';
+    exitBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><line x1="3" y1="3" x2="11" y2="11"/><line x1="11" y1="3" x2="3" y2="11"/></svg>';
     exitBtn.title = 'Exit live mode';
     exitBtn.addEventListener('mouseenter', () => { exitBtn.style.color = P.text; exitBtn.style.background = P.exitHover; });
     exitBtn.addEventListener('mouseleave', () => { exitBtn.style.color = P.textDim; exitBtn.style.background = 'transparent'; });
@@ -3301,6 +3474,7 @@ void main() {
     });
 
     document.body.appendChild(globalBarEl);
+    defangOutsideHandlers(globalBarEl);
 
     requestAnimationFrame(() => {
       globalBarEl.style.opacity = '1';
@@ -3513,6 +3687,11 @@ void main() {
     designShadow.appendChild(root);
 
     document.body.appendChild(designHost);
+    // The host is pointer-events: none; the panel inside the shadow DOM
+    // manages its own auto/none. Events bubble through the shadow boundary,
+    // so attaching here silences host-page outside-interaction handlers
+    // without touching the host's click-through behavior.
+    defangOutsideHandlers(designHost, { setPointerEvents: false });
 
     loadDesignPrefs();
     renderDesignChrome();
@@ -4577,6 +4756,18 @@ void main() {
     // Check for an active session to resume (variant wrapper already in DOM after HMR)
     if (!resumeSession()) {
       console.log('[impeccable] Live variant mode ready. Hover over elements to pick one.');
+      // SvelteKit (and any framework that hydrates after HTML parse) may add
+      // the variant wrapper AFTER init runs. Watch for it and retry resume
+      // once it appears. Disconnect on first hit.
+      const scout = new MutationObserver(() => {
+        const wrapper = document.querySelector('[data-impeccable-variants]');
+        if (!wrapper) return;
+        scout.disconnect();
+        if (resumeSession()) {
+          console.log('[impeccable] Resumed deferred session ' + currentSessionId + ' (post-hydration).');
+        }
+      });
+      scout.observe(document.body, { childList: true, subtree: true });
     } else {
       console.log('[impeccable] Resumed active variant session ' + currentSessionId + ' (' + arrivedVariants + '/' + expectedVariants + ' variants).');
     }

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

@@ -88,10 +88,15 @@ Output (JSON):
       const absFile = path.resolve(process.cwd(), relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
       const content = fs.readFileSync(absFile, 'utf-8');
-      const updated = removeTag(content, config.commentSyntax);
+      const detagged = removeTag(content, config.commentSyntax);
+      const updated = revertCspMeta(detagged);
       if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
       fs.writeFileSync(absFile, updated, 'utf-8');
-      return { file: relFile, removed: true };
+      return {
+        file: relFile,
+        removed: detagged !== content,
+        cspReverted: updated !== detagged,
+      };
     });
     console.log(JSON.stringify({ ok: true, results }));
     return;
@@ -109,11 +114,18 @@ Output (JSON):
     const absFile = path.resolve(process.cwd(), relFile);
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
-    const withoutOld = removeTag(content, config.commentSyntax);
-    const updated = insertTag(withoutOld, config, port);
-    if (updated === withoutOld) return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
+    const withTag = insertTag(withoutOld, config, port);
+    if (withTag === withoutOld) {
+      return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    }
+    const updated = patchCspMeta(withTag, port);
     fs.writeFileSync(absFile, updated, 'utf-8');
-    return { file: relFile, inserted: true };
+    return {
+      file: relFile,
+      inserted: true,
+      cspPatched: updated !== withTag,
+    };
   });
   const anyInserted = results.some((r) => r.inserted);
   console.log(JSON.stringify({ ok: anyInserted, port, results }));
@@ -296,6 +308,130 @@ function removeTag(content, _syntax) {
   return content;
 }
 
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // 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);
+  }
+  return result;
+}
+
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-execute
 // ---------------------------------------------------------------------------
@@ -306,3 +442,4 @@ if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs
 }
 
 export { insertTag, removeTag, validateConfig, buildTagBlock };
+// patchCspMeta + revertCspMeta are exported above where they're defined.

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

@@ -8,7 +8,7 @@
  *   npx impeccable poll --reply <id> error "msg" # Reply with error
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -146,13 +146,12 @@ 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());

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

@@ -21,11 +21,16 @@ 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';
 
 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 / DESIGN.json live wherever load-context.mjs resolves.
+// Keeps live-server in sync with the loader when users keep the docs in
+// .agents/context/, docs/, or a path set via IMPECCABLE_CONTEXT_DIR.
+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
 
@@ -113,7 +118,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 +136,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 +160,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 +169,7 @@ 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 'exit':
       return null;
     case 'prefetch':
@@ -315,8 +330,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 = path.join(CONTEXT_DIR, 'DESIGN.json');
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 

.claude/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,17 +120,67 @@ 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;
@@ -133,17 +188,48 @@ The agent should insert variant HTML at insertLine.`);
   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,13 +249,24 @@ 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,
     originalLineCount: originalLines.length,
@@ -310,6 +407,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 +443,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

.claude/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 / DESIGN.json 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;

.cursor/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.0
+version: 3.0.5
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 ---
 
@@ -9,11 +9,30 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 ## Setup (non-optional)
 
-Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .cursor/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. |
+
+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.
 
 ### 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.
@@ -24,13 +43,13 @@ Load both in one call:
 node .cursor/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.
 
-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 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.
 
 If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed.
 
@@ -103,7 +122,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
 
@@ -143,6 +165,8 @@ Plus two management commands — `pin <command>` and `unpin <command>`, detailed
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
 ## Pin / Unpin
 
 **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

.cursor/skills/impeccable/reference/animate.md

@@ -122,7 +122,8 @@ Use appropriate techniques for each animation:
 /* Prefer for simple, declarative animations */
 - transitions for state changes
 - @keyframes for complex sequences
-- transform + opacity only (GPU-accelerated)
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
 ```
 
 ### JavaScript Animation
@@ -134,9 +135,10 @@ Use appropriate techniques for each animation:
 ```
 
 ### Performance
-- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - **will-change**: Add sparingly for known expensive animations
-- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
 ### Accessibility
@@ -152,7 +154,7 @@ Use appropriate techniques for each animation:
 
 **NEVER**:
 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
-- Animate layout properties (width, height, top, left)—use transform instead
+- 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

.cursor/skills/impeccable/reference/audit.md

@@ -22,7 +22,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 **Check for**:
 - **Layout thrashing**: Reading/writing layout properties in loops
-- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
 - **Bundle size**: Unnecessary imports, unused dependencies
 - **Render performance**: Unnecessary re-renders, missing memoization

.cursor/skills/impeccable/reference/brand.md

@@ -29,6 +29,16 @@ 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:

.cursor/skills/impeccable/reference/craft.md

@@ -1,12 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful.
+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 Gate
+
+Craft cannot build until all of these are true:
+
+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.
+
+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.
+
+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.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+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.
+
+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."
 
 ## Step 1: Shape the Design
 
 Run /impeccable shape, passing along whatever feature description the user provided.
 
-Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+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.
+
+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 has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
 
@@ -24,15 +53,17 @@ 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: North Star Mock (Capability-Gated)
+## Step 3: Land the Visual Direction (Capability-Gated)
 
-Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+Before implementation, generate high-fidelity visual comps when all of these are true:
 
 - 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.
 
-When those conditions are met, this step is the default for **both brand and product work**.
+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.
+
+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
 
@@ -40,25 +71,43 @@ Use the mock step to find a stronger visual lane than code-first generation woul
 
 ### What to generate
 
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+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.
 
-### After generation
+### Approval loop
 
-Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+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
 
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
 
-## Step 4: Asset Extraction (Optional)
+### 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.
 
@@ -74,53 +123,71 @@ Good candidates:
 - 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.
+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
+## Step 5: Build to Production Quality
 
-Implement the feature following the design brief. Work in this order:
+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.
 
-1. **Structure first**: HTML/semantic structure for the primary state. No styling yet.
-2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy.
-3. **Typography and color**: Apply the type scale and color system.
-4. **Interactive states**: Hover, focus, active, disabled.
-5. **Edge case states**: Empty, loading, error, overflow, first-run.
-6. **Motion**: Purposeful transitions and animations (if appropriate).
-7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context.
+### Production bar
 
-### During Build
-- Test with real (or realistic) data at every step, not placeholder text
-- Check each state as you build it, not all at the end
-- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief or the chosen north-star direction
-- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
-- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
+- 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.
 
-## Step 6: Visual Iteration
+## Step 6: Browser-Based Iteration
 
 **This step is critical.** Do not stop after the first implementation pass.
 
-Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback.
+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.
 
-Iterate through these checks visually:
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+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.
+
+### 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 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.
-3. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink?
-6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing.
+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.
 
-After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
+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
 
 Present the result to the user:
 - Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
 - Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
+- 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.

.cursor/skills/impeccable/reference/live.md

@@ -29,7 +29,7 @@ Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodi
 node .cursor/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).
 
@@ -74,7 +74,7 @@ Reading annotations precisely:
 ### 2. Wrap the element
 
 ```bash
-node .cursor/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div"
+node .cursor/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`:
@@ -82,9 +82,12 @@ 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.
 
+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.
+
 Output on success: `{ file, insertLine, commentSyntax }`.
 
 **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:
@@ -101,38 +104,81 @@ 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. **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?)
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+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, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+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 primary axes, not three riffs on color.
+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.
 
-**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.
+**Departure mode.** Each variant anchors to a different **aesthetic lane**, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+- Tech-minimal (Stripe / Linear / Vercel-restraint)
+- Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)
+- Terminal-native (actual code surface, syntax-highlighted UI as the design)
+- Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)
+- Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)
+- Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)
+- Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)
 
-> 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.
+Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. *Editorial-typographic is currently a reflex-reject lane* — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.
 
-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.
+#### 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: *editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal*. If any two variants share a family label, rework. *This pass is non-negotiable in departure mode and catches the editorial-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:
 
@@ -150,7 +196,13 @@ If two of them rhyme ("both use big type" / "both are stacks of sections" / "bot
 
 ### 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
 
@@ -181,6 +233,25 @@ The first variant has no `display: none` (visible by default). All others do. If
 
 One edit, all variants — the browser's MutationObserver picks everything up in one pass.
 
+**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 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)
 
 Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
@@ -246,6 +317,16 @@ node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --fil
 
 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 .cursor/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.

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

@@ -38,9 +38,19 @@ Timing matters more than easing. These durations feel right for most UI:
 
 **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.
 
-## The Only Two Properties You Should Animate
+## Premium Motion Materials
 
-**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties: blur reveals, backdrop-filter panels, saturation or brightness shifts, shadow bloom, SVG filters, masks, clip paths, gradient-position movement, and variable font or shader-driven effects.
+
+Use the right material for the effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography.
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances, atmospheric transitions.
+- **Clip path / masks**: wipes, reveals, editorial cropping, product-like transitions.
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state.
+- **Grid-template rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly.
+
+The hard rule is not "transform and opacity only." The hard rule is: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify in-browser that the result is smooth on the target viewports. If blur/filter makes the interaction feel significantly more premium and remains smooth, use it.
 
 ## Staggered Animations
 

.cursor/skills/impeccable/reference/optimize.md

@@ -109,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 

.cursor/skills/impeccable/reference/polish.md

@@ -4,17 +4,17 @@ Perform a meticulous final pass to catch all the small details that separate goo
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+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: color tokens, spacing scale, typography styles, component API.
-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?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+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.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+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
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -22,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+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
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - 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.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -50,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+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.
+- **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.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -89,7 +104,7 @@ Every interactive element needs all states:
 
 - **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.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **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`
 
@@ -158,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -183,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- 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)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 

.cursor/skills/impeccable/reference/shape.md

@@ -12,7 +12,18 @@ Most AI-generated UIs fail not because of bad code, but because of skipped think
 
 **Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
 
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+
+### 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.
+
+- 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.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -63,7 +74,11 @@ After the discovery interview, generate a small set of visual direction probes *
 - 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.
 
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
+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.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
 
 ### What to generate
 
@@ -89,11 +104,11 @@ 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 and proceed directly to the design brief.
+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.
 
 ## Phase 2: Design Brief
 
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
+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.
 
 ### Brief Structure
 
@@ -131,6 +146,6 @@ Anything unresolved that the implementer should resolve during build.
 
 ---
 
-ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
+ask the user directly 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.
 
 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.)

.cursor/skills/impeccable/reference/teach.md

@@ -21,11 +21,13 @@ 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 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**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Both exist**: ask the user directly 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.
 
 Never silently overwrite an existing file. Always confirm first.
 
+If teach was invoked as a setup blocker by another command, such as `/impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
 ## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
@@ -48,7 +50,22 @@ Note what you've learned and what remains unclear. This exploration feeds both P
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase.
+ask the user directly to clarify what you cannot infer. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- 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.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+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)
 
@@ -56,7 +73,7 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 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), ask the user directly to clarify what you cannot infer. which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+If the signal is genuinely split (e.g. a product with a big marketing landing), ask the user directly 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.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
@@ -79,6 +96,8 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
 Synthesize into a strategic document:
 
 ```markdown
@@ -134,4 +153,4 @@ Summarize:
 
 If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
 
-Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .cursorrules for easier agent reference. If yes, append a short **Design Context** pointer section there.
+Optionally ask the user directly to clarify what you cannot infer. Ask whether they'd like a brief summary of PRODUCT.md appended to .cursorrules for easier agent reference. If yes, append a short **Design Context** pointer section there.

.cursor/skills/impeccable/scripts/command-metadata.json

@@ -1,10 +1,10 @@
 {
   "craft": {
-    "description": "Full shape-then-build flow with visual iteration. Plans the UX with /impeccable shape, loads the right reference files, then builds and iterates visually until the result is delightful. Use when building a new feature end-to-end.",
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
     "argumentHint": ""
   },
   "document": {
@@ -84,7 +84,7 @@
     "argumentHint": "[target]"
   },
   "shape": {
-    "description": "Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written.",
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
     "argumentHint": "[feature to shape]"
   },
   "typeset": {

.cursor/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);
@@ -150,12 +163,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
 
   if (cssContent) {
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
-    replacement.push(indent + '<style data-impeccable-css="' + id + '">');
+    // 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.
+    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
     // Re-indent CSS content to match
     for (const cssLine of cssContent) {
       replacement.push(indent + cssLine.trimStart());
     }
-    replacement.push(indent + '</style>');
+    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
     if (paramValues && Object.keys(paramValues).length > 0) {
       // Preserve the user's knob positions for the carbonize-cleanup agent
       // to bake into the final CSS when it collapses scoped rules.
@@ -169,8 +184,13 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // in a data-impeccable-variant="N" div with `display: contents` (so layout
   // isn't affected). The carbonize agent strips this attribute + wrapper when
   // it moves the CSS to a proper stylesheet.
+  //
+  // Style attribute syntax has to follow the host file's flavor — JSX files
+  // 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) {
-    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" style="display: contents">');
+    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
     replacement.push(indent + '</div>');
   } else {
@@ -178,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');
 
@@ -209,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:
@@ -336,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;
@@ -344,12 +430,69 @@ function extractCss(lines, block, id) {
     }
 
     if (inStyle) {
-      if (line.trimStart().startsWith('</style>')) break;
+      // Detect </style> anywhere on the line — JSX template-literal closes
+      // (`}</style>`) put the close mid-line, and we don't want to absorb the
+      // template-literal punctuation as CSS content.
+      const closeIdx = line.indexOf('</style>');
+      if (closeIdx !== -1) break;
       content.push(line);
     }
   }
 
-  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') : '';
 }
 
 /**

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

@@ -197,6 +197,45 @@
 
   function id8() { return crypto.randomUUID().replace(/-/g, '').slice(0, 8); }
 
+  // Modal-aware chrome: keep our floating UI clickable inside Radix /
+  // Headless UI / vaul portals.
+  //
+  // Two host-page behaviors break us when the picked element lives inside a
+  // modal dialog:
+  //
+  //   1. Modal scroll-lock disables outside pointer events. Radix's
+  //      `DismissableLayer` sets `document.body.style.pointerEvents = 'none'`
+  //      while a modal is open and only restores `auto` on the layer. Our
+  //      chrome inherits `none` from <body> and becomes unclickable.
+  //   2. The dialog's outside-interaction handler (Radix's
+  //      `usePointerDownOutside`) listens at document level and dismisses
+  //      the dialog whenever a `pointerdown` lands outside the layer node.
+  //      Our chrome is a sibling of <body>, so Radix classifies our clicks
+  //      as outside and tears the dialog down mid-task.
+  //
+  // We can't reliably re-parent our chrome into the dialog subtree (z-index
+  // stacking, scroll containers, theming all become host-page concerns), so
+  // we defang both behaviors at our root:
+  //
+  //   - `pointer-events: auto !important` overrides the inherited `none`.
+  //   - Stop `pointerdown` / `mousedown` propagation so the document-level
+  //     dismiss listener never fires for our clicks.
+  //   - Stop `focusin` propagation so any focus shifts inside our chrome
+  //     don't read as "focus moved outside the dialog" to focus traps.
+  //
+  // Click events still bubble normally — only the early pointer/focus
+  // signals that drive outside-interaction detection are silenced.
+  function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+    if (!rootEl) return;
+    if (setPointerEvents) {
+      rootEl.style.setProperty('pointer-events', 'auto', 'important');
+    }
+    const stop = (e) => e.stopPropagation();
+    rootEl.addEventListener('pointerdown', stop);
+    rootEl.addEventListener('mousedown', stop);
+    rootEl.addEventListener('focusin', stop);
+  }
+
   // ---------------------------------------------------------------------------
   // Highlight overlay
   // ---------------------------------------------------------------------------
@@ -336,6 +375,11 @@
     annotOverlayEl.addEventListener('pointerup', onAnnotUp);
     annotOverlayEl.addEventListener('pointercancel', onAnnotUp);
     document.body.appendChild(annotOverlayEl);
+    // Modal-host friendliness: pointer-events is already 'auto' on this
+    // overlay; we only need to silence the host's outside-interaction
+    // listeners. Don't override pointer-events here (the overlay toggles
+    // visibility via display:none, which is fine).
+    defangOutsideHandlers(annotOverlayEl, { setPointerEvents: false });
   }
 
   function updateClearChip() {
@@ -811,6 +855,7 @@
       maxWidth: '520px', minWidth: '320px',
     });
     document.body.appendChild(barEl);
+    defangOutsideHandlers(barEl);
   }
 
   function positionBar() {
@@ -905,7 +950,12 @@
     pill.addEventListener('click', (e) => { e.stopPropagation(); toggleActionPicker(); });
     row.appendChild(pill);
 
-    // Freeform input
+    // Freeform input. Focus state shows an accent-colored border only —
+    // an earlier version tinted the background with `BP.accentSoft`, which
+    // composited against the dark bar surface to a murky purple where the
+    // browser's default placeholder gray was unreadable. Placeholder color
+    // is set explicitly via a one-shot stylesheet keyed off this input's id
+    // so it picks up the bar's `textDim` token in both themes.
     const input = document.createElement('input');
     input.id = PREFIX + '-input';
     input.type = 'text';
@@ -916,15 +966,20 @@
       border: '1px solid transparent', background: 'transparent',
       fontFamily: FONT, fontSize: '12px', color: BP.text,
       outline: 'none',
-      transition: 'border-color 0.15s ease, background 0.15s ease',
+      transition: 'border-color 0.15s ease',
     });
+    if (!document.getElementById(PREFIX + '-input-style')) {
+      const s = document.createElement('style');
+      s.id = PREFIX + '-input-style';
+      s.textContent =
+        '#' + PREFIX + '-input::placeholder { color: ' + BP.textDim + '; opacity: 1; }';
+      document.head.appendChild(s);
+    }
     input.addEventListener('focus', () => {
-      input.style.borderColor = BP.hairline;
-      input.style.background = BP.accentSoft;
+      input.style.borderColor = BP.accent;
     });
     input.addEventListener('blur', () => {
       input.style.borderColor = 'transparent';
-      input.style.background = 'transparent';
     });
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') { e.stopPropagation(); e.preventDefault(); handleGo(); return; }
@@ -1320,6 +1375,7 @@
 
     pickerEl.appendChild(grid);
     document.body.appendChild(pickerEl);
+    defangOutsideHandlers(pickerEl);
 
     // Cache the palette on the picker so toggleActionPicker's state refresh
     // uses the same theme-aware colors when it repaints chips.
@@ -1433,6 +1489,10 @@
 
     paramsPanelEl.appendChild(paramsPanelBody);
     document.body.appendChild(paramsPanelEl);
+    // Don't override pointer-events: the panel toggles between 'none' (closed,
+    // click-through) and 'auto' (open) on its own. Just silence the host's
+    // outside-interaction listeners while the panel is open.
+    defangOutsideHandlers(paramsPanelEl, { setPointerEvents: false });
     paramsPanelInner = paramsPanelEl; // compatibility alias for the rest of the code
   }
 
@@ -2011,7 +2071,16 @@
       for (const m of mutations) {
         if (m.target.closest?.('[data-impeccable-variants]')) { dominated = true; break; }
         for (const n of m.addedNodes) {
-          if (n.nodeType === 1 && (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant)) {
+          if (n.nodeType !== 1) continue;
+          // Direct hit: the added node itself is the wrapper or a variant.
+          if (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant) {
+            dominated = true; break;
+          }
+          // Subtree hit: framework HMR (notably SvelteKit) sometimes replaces
+          // a whole subtree where the wrapper is a descendant of the added
+          // node. Without this check, the observer ignores those mutations
+          // and the session stays in GENERATING forever.
+          if (n.querySelector?.('[data-impeccable-variants],[data-impeccable-variant]')) {
             dominated = true; break;
           }
         }
@@ -2126,17 +2195,20 @@
             }
             break;
           }
-          // HMR didn't propagate in time. Give it a 2s grace window, then
-          // reload the page. resumeSession counts variants off the rendered
-          // DOM on load and transitions straight to CYCLING — reload is the
-          // one universal recovery path: HTML, JSX/TSX, Vue, Svelte, static
-          // servers, anything. We used to try DOMParser on the raw source,
-          // but JSX expressions aren't valid HTML and the parse fails.
+          // Variants are in source but not in the DOM yet. Common when the
+          // picked element lived inside conditional render (closed modal,
+          // hidden tab, a route the user navigated away from). The variant
+          // MutationObserver stays armed and auto-transitions to CYCLING
+          // the moment the wrapper actually mounts. Nudge the user toward
+          // that path with a toast — better than the prior force-reload
+          // which reset framework state and left the session stuck.
           setTimeout(() => {
             if (arrivedVariants >= expectedVariants && expectedVariants > 0) return;
             if (state !== 'GENERATING') return;
-            saveSession();
-            window.location.reload();
+            showToast(
+              "Variants ready. If the picked element isn't visible, retrace the path that revealed it — they'll appear automatically.",
+              15000,
+            );
           }, 2000);
           break;
         case 'error':
@@ -2236,6 +2308,60 @@
     showBar('configure');
     startScrollTracking();
     maybePrefetchPage();
+    maybeWarnConditionalAncestor(selectedElement);
+  }
+
+  /**
+   * Surface a brief, non-blocking heads-up when the picked element lives
+   * inside a container whose visibility is gated by ephemeral state — modals,
+   * collapsible panels, popovers, off-screen tab panels. If HMR remounts the
+   * parent during generation (Vite Fast Refresh, SvelteKit page reload), the
+   * variants land in source but stay invisible until the user re-opens the
+   * container. Telling the user upfront is much friendlier than the silent
+   * timeout-then-toast that they'd otherwise hit.
+   *
+   * Heuristic, intentionally narrow — only fires for unambiguous cases so
+   * we don't cry wolf on every nested element.
+   */
+  function maybeWarnConditionalAncestor(el) {
+    let node = el?.parentElement;
+    let depth = 0;
+    while (node && depth < 12) {
+      // 1. Active dialog / modal
+      if (node.getAttribute && node.getAttribute('role') === 'dialog'
+          && node.getAttribute('aria-modal') === 'true') {
+        showToast('Heads up: this element lives inside a dialog. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 2. Common Radix / shadcn / headless-ui open-state attribute
+      if (node.dataset && node.dataset.state === 'open') {
+        showToast('Heads up: this element lives inside an open panel. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 3. Tab panel — only meaningful when the page also shows ANOTHER
+      // tab as selected. A single tabpanel with no tablist is just a static
+      // section in disguise and isn't conditional.
+      if (node.getAttribute && node.getAttribute('role') === 'tabpanel') {
+        const list = document.querySelector('[role="tablist"]');
+        if (list) {
+          const tabs = list.querySelectorAll('[role="tab"]');
+          if (tabs.length > 1) {
+            showToast('Heads up: this element lives in a tab panel. If state resets during generation, switch back to this tab.', 6000);
+            return;
+          }
+        }
+      }
+      // 4. Collapsible: aria-expanded sibling. Look for the trigger button.
+      if (node.id) {
+        const trigger = document.querySelector(`[aria-controls="${CSS.escape(node.id)}"][aria-expanded="true"]`);
+        if (trigger) {
+          showToast('Heads up: this element lives inside an expandable section. If state resets during generation, re-expand it.', 6000);
+          return;
+        }
+      }
+      node = node.parentElement;
+      depth++;
+    }
   }
 
   // Fire a lightweight prefetch event the first time the user selects an
@@ -2496,11 +2622,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
@@ -2694,7 +2824,13 @@ void main() {
       const img = document.createElement('img');
       img.src = URL.createObjectURL(blob);
       img.id = PREFIX + '-shader';
-      Object.assign(img.style, canvas.style, { outline: '2px dashed ' + C.brand, outlineOffset: '-2px' });
+      // Copy positioning via cssText. Object.assign across CSSStyleDeclaration
+      // throws in modern Chromium because the source's indexed properties
+      // (style[0], [1], ...) are read-only and the engine forbids writing
+      // them on the destination.
+      img.style.cssText = canvas.style.cssText;
+      img.style.outline = '2px dashed ' + C.brand;
+      img.style.outlineOffset = '-2px';
       document.body.appendChild(img);
       shaderState = { canvas: img, gl: null, program: null, texture: null, rafId: 0, startTime: 0 };
       return;
@@ -2942,8 +3078,16 @@ void main() {
 
   function showToast(message, duration) {
     if (toastEl) toastEl.remove();
+    // Stack the toast above the global bar (which sits at bottom:14px) so
+    // the two never overlap. Read the bar's actual rect — its height varies
+    // with hover-expanded labels — and fall back to a sensible default
+    // when the bar isn't mounted yet.
+    const barRect = globalBarEl?.getBoundingClientRect();
+    const barTopFromBottom = barRect && barRect.height > 0
+      ? Math.max(16, window.innerHeight - barRect.top + 12)
+      : 16;
     toastEl = el('div', {
-      position: 'fixed', bottom: '16px', left: '50%',
+      position: 'fixed', bottom: barTopFromBottom + 'px', left: '50%',
       transform: 'translateX(-50%) translateY(8px)',
       background: C.ink, color: C.white,
       fontFamily: FONT, fontSize: '12px',
@@ -3066,13 +3210,33 @@ void main() {
       // page bg. Used for screenshots and theme QA.
       const override = localStorage.getItem('impeccable-dev-theme');
       if (override === 'light' || override === 'dark') return override;
-      const bg = getComputedStyle(document.body).backgroundColor
-        || getComputedStyle(document.documentElement).backgroundColor;
-      const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-      if (!m) return 'light';
-      const [, r, g, b] = m;
+
+      // Walk body → html, taking the first opaque background. The browser's
+      // default body / html background is `rgba(0, 0, 0, 0)`, which a naive
+      // regex would read as black and mislabel a perfectly white page as
+      // dark. Honoring alpha avoids that — and falling through to <html>
+      // catches the common pattern of a bg only on <html> (or only on body).
+      function readOpaque(el) {
+        if (!el) return null;
+        const bg = getComputedStyle(el).backgroundColor;
+        const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/);
+        if (!m) return null;
+        const alpha = m[4] == null ? 1 : parseFloat(m[4]);
+        if (alpha < 0.5) return null; // transparent / nearly transparent → skip
+        return [+m[1], +m[2], +m[3]];
+      }
+
+      const rgb = readOpaque(document.body) || readOpaque(document.documentElement);
+      // Both transparent → fall back to the browser's effective canvas color.
+      // White is the universal default; only one in a thousand sites swaps it
+      // via `color-scheme: dark` on <html>, and `prefers-color-scheme` lets
+      // us catch that case.
+      if (!rgb) {
+        return matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      const [r, g, b] = rgb;
       // Perceptual luminance (Rec. 709)
-      const L = (0.2126 * +r + 0.7152 * +g + 0.0722 * +b) / 255;
+      const L = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
       return L > 0.55 ? 'light' : 'dark';
     } catch { return 'light'; }
   }
@@ -3275,15 +3439,24 @@ void main() {
     });
     inner.appendChild(divider);
 
-    // Exit (subtle × on the right) — SVG for baseline-free centering
+    // Exit × on the right — intentionally subtle (textDim at rest, text on
+    // hover) so it sits behind the active toggles in visual hierarchy.
+    //
+    // Explicit padding + box-sizing here is load-bearing: a host page like
+    // `button { padding: 0.5rem 1rem; }` (very common in resets) would
+    // otherwise inflate this 24x24 button into 56x40 and push the SVG out
+    // of the visible bar — the X stays invisible even though the styles in
+    // DevTools look fine. Every other chrome button sets padding inline;
+    // this one needed it too.
     const exitBtn = el('button', {
       display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
-      width: '26px', height: '26px', borderRadius: '6px',
+      padding: '0', boxSizing: 'border-box',
+      width: '24px', height: '24px', borderRadius: '6px',
       border: 'none', background: 'transparent',
       color: P.textDim, fontFamily: FONT, fontSize: '0', lineHeight: '0',
       cursor: 'pointer', transition: 'color 0.12s ease, background 0.12s ease',
     });
-    exitBtn.innerHTML = '<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="2.5" y1="2.5" x2="9.5" y2="9.5"/><line x1="9.5" y1="2.5" x2="2.5" y2="9.5"/></svg>';
+    exitBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><line x1="3" y1="3" x2="11" y2="11"/><line x1="11" y1="3" x2="3" y2="11"/></svg>';
     exitBtn.title = 'Exit live mode';
     exitBtn.addEventListener('mouseenter', () => { exitBtn.style.color = P.text; exitBtn.style.background = P.exitHover; });
     exitBtn.addEventListener('mouseleave', () => { exitBtn.style.color = P.textDim; exitBtn.style.background = 'transparent'; });
@@ -3301,6 +3474,7 @@ void main() {
     });
 
     document.body.appendChild(globalBarEl);
+    defangOutsideHandlers(globalBarEl);
 
     requestAnimationFrame(() => {
       globalBarEl.style.opacity = '1';
@@ -3513,6 +3687,11 @@ void main() {
     designShadow.appendChild(root);
 
     document.body.appendChild(designHost);
+    // The host is pointer-events: none; the panel inside the shadow DOM
+    // manages its own auto/none. Events bubble through the shadow boundary,
+    // so attaching here silences host-page outside-interaction handlers
+    // without touching the host's click-through behavior.
+    defangOutsideHandlers(designHost, { setPointerEvents: false });
 
     loadDesignPrefs();
     renderDesignChrome();
@@ -4577,6 +4756,18 @@ void main() {
     // Check for an active session to resume (variant wrapper already in DOM after HMR)
     if (!resumeSession()) {
       console.log('[impeccable] Live variant mode ready. Hover over elements to pick one.');
+      // SvelteKit (and any framework that hydrates after HTML parse) may add
+      // the variant wrapper AFTER init runs. Watch for it and retry resume
+      // once it appears. Disconnect on first hit.
+      const scout = new MutationObserver(() => {
+        const wrapper = document.querySelector('[data-impeccable-variants]');
+        if (!wrapper) return;
+        scout.disconnect();
+        if (resumeSession()) {
+          console.log('[impeccable] Resumed deferred session ' + currentSessionId + ' (post-hydration).');
+        }
+      });
+      scout.observe(document.body, { childList: true, subtree: true });
     } else {
       console.log('[impeccable] Resumed active variant session ' + currentSessionId + ' (' + arrivedVariants + '/' + expectedVariants + ' variants).');
     }

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

@@ -88,10 +88,15 @@ Output (JSON):
       const absFile = path.resolve(process.cwd(), relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
       const content = fs.readFileSync(absFile, 'utf-8');
-      const updated = removeTag(content, config.commentSyntax);
+      const detagged = removeTag(content, config.commentSyntax);
+      const updated = revertCspMeta(detagged);
       if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
       fs.writeFileSync(absFile, updated, 'utf-8');
-      return { file: relFile, removed: true };
+      return {
+        file: relFile,
+        removed: detagged !== content,
+        cspReverted: updated !== detagged,
+      };
     });
     console.log(JSON.stringify({ ok: true, results }));
     return;
@@ -109,11 +114,18 @@ Output (JSON):
     const absFile = path.resolve(process.cwd(), relFile);
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
-    const withoutOld = removeTag(content, config.commentSyntax);
-    const updated = insertTag(withoutOld, config, port);
-    if (updated === withoutOld) return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
+    const withTag = insertTag(withoutOld, config, port);
+    if (withTag === withoutOld) {
+      return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    }
+    const updated = patchCspMeta(withTag, port);
     fs.writeFileSync(absFile, updated, 'utf-8');
-    return { file: relFile, inserted: true };
+    return {
+      file: relFile,
+      inserted: true,
+      cspPatched: updated !== withTag,
+    };
   });
   const anyInserted = results.some((r) => r.inserted);
   console.log(JSON.stringify({ ok: anyInserted, port, results }));
@@ -296,6 +308,130 @@ function removeTag(content, _syntax) {
   return content;
 }
 
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // 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);
+  }
+  return result;
+}
+
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-execute
 // ---------------------------------------------------------------------------
@@ -306,3 +442,4 @@ if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs
 }
 
 export { insertTag, removeTag, validateConfig, buildTagBlock };
+// patchCspMeta + revertCspMeta are exported above where they're defined.

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

@@ -8,7 +8,7 @@
  *   npx impeccable poll --reply <id> error "msg" # Reply with error
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -146,13 +146,12 @@ 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());

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

@@ -21,11 +21,16 @@ 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';
 
 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 / DESIGN.json live wherever load-context.mjs resolves.
+// Keeps live-server in sync with the loader when users keep the docs in
+// .agents/context/, docs/, or a path set via IMPECCABLE_CONTEXT_DIR.
+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
 
@@ -113,7 +118,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 +136,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 +160,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 +169,7 @@ 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 'exit':
       return null;
     case 'prefetch':
@@ -315,8 +330,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 = path.join(CONTEXT_DIR, 'DESIGN.json');
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 

.cursor/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,17 +120,67 @@ 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;
@@ -133,17 +188,48 @@ The agent should insert variant HTML at insertLine.`);
   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,13 +249,24 @@ 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,
     originalLineCount: originalLines.length,
@@ -310,6 +407,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 +443,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

.cursor/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 / DESIGN.json 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;

.gemini/skills/impeccable/SKILL.md

@@ -1,18 +1,37 @@
 ---
 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.0
+version: 3.0.5
 ---
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
 
 ## Setup (non-optional)
 
-Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .gemini/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. |
+
+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.
 
 ### 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.
@@ -23,13 +42,13 @@ Load both in one call:
 node .gemini/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.
 
-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 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.
 
 If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed.
 
@@ -102,7 +121,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
 
@@ -142,6 +164,8 @@ Plus two management commands — `pin <command>` and `unpin <command>`, detailed
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
 ## Pin / Unpin
 
 **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

.gemini/skills/impeccable/reference/animate.md

@@ -122,7 +122,8 @@ Use appropriate techniques for each animation:
 /* Prefer for simple, declarative animations */
 - transitions for state changes
 - @keyframes for complex sequences
-- transform + opacity only (GPU-accelerated)
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
 ```
 
 ### JavaScript Animation
@@ -134,9 +135,10 @@ Use appropriate techniques for each animation:
 ```
 
 ### Performance
-- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - **will-change**: Add sparingly for known expensive animations
-- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
 ### Accessibility
@@ -152,7 +154,7 @@ Use appropriate techniques for each animation:
 
 **NEVER**:
 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
-- Animate layout properties (width, height, top, left)—use transform instead
+- 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

.gemini/skills/impeccable/reference/audit.md

@@ -22,7 +22,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 **Check for**:
 - **Layout thrashing**: Reading/writing layout properties in loops
-- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
 - **Bundle size**: Unnecessary imports, unused dependencies
 - **Render performance**: Unnecessary re-renders, missing memoization

.gemini/skills/impeccable/reference/brand.md

@@ -29,6 +29,16 @@ 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:

.gemini/skills/impeccable/reference/craft.md

@@ -1,12 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful.
+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 Gate
+
+Craft cannot build until all of these are true:
+
+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.
+
+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.
+
+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.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+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.
+
+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."
 
 ## Step 1: Shape the Design
 
 Run /impeccable shape, passing along whatever feature description the user provided.
 
-Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+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.
+
+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 has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
 
@@ -24,15 +53,17 @@ 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: North Star Mock (Capability-Gated)
+## Step 3: Land the Visual Direction (Capability-Gated)
 
-Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+Before implementation, generate high-fidelity visual comps when all of these are true:
 
 - 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.
 
-When those conditions are met, this step is the default for **both brand and product work**.
+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.
+
+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
 
@@ -40,25 +71,43 @@ Use the mock step to find a stronger visual lane than code-first generation woul
 
 ### What to generate
 
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+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.
 
-### After generation
+### Approval loop
 
-Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+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
 
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
 
-## Step 4: Asset Extraction (Optional)
+### 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.
 
@@ -74,53 +123,71 @@ Good candidates:
 - 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.
+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
+## Step 5: Build to Production Quality
 
-Implement the feature following the design brief. Work in this order:
+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.
 
-1. **Structure first**: HTML/semantic structure for the primary state. No styling yet.
-2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy.
-3. **Typography and color**: Apply the type scale and color system.
-4. **Interactive states**: Hover, focus, active, disabled.
-5. **Edge case states**: Empty, loading, error, overflow, first-run.
-6. **Motion**: Purposeful transitions and animations (if appropriate).
-7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context.
+### Production bar
 
-### During Build
-- Test with real (or realistic) data at every step, not placeholder text
-- Check each state as you build it, not all at the end
-- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief or the chosen north-star direction
-- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
-- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
+- 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.
 
-## Step 6: Visual Iteration
+## Step 6: Browser-Based Iteration
 
 **This step is critical.** Do not stop after the first implementation pass.
 
-Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback.
+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.
 
-Iterate through these checks visually:
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+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.
+
+### 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 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.
-3. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink?
-6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing.
+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.
 
-After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
+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
 
 Present the result to the user:
 - Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
 - Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
+- 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.

.gemini/skills/impeccable/reference/live.md

@@ -29,7 +29,7 @@ Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodi
 node .gemini/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).
 
@@ -74,7 +74,7 @@ Reading annotations precisely:
 ### 2. Wrap the element
 
 ```bash
-node .gemini/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div"
+node .gemini/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`:
@@ -82,9 +82,12 @@ 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.
 
+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.
+
 Output on success: `{ file, insertLine, commentSyntax }`.
 
 **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:
@@ -101,38 +104,81 @@ 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. **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?)
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+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, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+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 primary axes, not three riffs on color.
+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.
 
-**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.
+**Departure mode.** Each variant anchors to a different **aesthetic lane**, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+- Tech-minimal (Stripe / Linear / Vercel-restraint)
+- Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)
+- Terminal-native (actual code surface, syntax-highlighted UI as the design)
+- Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)
+- Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)
+- Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)
+- Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)
 
-> 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.
+Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. *Editorial-typographic is currently a reflex-reject lane* — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.
 
-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.
+#### 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: *editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal*. If any two variants share a family label, rework. *This pass is non-negotiable in departure mode and catches the editorial-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:
 
@@ -150,7 +196,13 @@ If two of them rhyme ("both use big type" / "both are stacks of sections" / "bot
 
 ### 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
 
@@ -181,6 +233,25 @@ The first variant has no `display: none` (visible by default). All others do. If
 
 One edit, all variants — the browser's MutationObserver picks everything up in one pass.
 
+**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 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)
 
 Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
@@ -246,6 +317,16 @@ node .gemini/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --fil
 
 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 .gemini/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.

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

@@ -38,9 +38,19 @@ Timing matters more than easing. These durations feel right for most UI:
 
 **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.
 
-## The Only Two Properties You Should Animate
+## Premium Motion Materials
 
-**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties: blur reveals, backdrop-filter panels, saturation or brightness shifts, shadow bloom, SVG filters, masks, clip paths, gradient-position movement, and variable font or shader-driven effects.
+
+Use the right material for the effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography.
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances, atmospheric transitions.
+- **Clip path / masks**: wipes, reveals, editorial cropping, product-like transitions.
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state.
+- **Grid-template rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly.
+
+The hard rule is not "transform and opacity only." The hard rule is: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify in-browser that the result is smooth on the target viewports. If blur/filter makes the interaction feel significantly more premium and remains smooth, use it.
 
 ## Staggered Animations
 

.gemini/skills/impeccable/reference/optimize.md

@@ -109,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 

.gemini/skills/impeccable/reference/polish.md

@@ -4,17 +4,17 @@ Perform a meticulous final pass to catch all the small details that separate goo
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+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: color tokens, spacing scale, typography styles, component API.
-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?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+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.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+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
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -22,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+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
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - 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.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -50,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+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.
+- **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.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -89,7 +104,7 @@ Every interactive element needs all states:
 
 - **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.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **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`
 
@@ -158,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -183,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- 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)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 

.gemini/skills/impeccable/reference/shape.md

@@ -12,7 +12,18 @@ Most AI-generated UIs fail not because of bad code, but because of skipped think
 
 **Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
 
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+
+### 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.
+
+- 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.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -63,7 +74,11 @@ After the discovery interview, generate a small set of visual direction probes *
 - 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.
 
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
+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.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
 
 ### What to generate
 
@@ -89,11 +104,11 @@ 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 and proceed directly to the design brief.
+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.
 
 ## Phase 2: Design Brief
 
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
+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.
 
 ### Brief Structure
 
@@ -131,6 +146,6 @@ Anything unresolved that the implementer should resolve during build.
 
 ---
 
-ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
+ask the user directly 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.
 
 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.)

.gemini/skills/impeccable/reference/teach.md

@@ -21,11 +21,13 @@ 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 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**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Both exist**: ask the user directly 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.
 
 Never silently overwrite an existing file. Always confirm first.
 
+If teach was invoked as a setup blocker by another command, such as `/impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
 ## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
@@ -48,7 +50,22 @@ Note what you've learned and what remains unclear. This exploration feeds both P
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase.
+ask the user directly to clarify what you cannot infer. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- 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.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+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)
 
@@ -56,7 +73,7 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 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), ask the user directly to clarify what you cannot infer. which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+If the signal is genuinely split (e.g. a product with a big marketing landing), ask the user directly 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.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
@@ -79,6 +96,8 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
 Synthesize into a strategic document:
 
 ```markdown
@@ -134,4 +153,4 @@ Summarize:
 
 If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
 
-Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to GEMINI.md for easier agent reference. If yes, append a short **Design Context** pointer section there.
+Optionally ask the user directly to clarify what you cannot infer. Ask whether they'd like a brief summary of PRODUCT.md appended to GEMINI.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.gemini/skills/impeccable/scripts/command-metadata.json

@@ -1,10 +1,10 @@
 {
   "craft": {
-    "description": "Full shape-then-build flow with visual iteration. Plans the UX with /impeccable shape, loads the right reference files, then builds and iterates visually until the result is delightful. Use when building a new feature end-to-end.",
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
     "argumentHint": ""
   },
   "document": {
@@ -84,7 +84,7 @@
     "argumentHint": "[target]"
   },
   "shape": {
-    "description": "Plan the UX and UI for a feature before writing code. Runs a structured discovery interview, then produces a design brief that guides implementation. Use during the planning phase to establish design direction, constraints, and strategy before any code is written.",
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
     "argumentHint": "[feature to shape]"
   },
   "typeset": {

.gemini/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);
@@ -150,12 +163,14 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
 
   if (cssContent) {
     replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
-    replacement.push(indent + '<style data-impeccable-css="' + id + '">');
+    // 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.
+    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
     // Re-indent CSS content to match
     for (const cssLine of cssContent) {
       replacement.push(indent + cssLine.trimStart());
     }
-    replacement.push(indent + '</style>');
+    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
     if (paramValues && Object.keys(paramValues).length > 0) {
       // Preserve the user's knob positions for the carbonize-cleanup agent
       // to bake into the final CSS when it collapses scoped rules.
@@ -169,8 +184,13 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   // in a data-impeccable-variant="N" div with `display: contents` (so layout
   // isn't affected). The carbonize agent strips this attribute + wrapper when
   // it moves the CSS to a proper stylesheet.
+  //
+  // Style attribute syntax has to follow the host file's flavor — JSX files
+  // 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) {
-    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" style="display: contents">');
+    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
     replacement.push(...restored);
     replacement.push(indent + '</div>');
   } else {
@@ -178,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');
 
@@ -209,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:
@@ -336,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;
@@ -344,12 +430,69 @@ function extractCss(lines, block, id) {
     }
 
     if (inStyle) {
-      if (line.trimStart().startsWith('</style>')) break;
+      // Detect </style> anywhere on the line — JSX template-literal closes
+      // (`}</style>`) put the close mid-line, and we don't want to absorb the
+      // template-literal punctuation as CSS content.
+      const closeIdx = line.indexOf('</style>');
+      if (closeIdx !== -1) break;
       content.push(line);
     }
   }
 
-  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') : '';
 }
 
 /**

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

@@ -197,6 +197,45 @@
 
   function id8() { return crypto.randomUUID().replace(/-/g, '').slice(0, 8); }
 
+  // Modal-aware chrome: keep our floating UI clickable inside Radix /
+  // Headless UI / vaul portals.
+  //
+  // Two host-page behaviors break us when the picked element lives inside a
+  // modal dialog:
+  //
+  //   1. Modal scroll-lock disables outside pointer events. Radix's
+  //      `DismissableLayer` sets `document.body.style.pointerEvents = 'none'`
+  //      while a modal is open and only restores `auto` on the layer. Our
+  //      chrome inherits `none` from <body> and becomes unclickable.
+  //   2. The dialog's outside-interaction handler (Radix's
+  //      `usePointerDownOutside`) listens at document level and dismisses
+  //      the dialog whenever a `pointerdown` lands outside the layer node.
+  //      Our chrome is a sibling of <body>, so Radix classifies our clicks
+  //      as outside and tears the dialog down mid-task.
+  //
+  // We can't reliably re-parent our chrome into the dialog subtree (z-index
+  // stacking, scroll containers, theming all become host-page concerns), so
+  // we defang both behaviors at our root:
+  //
+  //   - `pointer-events: auto !important` overrides the inherited `none`.
+  //   - Stop `pointerdown` / `mousedown` propagation so the document-level
+  //     dismiss listener never fires for our clicks.
+  //   - Stop `focusin` propagation so any focus shifts inside our chrome
+  //     don't read as "focus moved outside the dialog" to focus traps.
+  //
+  // Click events still bubble normally — only the early pointer/focus
+  // signals that drive outside-interaction detection are silenced.
+  function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+    if (!rootEl) return;
+    if (setPointerEvents) {
+      rootEl.style.setProperty('pointer-events', 'auto', 'important');
+    }
+    const stop = (e) => e.stopPropagation();
+    rootEl.addEventListener('pointerdown', stop);
+    rootEl.addEventListener('mousedown', stop);
+    rootEl.addEventListener('focusin', stop);
+  }
+
   // ---------------------------------------------------------------------------
   // Highlight overlay
   // ---------------------------------------------------------------------------
@@ -336,6 +375,11 @@
     annotOverlayEl.addEventListener('pointerup', onAnnotUp);
     annotOverlayEl.addEventListener('pointercancel', onAnnotUp);
     document.body.appendChild(annotOverlayEl);
+    // Modal-host friendliness: pointer-events is already 'auto' on this
+    // overlay; we only need to silence the host's outside-interaction
+    // listeners. Don't override pointer-events here (the overlay toggles
+    // visibility via display:none, which is fine).
+    defangOutsideHandlers(annotOverlayEl, { setPointerEvents: false });
   }
 
   function updateClearChip() {
@@ -811,6 +855,7 @@
       maxWidth: '520px', minWidth: '320px',
     });
     document.body.appendChild(barEl);
+    defangOutsideHandlers(barEl);
   }
 
   function positionBar() {
@@ -905,7 +950,12 @@
     pill.addEventListener('click', (e) => { e.stopPropagation(); toggleActionPicker(); });
     row.appendChild(pill);
 
-    // Freeform input
+    // Freeform input. Focus state shows an accent-colored border only —
+    // an earlier version tinted the background with `BP.accentSoft`, which
+    // composited against the dark bar surface to a murky purple where the
+    // browser's default placeholder gray was unreadable. Placeholder color
+    // is set explicitly via a one-shot stylesheet keyed off this input's id
+    // so it picks up the bar's `textDim` token in both themes.
     const input = document.createElement('input');
     input.id = PREFIX + '-input';
     input.type = 'text';
@@ -916,15 +966,20 @@
       border: '1px solid transparent', background: 'transparent',
       fontFamily: FONT, fontSize: '12px', color: BP.text,
       outline: 'none',
-      transition: 'border-color 0.15s ease, background 0.15s ease',
+      transition: 'border-color 0.15s ease',
     });
+    if (!document.getElementById(PREFIX + '-input-style')) {
+      const s = document.createElement('style');
+      s.id = PREFIX + '-input-style';
+      s.textContent =
+        '#' + PREFIX + '-input::placeholder { color: ' + BP.textDim + '; opacity: 1; }';
+      document.head.appendChild(s);
+    }
     input.addEventListener('focus', () => {
-      input.style.borderColor = BP.hairline;
-      input.style.background = BP.accentSoft;
+      input.style.borderColor = BP.accent;
     });
     input.addEventListener('blur', () => {
       input.style.borderColor = 'transparent';
-      input.style.background = 'transparent';
     });
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') { e.stopPropagation(); e.preventDefault(); handleGo(); return; }
@@ -1320,6 +1375,7 @@
 
     pickerEl.appendChild(grid);
     document.body.appendChild(pickerEl);
+    defangOutsideHandlers(pickerEl);
 
     // Cache the palette on the picker so toggleActionPicker's state refresh
     // uses the same theme-aware colors when it repaints chips.
@@ -1433,6 +1489,10 @@
 
     paramsPanelEl.appendChild(paramsPanelBody);
     document.body.appendChild(paramsPanelEl);
+    // Don't override pointer-events: the panel toggles between 'none' (closed,
+    // click-through) and 'auto' (open) on its own. Just silence the host's
+    // outside-interaction listeners while the panel is open.
+    defangOutsideHandlers(paramsPanelEl, { setPointerEvents: false });
     paramsPanelInner = paramsPanelEl; // compatibility alias for the rest of the code
   }
 
@@ -2011,7 +2071,16 @@
       for (const m of mutations) {
         if (m.target.closest?.('[data-impeccable-variants]')) { dominated = true; break; }
         for (const n of m.addedNodes) {
-          if (n.nodeType === 1 && (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant)) {
+          if (n.nodeType !== 1) continue;
+          // Direct hit: the added node itself is the wrapper or a variant.
+          if (n.dataset?.impeccableVariants || n.dataset?.impeccableVariant) {
+            dominated = true; break;
+          }
+          // Subtree hit: framework HMR (notably SvelteKit) sometimes replaces
+          // a whole subtree where the wrapper is a descendant of the added
+          // node. Without this check, the observer ignores those mutations
+          // and the session stays in GENERATING forever.
+          if (n.querySelector?.('[data-impeccable-variants],[data-impeccable-variant]')) {
             dominated = true; break;
           }
         }
@@ -2126,17 +2195,20 @@
             }
             break;
           }
-          // HMR didn't propagate in time. Give it a 2s grace window, then
-          // reload the page. resumeSession counts variants off the rendered
-          // DOM on load and transitions straight to CYCLING — reload is the
-          // one universal recovery path: HTML, JSX/TSX, Vue, Svelte, static
-          // servers, anything. We used to try DOMParser on the raw source,
-          // but JSX expressions aren't valid HTML and the parse fails.
+          // Variants are in source but not in the DOM yet. Common when the
+          // picked element lived inside conditional render (closed modal,
+          // hidden tab, a route the user navigated away from). The variant
+          // MutationObserver stays armed and auto-transitions to CYCLING
+          // the moment the wrapper actually mounts. Nudge the user toward
+          // that path with a toast — better than the prior force-reload
+          // which reset framework state and left the session stuck.
           setTimeout(() => {
             if (arrivedVariants >= expectedVariants && expectedVariants > 0) return;
             if (state !== 'GENERATING') return;
-            saveSession();
-            window.location.reload();
+            showToast(
+              "Variants ready. If the picked element isn't visible, retrace the path that revealed it — they'll appear automatically.",
+              15000,
+            );
           }, 2000);
           break;
         case 'error':
@@ -2236,6 +2308,60 @@
     showBar('configure');
     startScrollTracking();
     maybePrefetchPage();
+    maybeWarnConditionalAncestor(selectedElement);
+  }
+
+  /**
+   * Surface a brief, non-blocking heads-up when the picked element lives
+   * inside a container whose visibility is gated by ephemeral state — modals,
+   * collapsible panels, popovers, off-screen tab panels. If HMR remounts the
+   * parent during generation (Vite Fast Refresh, SvelteKit page reload), the
+   * variants land in source but stay invisible until the user re-opens the
+   * container. Telling the user upfront is much friendlier than the silent
+   * timeout-then-toast that they'd otherwise hit.
+   *
+   * Heuristic, intentionally narrow — only fires for unambiguous cases so
+   * we don't cry wolf on every nested element.
+   */
+  function maybeWarnConditionalAncestor(el) {
+    let node = el?.parentElement;
+    let depth = 0;
+    while (node && depth < 12) {
+      // 1. Active dialog / modal
+      if (node.getAttribute && node.getAttribute('role') === 'dialog'
+          && node.getAttribute('aria-modal') === 'true') {
+        showToast('Heads up: this element lives inside a dialog. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 2. Common Radix / shadcn / headless-ui open-state attribute
+      if (node.dataset && node.dataset.state === 'open') {
+        showToast('Heads up: this element lives inside an open panel. If state resets during generation, you may need to re-open it.', 6000);
+        return;
+      }
+      // 3. Tab panel — only meaningful when the page also shows ANOTHER
+      // tab as selected. A single tabpanel with no tablist is just a static
+      // section in disguise and isn't conditional.
+      if (node.getAttribute && node.getAttribute('role') === 'tabpanel') {
+        const list = document.querySelector('[role="tablist"]');
+        if (list) {
+          const tabs = list.querySelectorAll('[role="tab"]');
+          if (tabs.length > 1) {
+            showToast('Heads up: this element lives in a tab panel. If state resets during generation, switch back to this tab.', 6000);
+            return;
+          }
+        }
+      }
+      // 4. Collapsible: aria-expanded sibling. Look for the trigger button.
+      if (node.id) {
+        const trigger = document.querySelector(`[aria-controls="${CSS.escape(node.id)}"][aria-expanded="true"]`);
+        if (trigger) {
+          showToast('Heads up: this element lives inside an expandable section. If state resets during generation, re-expand it.', 6000);
+          return;
+        }
+      }
+      node = node.parentElement;
+      depth++;
+    }
   }
 
   // Fire a lightweight prefetch event the first time the user selects an
@@ -2496,11 +2622,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
@@ -2694,7 +2824,13 @@ void main() {
       const img = document.createElement('img');
       img.src = URL.createObjectURL(blob);
       img.id = PREFIX + '-shader';
-      Object.assign(img.style, canvas.style, { outline: '2px dashed ' + C.brand, outlineOffset: '-2px' });
+      // Copy positioning via cssText. Object.assign across CSSStyleDeclaration
+      // throws in modern Chromium because the source's indexed properties
+      // (style[0], [1], ...) are read-only and the engine forbids writing
+      // them on the destination.
+      img.style.cssText = canvas.style.cssText;
+      img.style.outline = '2px dashed ' + C.brand;
+      img.style.outlineOffset = '-2px';
       document.body.appendChild(img);
       shaderState = { canvas: img, gl: null, program: null, texture: null, rafId: 0, startTime: 0 };
       return;
@@ -2942,8 +3078,16 @@ void main() {
 
   function showToast(message, duration) {
     if (toastEl) toastEl.remove();
+    // Stack the toast above the global bar (which sits at bottom:14px) so
+    // the two never overlap. Read the bar's actual rect — its height varies
+    // with hover-expanded labels — and fall back to a sensible default
+    // when the bar isn't mounted yet.
+    const barRect = globalBarEl?.getBoundingClientRect();
+    const barTopFromBottom = barRect && barRect.height > 0
+      ? Math.max(16, window.innerHeight - barRect.top + 12)
+      : 16;
     toastEl = el('div', {
-      position: 'fixed', bottom: '16px', left: '50%',
+      position: 'fixed', bottom: barTopFromBottom + 'px', left: '50%',
       transform: 'translateX(-50%) translateY(8px)',
       background: C.ink, color: C.white,
       fontFamily: FONT, fontSize: '12px',
@@ -3066,13 +3210,33 @@ void main() {
       // page bg. Used for screenshots and theme QA.
       const override = localStorage.getItem('impeccable-dev-theme');
       if (override === 'light' || override === 'dark') return override;
-      const bg = getComputedStyle(document.body).backgroundColor
-        || getComputedStyle(document.documentElement).backgroundColor;
-      const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
-      if (!m) return 'light';
-      const [, r, g, b] = m;
+
+      // Walk body → html, taking the first opaque background. The browser's
+      // default body / html background is `rgba(0, 0, 0, 0)`, which a naive
+      // regex would read as black and mislabel a perfectly white page as
+      // dark. Honoring alpha avoids that — and falling through to <html>
+      // catches the common pattern of a bg only on <html> (or only on body).
+      function readOpaque(el) {
+        if (!el) return null;
+        const bg = getComputedStyle(el).backgroundColor;
+        const m = bg.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/);
+        if (!m) return null;
+        const alpha = m[4] == null ? 1 : parseFloat(m[4]);
+        if (alpha < 0.5) return null; // transparent / nearly transparent → skip
+        return [+m[1], +m[2], +m[3]];
+      }
+
+      const rgb = readOpaque(document.body) || readOpaque(document.documentElement);
+      // Both transparent → fall back to the browser's effective canvas color.
+      // White is the universal default; only one in a thousand sites swaps it
+      // via `color-scheme: dark` on <html>, and `prefers-color-scheme` lets
+      // us catch that case.
+      if (!rgb) {
+        return matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+      }
+      const [r, g, b] = rgb;
       // Perceptual luminance (Rec. 709)
-      const L = (0.2126 * +r + 0.7152 * +g + 0.0722 * +b) / 255;
+      const L = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
       return L > 0.55 ? 'light' : 'dark';
     } catch { return 'light'; }
   }
@@ -3275,15 +3439,24 @@ void main() {
     });
     inner.appendChild(divider);
 
-    // Exit (subtle × on the right) — SVG for baseline-free centering
+    // Exit × on the right — intentionally subtle (textDim at rest, text on
+    // hover) so it sits behind the active toggles in visual hierarchy.
+    //
+    // Explicit padding + box-sizing here is load-bearing: a host page like
+    // `button { padding: 0.5rem 1rem; }` (very common in resets) would
+    // otherwise inflate this 24x24 button into 56x40 and push the SVG out
+    // of the visible bar — the X stays invisible even though the styles in
+    // DevTools look fine. Every other chrome button sets padding inline;
+    // this one needed it too.
     const exitBtn = el('button', {
       display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
-      width: '26px', height: '26px', borderRadius: '6px',
+      padding: '0', boxSizing: 'border-box',
+      width: '24px', height: '24px', borderRadius: '6px',
       border: 'none', background: 'transparent',
       color: P.textDim, fontFamily: FONT, fontSize: '0', lineHeight: '0',
       cursor: 'pointer', transition: 'color 0.12s ease, background 0.12s ease',
     });
-    exitBtn.innerHTML = '<svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="2.5" y1="2.5" x2="9.5" y2="9.5"/><line x1="9.5" y1="2.5" x2="2.5" y2="9.5"/></svg>';
+    exitBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><line x1="3" y1="3" x2="11" y2="11"/><line x1="11" y1="3" x2="3" y2="11"/></svg>';
     exitBtn.title = 'Exit live mode';
     exitBtn.addEventListener('mouseenter', () => { exitBtn.style.color = P.text; exitBtn.style.background = P.exitHover; });
     exitBtn.addEventListener('mouseleave', () => { exitBtn.style.color = P.textDim; exitBtn.style.background = 'transparent'; });
@@ -3301,6 +3474,7 @@ void main() {
     });
 
     document.body.appendChild(globalBarEl);
+    defangOutsideHandlers(globalBarEl);
 
     requestAnimationFrame(() => {
       globalBarEl.style.opacity = '1';
@@ -3513,6 +3687,11 @@ void main() {
     designShadow.appendChild(root);
 
     document.body.appendChild(designHost);
+    // The host is pointer-events: none; the panel inside the shadow DOM
+    // manages its own auto/none. Events bubble through the shadow boundary,
+    // so attaching here silences host-page outside-interaction handlers
+    // without touching the host's click-through behavior.
+    defangOutsideHandlers(designHost, { setPointerEvents: false });
 
     loadDesignPrefs();
     renderDesignChrome();
@@ -4577,6 +4756,18 @@ void main() {
     // Check for an active session to resume (variant wrapper already in DOM after HMR)
     if (!resumeSession()) {
       console.log('[impeccable] Live variant mode ready. Hover over elements to pick one.');
+      // SvelteKit (and any framework that hydrates after HTML parse) may add
+      // the variant wrapper AFTER init runs. Watch for it and retry resume
+      // once it appears. Disconnect on first hit.
+      const scout = new MutationObserver(() => {
+        const wrapper = document.querySelector('[data-impeccable-variants]');
+        if (!wrapper) return;
+        scout.disconnect();
+        if (resumeSession()) {
+          console.log('[impeccable] Resumed deferred session ' + currentSessionId + ' (post-hydration).');
+        }
+      });
+      scout.observe(document.body, { childList: true, subtree: true });
     } else {
       console.log('[impeccable] Resumed active variant session ' + currentSessionId + ' (' + arrivedVariants + '/' + expectedVariants + ' variants).');
     }

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

@@ -88,10 +88,15 @@ Output (JSON):
       const absFile = path.resolve(process.cwd(), relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
       const content = fs.readFileSync(absFile, 'utf-8');
-      const updated = removeTag(content, config.commentSyntax);
+      const detagged = removeTag(content, config.commentSyntax);
+      const updated = revertCspMeta(detagged);
       if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
       fs.writeFileSync(absFile, updated, 'utf-8');
-      return { file: relFile, removed: true };
+      return {
+        file: relFile,
+        removed: detagged !== content,
+        cspReverted: updated !== detagged,
+      };
     });
     console.log(JSON.stringify({ ok: true, results }));
     return;
@@ -109,11 +114,18 @@ Output (JSON):
     const absFile = path.resolve(process.cwd(), relFile);
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
-    const withoutOld = removeTag(content, config.commentSyntax);
-    const updated = insertTag(withoutOld, config, port);
-    if (updated === withoutOld) return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
+    const withTag = insertTag(withoutOld, config, port);
+    if (withTag === withoutOld) {
+      return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    }
+    const updated = patchCspMeta(withTag, port);
     fs.writeFileSync(absFile, updated, 'utf-8');
-    return { file: relFile, inserted: true };
+    return {
+      file: relFile,
+      inserted: true,
+      cspPatched: updated !== withTag,
+    };
   });
   const anyInserted = results.some((r) => r.inserted);
   console.log(JSON.stringify({ ok: anyInserted, port, results }));
@@ -296,6 +308,130 @@ function removeTag(content, _syntax) {
   return content;
 }
 
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // 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);
+  }
+  return result;
+}
+
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-execute
 // ---------------------------------------------------------------------------
@@ -306,3 +442,4 @@ if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs
 }
 
 export { insertTag, removeTag, validateConfig, buildTagBlock };
+// patchCspMeta + revertCspMeta are exported above where they're defined.

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

@@ -8,7 +8,7 @@
  *   npx impeccable poll --reply <id> error "msg" # Reply with error
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -146,13 +146,12 @@ 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());

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

@@ -21,11 +21,16 @@ 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';
 
 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 / DESIGN.json live wherever load-context.mjs resolves.
+// Keeps live-server in sync with the loader when users keep the docs in
+// .agents/context/, docs/, or a path set via IMPECCABLE_CONTEXT_DIR.
+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
 
@@ -113,7 +118,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 +136,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 +160,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 +169,7 @@ 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 'exit':
       return null;
     case 'prefetch':
@@ -315,8 +330,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 = path.join(CONTEXT_DIR, 'DESIGN.json');
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 

.gemini/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,17 +120,67 @@ 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;
@@ -133,17 +188,48 @@ The agent should insert variant HTML at insertLine.`);
   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,13 +249,24 @@ 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,
     originalLineCount: originalLines.length,
@@ -310,6 +407,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 +443,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

.gemini/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 / DESIGN.json 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;

.github/ISSUE_TEMPLATE/feature_request.md

@@ -23,6 +23,7 @@ assignees: ''
 - [ ] VS Code Copilot
 - [ ] Kiro
 - [ ] OpenCode
+- [ ] Qoder
 - [ ] All providers
 
 ## Alternatives considered

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,5 +17,5 @@
 - [ ] Source files updated in `source/`
 - [ ] `bun run build` ran successfully
 - [ ] `bun test` passes
-- [ ] Tested with at least one provider (Cursor / Claude Code / Gemini CLI / Codex / Copilot / Kiro / OpenCode)
+- [ ] Tested with at least one provider (Cursor / Claude Code / Gemini CLI / Codex / Copilot / Kiro / OpenCode / Qoder)
 - [ ] README / DEVELOP.md updated if needed

.github/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.0
+version: 3.0.5
 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,11 +11,30 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 ## Setup (non-optional)
 
-Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .github/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. |
+
+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.
 
 ### 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.
@@ -26,13 +45,13 @@ Load both in one call:
 node .github/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.
 
-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 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.
 
 If DESIGN.md is missing: nudge once per session (*"Run `/impeccable document` for more on-brand output"*), then proceed.
 
@@ -105,7 +124,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
 
@@ -145,6 +167,8 @@ Plus two management commands — `pin <command>` and `unpin <command>`, detailed
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
 ## Pin / Unpin
 
 **Pin** creates a standalone shortcut so `/<command>` invokes `/impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

.github/skills/impeccable/reference/animate.md

@@ -122,7 +122,8 @@ Use appropriate techniques for each animation:
 /* Prefer for simple, declarative animations */
 - transitions for state changes
 - @keyframes for complex sequences
-- transform + opacity only (GPU-accelerated)
+- transform and opacity for reliable movement
+- blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth
 ```
 
 ### JavaScript Animation
@@ -134,9 +135,10 @@ Use appropriate techniques for each animation:
 ```
 
 ### Performance
-- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
+- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
+- **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - **will-change**: Add sparingly for known expensive animations
-- **Reduce paint**: Minimize repaints, use `contain` where appropriate
+- **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
 ### Accessibility
@@ -152,7 +154,7 @@ Use appropriate techniques for each animation:
 
 **NEVER**:
 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
-- Animate layout properties (width, height, top, left)—use transform instead
+- 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

.github/skills/impeccable/reference/audit.md

@@ -22,7 +22,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 **Check for**:
 - **Layout thrashing**: Reading/writing layout properties in loops
-- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
 - **Bundle size**: Unnecessary imports, unused dependencies
 - **Render performance**: Unnecessary re-renders, missing memoization

.github/skills/impeccable/reference/brand.md

@@ -29,6 +29,16 @@ 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:

.github/skills/impeccable/reference/craft.md

@@ -1,12 +1,41 @@
 # Craft Flow
 
-Build a feature with impeccable UX and UI quality through a structured process: shape the design, load the right references, then build and iterate visually until the result is delightful.
+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 Gate
+
+Craft cannot build until all of these are true:
+
+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.
+
+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.
+
+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.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+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.
+
+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."
 
 ## Step 1: Shape the Design
 
 Run /impeccable shape, passing along whatever feature description the user provided.
 
-Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+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.
+
+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 has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
 
@@ -24,15 +53,17 @@ 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: North Star Mock (Capability-Gated)
+## Step 3: Land the Visual Direction (Capability-Gated)
 
-Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+Before implementation, generate high-fidelity visual comps when all of these are true:
 
 - 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.
 
-When those conditions are met, this step is the default for **both brand and product work**.
+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.
+
+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
 
@@ -40,25 +71,43 @@ Use the mock step to find a stronger visual lane than code-first generation woul
 
 ### What to generate
 
-Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+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.
 
-### After generation
+### Approval loop
 
-Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+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
 
-Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
 
-## Step 4: Asset Extraction (Optional)
+### 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.
 
@@ -74,53 +123,71 @@ Good candidates:
 - 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.
+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
+## Step 5: Build to Production Quality
 
-Implement the feature following the design brief. Work in this order:
+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.
 
-1. **Structure first**: HTML/semantic structure for the primary state. No styling yet.
-2. **Layout and spacing**: Establish the spatial rhythm and visual hierarchy.
-3. **Typography and color**: Apply the type scale and color system.
-4. **Interactive states**: Hover, focus, active, disabled.
-5. **Edge case states**: Empty, loading, error, overflow, first-run.
-6. **Motion**: Purposeful transitions and animations (if appropriate).
-7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context.
+### Production bar
 
-### During Build
-- Test with real (or realistic) data at every step, not placeholder text
-- Check each state as you build it, not all at the end
-- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief or the chosen north-star direction
-- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
-- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
+- 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.
 
-## Step 6: Visual Iteration
+## Step 6: Browser-Based Iteration
 
 **This step is critical.** Do not stop after the first implementation pass.
 
-Open the result in a browser window. If browser automation tools are available, use them to navigate to the page and visually inspect the result. If not, ask the user to open it and provide feedback.
+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.
 
-Iterate through these checks visually:
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+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.
+
+### 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 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.
-3. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
-4. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
-5. **Check responsive.** Resize the viewport. Does it adapt well or just shrink?
-6. **Check the details.** Spacing consistency, type hierarchy clarity, color contrast, interactive feedback, motion timing.
+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.
 
-After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
+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
 
 Present the result to the user:
 - Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
 - Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
+- 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.

.github/skills/impeccable/reference/live.md

@@ -29,7 +29,7 @@ Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodi
 node .github/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).
 
@@ -74,7 +74,7 @@ Reading annotations precisely:
 ### 2. Wrap the element
 
 ```bash
-node .github/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div"
+node .github/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`:
@@ -82,9 +82,12 @@ 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.
 
+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.
+
 Output on success: `{ file, insertLine, commentSyntax }`.
 
 **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:
@@ -101,38 +104,81 @@ 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. **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?)
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+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, scale ratio, case/weight strategy
-4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+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 primary axes, not three riffs on color.
+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.
 
-**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.
+**Departure mode.** Each variant anchors to a different **aesthetic lane**, drawn from non-monoculture options. Lanes (illustrative, not exhaustive):
 
-**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+- Tech-minimal (Stripe / Linear / Vercel-restraint)
+- Brutalist-utility (system fonts, raw HTML defaults, Craigslist-energy)
+- Terminal-native (actual code surface, syntax-highlighted UI as the design)
+- Industrial-signage (dimensional type, arrow systems, ISO standards, wayfinding)
+- Technical-drawing (isometric line art, callout numbers, blueprint blue, exploded-view diagrams)
+- Drenched-saturated (Liquid Death / Mailchimp full-palette / single-hue commitment)
+- Swiss-grid-rigorous (visible grid as voice, tight type, accumulated systems)
 
-> 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.
+Avoid the **reflex-reject lanes** in [brand.md](brand.md). Don't trade one monoculture for another. *Editorial-typographic is currently a reflex-reject lane* — three variants that all read as "magazine cover" is the second-order training reflex, the trap one tier deeper than SaaS-cream.
 
-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.
+#### 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: *editorial / brutalist / terminal / signage / drenched / swiss / technical-drawing / tech-minimal*. If any two variants share a family label, rework. *This pass is non-negotiable in departure mode and catches the editorial-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:
 
@@ -150,7 +196,13 @@ If two of them rhyme ("both use big type" / "both are stacks of sections" / "bot
 
 ### 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
 
@@ -181,6 +233,25 @@ The first variant has no `display: none` (visible by default). All others do. If
 
 One edit, all variants — the browser's MutationObserver picks everything up in one pass.
 
+**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 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)
 
 Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
@@ -246,6 +317,16 @@ node .github/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --fil
 
 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 .github/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.

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

@@ -38,9 +38,19 @@ Timing matters more than easing. These durations feel right for most UI:
 
 **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.
 
-## The Only Two Properties You Should Animate
+## Premium Motion Materials
 
-**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties: blur reveals, backdrop-filter panels, saturation or brightness shifts, shadow bloom, SVG filters, masks, clip paths, gradient-position movement, and variable font or shader-driven effects.
+
+Use the right material for the effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography.
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances, atmospheric transitions.
+- **Clip path / masks**: wipes, reveals, editorial cropping, product-like transitions.
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state.
+- **Grid-template rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly.
+
+The hard rule is not "transform and opacity only." The hard rule is: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify in-browser that the result is smooth on the target viewports. If blur/filter makes the interaction feel significantly more premium and remains smooth, use it.
 
 ## Staggered Animations
 

.github/skills/impeccable/reference/optimize.md

@@ -109,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 

.github/skills/impeccable/reference/polish.md

@@ -4,17 +4,17 @@ Perform a meticulous final pass to catch all the small details that separate goo
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+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: color tokens, spacing scale, typography styles, component API.
-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?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+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.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+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
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -22,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+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
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - 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.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -50,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+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.
+- **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.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -89,7 +104,7 @@ Every interactive element needs all states:
 
 - **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.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **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`
 
@@ -158,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -183,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- 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)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 

.github/skills/impeccable/reference/shape.md

@@ -12,7 +12,18 @@ Most AI-generated UIs fail not because of bad code, but because of skipped think
 
 **Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
 
-Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer.
+
+### 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.
+
+- 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.
 
 ### Purpose & Context
 - What is this feature for? What problem does it solve?
@@ -63,7 +74,11 @@ After the discovery interview, generate a small set of visual direction probes *
 - 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.
 
-When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief.
+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.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
 
 ### What to generate
 
@@ -89,11 +104,11 @@ 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 and proceed directly to the design brief.
+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.
 
 ## Phase 2: Design Brief
 
-After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete.
+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.
 
 ### Brief Structure
 
@@ -131,6 +146,6 @@ Anything unresolved that the implementer should resolve during build.
 
 ---
 
-ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
+ask the user directly 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.
 
 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.)