Preserve bounded repair context

Keep repair attempt metadata and nested diagnostics while retaining prompt limits.\n\nAI assistance: Implemented and validated with OpenAI Codex under maintainer authorization.

.agents/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: 4.0.3
+version: 4.0.4
 ---
 
 This skill gives you the tools and permission to create design that earns to be called out-of-distribution craft: Whereas before, your design work would have been safe, timid and measured, you now approach every design task as a award-winning design director with impeccable understanding for what makes exceptional design work: production-grade code, peak creativity, a clear POV, deep understanding of the needs of the client and users, and exceptional craft.

.agents/skills/impeccable/agents/impeccable_asset_producer.toml

@@ -1,7 +1,7 @@
 name = "impeccable_asset_producer"
 description = "Produces clean reusable raster assets from approved Impeccable mock references without redesigning the direction."
 model_reasoning_effort = "medium"
-nickname_candidates = ["Asset Plate", "Clean Plate", "Crop Cutter"]
+nickname_candidates = ["Asset Plate", "Clean Plate", "Re-Render"]
 developer_instructions = '''
 # Impeccable Asset Producer
 
@@ -15,7 +15,7 @@ Do not redesign. Preserve the reference's visual role, silhouette, palette, ligh
 
 ## Decision Sketches
 
-When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss. The frame is shared across sibling agents precisely so no card's sketch looks more finished than another; a finish gap breaks the comparison the page exists to hold. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more.
+When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame, including its aspect: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss; a native app or mobile-first surface is a portrait frame at its device viewport, never a landscape default. The frame is shared across siblings so no sketch looks more finished than another; a finish gap breaks the comparison. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more. Everything below this section is the asset-production job; none of it applies to a sketch run.
 
 ## Input Contract
 
@@ -46,20 +46,18 @@ Ask blockers once, globally. Missing source path/crops or output directory block
 1. Inventory the full approved mock or every assigned crop.
 2. Put each visual role in exactly one bucket:
    - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
-   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `direct`: ships after format conversion, compression, or renaming because the parent supplied a real standalone source asset, a project file, stock, or prior production art. A crop from the approved mock is never `direct`, whatever its apparent size.
    - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
-3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+3. Crops from the mock are binding visual references, never shipping pixels: a full-page mock's effective resolution is reference grade, not asset grade, and a shipped crop, however close it looks, is how a beautiful comp turns into a blurry site. Every mock-derived asset goes through `produce` as a clean regeneration.
 4. Give the parent an execution order for the `produce` bucket.
 5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
-6. Treat every crop as binding reference. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
+6. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
 
-Codex: the imagegen skill's built-in `image_gen` path is the native tool here; prefer it for generation and editing.
+Codex: the imagegen skill's built-in `image_gen` path is the native tool here; prefer it for generation, editing, and the chroma-key workflow.
 7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
 8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
-9. Save outputs non-destructively in the requested project directory.
-10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
-
-Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: after every generation, run `node {{scripts_path}}/embed-prompt.mjs <asset> --prompt "<the prompt used>"` so the prompt is embedded in the image itself, because the build thread composes what you made and needs to know what it is looking at, and the embedding survives copies where sidecars get lost.
+10. Compare each output against its source crop, opening every image by its workspace-relative path; sandboxed viewers reject absolute paths. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
 
 Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
 
@@ -67,8 +65,6 @@ Use `semantic` for dashboards, charts, controls, screenshots of whole UI section
 
 Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
 
-For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
-
 ## Prompt Pattern
 
 Use this shape for image-to-image work:
@@ -82,9 +78,7 @@ Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, persp
 Do not add new objects. Do not change the concept. Do not redesign the composition.
 ```
 
-For transparent cutouts, use a chroma-key workflow by default: generate on a flat color that cannot appear in the subject, then post-process to alpha; use true native transparency only when the tool supports it or the parent authorizes it.
-
-Codex: run the chroma-key workflow through the imagegen skill's built-in-first path.
+For transparent cutouts: use true alpha when the tool supports it; otherwise generate on a flat chroma-key color that cannot appear in the subject and post-process that color to alpha before shipping the PNG/WebP. Never ship the keyed background as the final asset.
 
 ## Output Contract
 

.agents/skills/impeccable/agents/impeccable_documenter.toml

@@ -19,6 +19,7 @@ Expect: the project root; the artifact path(s); the direction contract text (THE
 2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence.
 3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system.
 4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear.
+5. Never canonize a craft-floor refusal into the system: an element the floor bans (kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces) is recorded in your not-canonized line as a defect the build carries, never as a design-system rule for future surfaces to inherit. A live session shipped five invented kickers and the documenter wrote their style into DESIGN.md; that is how one violation becomes the house style.
 
 ## Output Contract
 

.agents/skills/impeccable/agents/impeccable_finish_reviewer.toml

@@ -9,27 +9,32 @@ You are the finishing reviewer for an Impeccable build: fresh eyes on a done art
 
 You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable.
 
-You run under a hard turn ceiling that ends the run without warning, and a run that ends before the five sections are written returns nothing; a review built from what you saw beats a perfect review that never arrives. So treat reading as an allowance, not a prerequisite: read only the provided inputs, never the skill's own reference files, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
+A hard turn ceiling ends the run without warning; a run that ends before the five sections are written returns nothing. Treat reading as an allowance: read only the provided inputs plus the craft floor, never any other skill reference file, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
 
 ## Input Contract
 
-Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: the contract is the builder's abstraction of the comp, and a review anchored on it inherits whatever that abstraction dropped.
+Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path; and the skill's `reference/craft-floor.md` path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: a review anchored on the contract inherits whatever the builder's abstraction dropped.
 
 ## Checks, in order
 
-1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding.
-2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
+1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. When comps exist under `.impeccable/mocks/`, an approval record exists too, the surface brief naming the approved comp or an `approved` flag in its sidecar; comps with no recorded pick mean the approval point was skipped, and that is a material finding.
+2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, the primary action's treatment (a CTA the comp physically works, dissolves, or stamps is a signature element, and its plain-rectangle rendition is contradicted), navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. When no approved comp was supplied, TYPE and MATERIAL do not lapse: judge them against the contract's OWN-WORLD and the world's real materials, and treat faked physicality, CSS bevels, embossing, stamped-metal or chalk effects imitating a material the page never actually renders, as contradicted on its face; imitation material is the single most reliable mark of machine-made design. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. When MATERIAL is contradicted on the focal element, or contradiction is the page rather than the exception, stop ordering repairs: make the first material fix a rebuild directive naming the comp regions to re-derive and the assets to produce; a list of patches against a rejected page launders the rejection into an approval. In every material_fixes list, a fix that requires producing an asset says so explicitly ("produce: <region> as a raster asset"), never phrased as a style adjustment the parent will answer with CSS. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
 3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition.
 4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport.
 5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind other paint is a compliance token, not a shipped material.
+6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp, because the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and the last two live sessions shipped five kickers past a reviewer that never looked.
 
 Do not run a second detector pass; mechanical findings belong to the parent's hooks.
 
-## Verdict Pass
+## Disposition
 
-When the parent returns with post-fix recaptures, you are scoring, not re-hunting. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear").
+The first line of your return is `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. It is derived, never felt: rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it.
 
 ## Output Contract
 
-Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+Return the disposition line first, then exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+
+## Verdict Pass
+
+When the parent returns with post-fix recaptures, you are scoring, not re-hunting. The parent's narration of what was fixed is not evidence; a claimed fix you cannot see in the recaptures is unresolved. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear"), and end with the disposition line recomputed against what remains open; unresolved or partial material findings can never recompute to ship.
 '''

.agents/skills/impeccable/agents/impeccable_manual_edit_applier.toml

@@ -18,12 +18,12 @@ Expect a self-contained handoff with:
 - Event id.
 - Page URL.
 - Optional chunk metadata.
-- Optional repair metadata. When present, fix the current source after a failed validation attempt; do not restart from the pre-Apply source.
+- Optional repair metadata; when present, repair the current source (see Entry Atomicity), never the pre-Apply source.
 - Optional deadline.
 - The current event `batch`.
 - Optional `evidencePath`.
 
-The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not run `live-commit-manual-edits.mjs` for a leased manual Apply event. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
+The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
 
 ## Workflow
 

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

@@ -12,6 +12,7 @@ Each of these is a check on the built result, not an intention. Run them togethe
 - **Type:** body measure 65–75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale and weight steps. Run the real copy at every breakpoint and fix what overflows.
 - **Motion:** one authored moment, not scattered effects and not one identical entrance on every section. Exponential ease-out from an already-visible default. Reach past transform and opacity: blur, backdrop-filter, clip-path, mask, and shadow belong to the palette when they stay smooth.
 - **States:** hover, disabled, loading, error, empty. Plus real content, working controls, responsive composition, keyboard focus.
+- **Browser surfaces:** the parts you did not draw still carry the design. Text selection, the caret, custom scrollbars, focus rings, underline offset, and the numerals in tabular data all ship with browser defaults that belong to no design system. Theme them from the palette. This is the cheapest signal that a page was built rather than assembled, and the one models skip most reliably.
 - **Copy:** the product's own language. Controls name their action; errors name the problem and the recovery.
 - **Coverage:** every brief requirement present and findable within seconds.
 
@@ -32,13 +33,16 @@ Surface habits:
 - Gradient text. Emphasis comes from weight or size.
 - Glass and blur as decoration rather than as a specific effect.
 - A colored `border-left` or `border-right` above 1px on cards, list items, callouts, or alerts.
+- Hard offset shadows (`box-shadow: 4px 4px 0`) outside a world that is actually neobrutalist. The zero-blur block shadow is a costume, not a depth system; a world that did not choose it never earns it as a default.
 - Sparklines, progress rings, and soft-shadowed rounded rectangles standing in for content.
 - Monospace as a costume for "technical" rather than for code, data, or measurement.
+- A system display face (Impact, Arial Black, the platform sans) as the display voice of an own-world page. Source and self-host a face whose character matches the approved lettering; the closest installed font is a failure, not a fallback.
+- Unicode glyphs or emoji standing in for an icon system. Icons are drawn, from a real library or authored SVG, in one consistent stroke and weight.
 - Light or dark picked by category. Pick it from the use scene: who, where, under what ambient light.
 
 - Tracking stops at -0.04em. -0.02 to -0.03em usually reads better.
 - Declare elevation once, border or shadow. A 1px border under a wide soft shadow is the ghost card. Card radii stay at 12–16px; pills are for small controls.
-- Real illustration or none. Sketch-style SVG scenes, `loose-sketch` / `doodle` class names, and `feTurbulence` grain read as amateur.
+- Real illustration or none. Sketch-style SVG scenes, `loose-sketch` / `doodle` class names, and `feTurbulence` grain read as amateur. This bans SVG imitating pictures, never SVG doing geometry: crisp vector shapes, diagrams, animated linework, and shader-driven effects remain first-class media. A shaded, perspectived, or figure-bearing illustration is a picture even in line-art style; geometry means shapes a session can specify exactly.
 - Backgrounds are surfaces, textured only from the subject's world. `repeating-linear-gradient` stripes and two-axis grid overlays need an actual canvas, map, blueprint, or measuring tool under them.
 - Claims and configuration come from supplied truth; label illustrative values honestly. Naming a concept and then ironizing it is not a claim.
 

.agents/skills/impeccable/reference/degraded/asset-producer.md

@@ -13,7 +13,7 @@ Do not redesign. Preserve the reference's visual role, silhouette, palette, ligh
 
 ## Decision Sketches
 
-When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss. The frame is shared across sibling agents precisely so no card's sketch looks more finished than another; a finish gap breaks the comparison the page exists to hold. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more.
+When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame, including its aspect: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss; a native app or mobile-first surface is a portrait frame at its device viewport, never a landscape default. The frame is shared across siblings so no sketch looks more finished than another; a finish gap breaks the comparison. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more. Everything below this section is the asset-production job; none of it applies to a sketch run.
 
 ## Input Contract
 
@@ -44,20 +44,18 @@ Ask blockers once, globally. Missing source path/crops or output directory block
 1. Inventory the full approved mock or every assigned crop.
 2. Put each visual role in exactly one bucket:
    - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
-   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `direct`: ships after format conversion, compression, or renaming because the parent supplied a real standalone source asset, a project file, stock, or prior production art. A crop from the approved mock is never `direct`, whatever its apparent size.
    - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
-3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+3. Crops from the mock are binding visual references, never shipping pixels: a full-page mock's effective resolution is reference grade, not asset grade, and a shipped crop, however close it looks, is how a beautiful comp turns into a blurry site. Every mock-derived asset goes through `produce` as a clean regeneration.
 4. Give the parent an execution order for the `produce` bucket.
 5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
-6. Treat every crop as binding reference. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
+6. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
 
-Codex: the imagegen skill's built-in `image_gen` path is the native tool here; prefer it for generation and editing.
+Codex: the imagegen skill's built-in `image_gen` path is the native tool here; prefer it for generation, editing, and the chroma-key workflow.
 7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
 8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
-9. Save outputs non-destructively in the requested project directory.
-10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
-
-Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: after every generation, run `node .agents/skills/impeccable/scripts/embed-prompt.mjs <asset> --prompt "<the prompt used>"` so the prompt is embedded in the image itself, because the build thread composes what you made and needs to know what it is looking at, and the embedding survives copies where sidecars get lost.
+10. Compare each output against its source crop, opening every image by its workspace-relative path; sandboxed viewers reject absolute paths. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
 
 Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
 
@@ -65,8 +63,6 @@ Use `semantic` for dashboards, charts, controls, screenshots of whole UI section
 
 Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
 
-For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
-
 ## Prompt Pattern
 
 Use this shape for image-to-image work:
@@ -80,9 +76,7 @@ Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, persp
 Do not add new objects. Do not change the concept. Do not redesign the composition.
 ```
 
-For transparent cutouts, use a chroma-key workflow by default: generate on a flat color that cannot appear in the subject, then post-process to alpha; use true native transparency only when the tool supports it or the parent authorizes it.
-
-Codex: run the chroma-key workflow through the imagegen skill's built-in-first path.
+For transparent cutouts: use true alpha when the tool supports it; otherwise generate on a flat chroma-key color that cannot appear in the subject and post-process that color to alpha before shipping the PNG/WebP. Never ship the keyed background as the final asset.
 
 ## Output Contract
 

.agents/skills/impeccable/reference/degraded/documenter.md

@@ -17,6 +17,7 @@ Expect: the project root; the artifact path(s); the direction contract text (THE
 2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence.
 3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system.
 4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear.
+5. Never canonize a craft-floor refusal into the system: an element the floor bans (kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces) is recorded in your not-canonized line as a defect the build carries, never as a design-system rule for future surfaces to inherit. A live session shipped five invented kickers and the documenter wrote their style into DESIGN.md; that is how one violation becomes the house style.
 
 ## Output Contract
 

.agents/skills/impeccable/reference/degraded/finish-reviewer.md

@@ -7,26 +7,31 @@ You are the finishing reviewer for an Impeccable build: fresh eyes on a done art
 
 You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable.
 
-You run under a hard turn ceiling that ends the run without warning, and a run that ends before the five sections are written returns nothing; a review built from what you saw beats a perfect review that never arrives. So treat reading as an allowance, not a prerequisite: read only the provided inputs, never the skill's own reference files, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
+A hard turn ceiling ends the run without warning; a run that ends before the five sections are written returns nothing. Treat reading as an allowance: read only the provided inputs plus the craft floor, never any other skill reference file, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
 
 ## Input Contract
 
-Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: the contract is the builder's abstraction of the comp, and a review anchored on it inherits whatever that abstraction dropped.
+Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path; and the skill's `reference/craft-floor.md` path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: a review anchored on the contract inherits whatever the builder's abstraction dropped.
 
 ## Checks, in order
 
-1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding.
-2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
+1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. When comps exist under `.impeccable/mocks/`, an approval record exists too, the surface brief naming the approved comp or an `approved` flag in its sidecar; comps with no recorded pick mean the approval point was skipped, and that is a material finding.
+2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, the primary action's treatment (a CTA the comp physically works, dissolves, or stamps is a signature element, and its plain-rectangle rendition is contradicted), navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. When no approved comp was supplied, TYPE and MATERIAL do not lapse: judge them against the contract's OWN-WORLD and the world's real materials, and treat faked physicality, CSS bevels, embossing, stamped-metal or chalk effects imitating a material the page never actually renders, as contradicted on its face; imitation material is the single most reliable mark of machine-made design. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. When MATERIAL is contradicted on the focal element, or contradiction is the page rather than the exception, stop ordering repairs: make the first material fix a rebuild directive naming the comp regions to re-derive and the assets to produce; a list of patches against a rejected page launders the rejection into an approval. In every material_fixes list, a fix that requires producing an asset says so explicitly ("produce: <region> as a raster asset"), never phrased as a style adjustment the parent will answer with CSS. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
 3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition.
 4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport.
 5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind other paint is a compliance token, not a shipped material.
+6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp, because the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and the last two live sessions shipped five kickers past a reviewer that never looked.
 
 Do not run a second detector pass; mechanical findings belong to the parent's hooks.
 
-## Verdict Pass
+## Disposition
 
-When the parent returns with post-fix recaptures, you are scoring, not re-hunting. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear").
+The first line of your return is `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. It is derived, never felt: rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it.
 
 ## Output Contract
 
-Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+Return the disposition line first, then exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+
+## Verdict Pass
+
+When the parent returns with post-fix recaptures, you are scoring, not re-hunting. The parent's narration of what was fixed is not evidence; a claimed fix you cannot see in the recaptures is unresolved. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear"), and end with the disposition line recomputed against what remains open; unresolved or partial material findings can never recompute to ship.

.agents/skills/impeccable/reference/degraded/manual-edit-applier.md

@@ -16,12 +16,12 @@ Expect a self-contained handoff with:
 - Event id.
 - Page URL.
 - Optional chunk metadata.
-- Optional repair metadata. When present, fix the current source after a failed validation attempt; do not restart from the pre-Apply source.
+- Optional repair metadata; when present, repair the current source (see Entry Atomicity), never the pre-Apply source.
 - Optional deadline.
 - The current event `batch`.
 - Optional `evidencePath`.
 
-The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not run `live-commit-manual-edits.mjs` for a leased manual Apply event. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
+The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
 
 ## Workflow
 

.agents/skills/impeccable/reference/init.md

@@ -36,7 +36,7 @@ Start with the unknowns that most change future product decisions:
 2. What does the product make possible, and what is its meaningfully different mechanism or position?
 3. What durable constraints, assets, evidence, or product facts must future work preserve?
 
-Confirm ambiguous platform separately. Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them.
+Confirm ambiguous platform separately. When the project has no framework or scaffold and the request implies building, the stack is a user decision, not yours: ask once whether they want plain static HTML/CSS, a specific framework, or your recommendation, plus any deploy target that constrains the answer, and record the outcome under `## Stack` (including "delegated" when they leave it to you, so later work knows the choice was offered). Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them.
 
 Do not ask for an aesthetic direction, emotional feel, visual references, colors, typography, or style during init. If the user volunteers a binding visual constraint, record it without expanding it.
 
@@ -66,6 +66,9 @@ Write only confirmed facts and explicitly marked open decisions. Omit irrelevant
 
 web
 
+## Stack
+[Greenfield only: the user's answer to the stack question, e.g. "static HTML/CSS", "Astro", or "delegated: <what you chose and why>". Omit the section when an existing codebase already answers it.]
+
 ## Users
 [Primary users, their situation, and job. Add other audiences only when confirmed.]
 

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

@@ -0,0 +1,102 @@
+One-time live-mode project setup. Loaded from [live.md](live.md) only when `live.mjs` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
+
+## Write the config
+
+Create the file at the `path` the boot reported (default `.impeccable/live/config.json`):
+
+```json
+{
+  "files": ["<path-or-glob>", "<path-or-glob>", ...],
+  "exclude": ["<optional-glob>", ...],
+  "insertBefore": "</body>",
+  "commentSyntax": "html",
+  "cspChecked": true
+}
+```
+
+`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
+
+**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
+
+**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
+
+| Framework | `files` | `insertBefore` | `commentSyntax` |
+|-----------|---------|----------------|-----------------|
+| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
+| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
+| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
+| Nuxt | `["app.vue"]` | `</body>` | `html` |
+| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
+| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
+| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
+
+Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `live.mjs` after each build (accept is unaffected; it writes true source via the fallback flow).
+
+**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.impeccable/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `live-inject.mjs` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `ImpeccableLiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
+
+## Config drift
+
+On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
+
+## CSP detection (first-time only)
+
+If `config.cspChecked === true`, skip this whole section; the user was already asked once.
+
+```bash
+node .agents/skills/impeccable/scripts/detect-csp.mjs
+```
+
+Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
+
+- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
+- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
+- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
+- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
+
+### Consent prompt (use this phrasing)
+
+> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
+>
+> ```diff
+> [file: <patchTarget>]
+> [exact diff, 2-5 lines]
+> ```
+>
+> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
+
+On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
+
+### append-arrays
+
+Declare near the top of the file that holds the CSP arrays, then append `...__impeccableLiveDev` to the script-src and connect-src arrays:
+
+```ts
+// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
+const __impeccableLiveDev =
+  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
+```
+
+Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`, `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js`. Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
+
+### append-string
+
+Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
+
+```ts
+// Dev-only allowance so impeccable live mode can load.
+const __impeccableLiveDev =
+  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
+```
+
+- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
+- `connect-src 'self'` becomes `` `connect-src 'self'${__impeccableLiveDev}` ``
+
+Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js`, `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts`.
+
+## Troubleshooting
+
+If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`; setup asks again.
+
+After setup, re-run `live.mjs`.

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

@@ -2,52 +2,35 @@ Interactive live variant mode: select elements in the browser, pick a design act
 
 ## Prerequisites
 
-A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
+A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
 
 Codex: run live helper commands, the app dev server, and any dependency-installing setup with `sandbox_permissions: "require_escalated"` from the start; live mode depends on localhost and package-manager network access that the sandbox blocks.
 
 ## The contract (read once)
 
-Execute in order. No step skipped, no step reordered.
+Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins.
 
-1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .agents/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
+1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .agents/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root.
 2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
-3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
-
-The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
-5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
-6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
+3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `live-poll.mjs` to reconnect.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant.
+5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack.
+6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges delivery, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts stay recoverable until `live-complete.mjs --id EVENT_ID` runs. Finish that cleanup before polling again.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The journal under `.impeccable/live/sessions/` is canonical and replays unacknowledged work after a helper restart; the injected `live.js` re-attaches when the page reopens. Fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
-- **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free while you generate and publish in it. Do not block the shell.
-- **Cursor**: run **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|exit)"`. After each event the poll exits; handle it, `--reply`, then start `live-poll.mjs` again. Do **not** use `--stream` on Cursor: incremental stdout notify is slower in practice than exit-based notify (~5s vs sub-second in testing).
-- **Codex**: run the default one-shot poll in a **yielded foreground exec session**. Do not suffix it with `&`, use `--stream`, or leave Live without an active foreground poll. Handle every event in the main task; after each handler/reply, restart the foreground poll.
-- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
+- **Claude Code**: run the poll as a **background task** (no short timeout); the harness notifies you on completion. Do not block the shell.
+- **Cursor**: **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|manual_edit_apply|variant_mount_failed|prefetch|exit)"`; handle, `--reply`, restart the poll. Do **not** use `--stream` on Cursor (measured ~5s pickup vs sub-second one-shot).
+- **Codex**: default one-shot poll in a **yielded foreground exec session**. No `&`, no `--stream`, never leave Live without an active foreground poll. Starting the poll is not enough: SERVICE it (keep reading the exec session until it returns an event). Never announce "waiting for the user" and idle; a yielded poll nobody reads is a dead session, and the user's Go sits unanswered.
+- **Other harnesses**: one-shot foreground unless you know stdout reliably returns when a shell exits.
 
-Generation delivery policy:
-- **Default (Cursor and other harnesses):** keep the established atomic single-edit delivery. Do not switch a harness to progressive until its poll loop is known not to block on the extra publish calls. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
+Delivery policy: atomic single-edit delivery everywhere; do not switch a harness to progressive publishing unless its poll loop is known not to block on the extra calls.
 
 Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
 
-## Start
-
-```bash
-node .agents/skills/impeccable/scripts/live.mjs
-```
-
-Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md, DESIGN.md, and any surface brief already loaded by Setup in mind for variant generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** 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 requires the user's explicit redesign/replacement intent.
-
-`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).
-
-If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project hasn't been configured for live mode (or its config is stale). See **First-time setup** at the bottom.
-
 ## Poll loop
 
-**Default (portable, all harnesses):**
-
 ```
 LOOP:
   node .agents/skills/impeccable/scripts/live-poll.mjs   # default long timeout; no --timeout=
@@ -59,253 +42,143 @@ LOOP:
   "discard"   → Handle Discard; LOOP
   "prefetch"  → Handle Prefetch; LOOP
   "manual_edit_apply" → Handle Manual Edit Apply; reply done|partial|error; LOOP
+  "variant_mount_failed" → Fix the variant files; reply done --file <path>; LOOP
   "timeout"   → LOOP
   "exit"      → break → Cleanup
 ```
 
-**Stream mode (experimental, not for Cursor):**
+`variant_mount_failed` means the browser could not render what you published (`variant`, module `url`, `error`). The user sees a persistent error card, not variants. Fix the variant files, then `--reply EVENT_ID done --file <manifest or source path>`; the browser retries on its own.
 
-```
-node .agents/skills/impeccable/scripts/live-poll.mjs --stream   # stays running; one JSON line per event
-  Handle event; run --reply in a separate command
-  Repeat until "exit" line → Cleanup
+**Stream mode** (`--stream`, experimental, never on Cursor): one long-lived process, one JSON line per event, `--reply` from a separate command. Only for harnesses that read incremental stdout reliably.
+
+## Start
+
+```bash
+node .agents/skills/impeccable/scripts/live.mjs
 ```
 
-Stream keeps one process alive and waits for `--reply` ack before polling again. Useful only when the harness reads incremental stdout reliably and quickly. **Cursor is not one of those:** background pattern notify on a long-running shell was ~5s to pick up events vs sub-second for one-shot exit notify. Default to one-shot everywhere unless you have measured otherwise.
+Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `surface-brief.mjs` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent.
+
+`serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry.
+
+If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config.
 
 ## Recovery commands
 
-The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
-
-Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
+The append-only journal under `.impeccable/live/sessions/` is canonical durable state (not project source). When the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
 
 ```bash
-node .agents/skills/impeccable/scripts/live-status.mjs
-node .agents/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
-node .agents/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
+node .agents/skills/impeccable/scripts/live-status.mjs      # helper state, active sessions, queued events; works with the helper down
+node .agents/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID   # active snapshot, pending event, next safe action
+node .agents/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID # canonical manual final acknowledgement after verified cleanup
 ```
 
-- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
-- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
-- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
-
-Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
+Server restart rule: start `live-server.mjs` again, then poll; startup requeues unacknowledged events, so never ask the user to click Go again unless `live-resume.mjs` says no active session exists.
 
 ## Handle `generate`
 
 **Replace mode** (default): `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
 
-**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`. Requires a non-empty `freeformPrompt` **or** annotations. Screenshot is sent only when annotations exist (same rule as replace). Use `placeholder` dimensions as a soft size hint for net-new content.
+**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`; requires a non-empty `freeformPrompt` **or** annotations. `placeholder` is a soft size hint.
 
-Speed matters; the user is watching the selected element. Reuse server preflight metadata when available, minimize discovery calls, and follow the harness-specific delivery policy above.
+Speed matters; the user is watching the selected element. Reuse preflight metadata, minimize discovery calls.
 
 ### Insert mode branch
 
-When `event.mode === "insert"`:
-
-1. Read the screenshot if `event.screenshotPath` is present (annotations only).
-2. If `event.scaffold` is present, use it as the insert-helper result and do **not** run the helper again. Otherwise run the insert helper instead of wrap:
+1. Read the screenshot if present (annotations only).
+2. If `event.scaffold` is present, use it and do **not** run the helper again. Otherwise:
 
 ```bash
 node .agents/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
   --element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT"
 ```
 
-- `--position` ← `event.insert.position` (`before` | `after`)
-- Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
-
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
-
-For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
-
-For non-Svelte targets, on accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
+`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched.
 
 ### Replace mode (default)
 
 ### 1. Read the screenshot (if present)
 
-`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
+`event.screenshotPath` is sent **only when the user annotated before Go**; it is a PNG of the element with annotations baked in. Read it before planning. When absent, do not ask for one or screenshot the page yourself: without annotations a screenshot anchors you on the existing design and fights the three-distinct-directions brief; work from `element.outerHTML`, the computed styles, and the prompt.
 
-When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
-
-`event.comments` and `event.strokes` carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).
-
-Reading annotations precisely:
-
-- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
-- **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
-- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
-- **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
+Annotation semantics: a comment's `{x, y}` is element-local and binds the text to the child under that point (a comment near the title is about the title). Comments and strokes are independent unless clearly paired. Strokes read by shape: closed loop = "this thing" (emphasis, not a clipping region); arrow = direction or movement; cross/slash = delete; scribble = emphasis or delete by context. If a stroke's intent is genuinely ambiguous and it changes the brief, ask one short question before generating; otherwise state your reading in one sentence.
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the helper already found the source and computed the wrapper; treat it as the successful output and skip the command. `event.scaffoldAttempted` with `scaffoldError` means preflight could not finish; use the command below.
 
-**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper; it hands you `scaffold.wrapperBlock` plus the picked element's source range (`replaceStartLine`, `replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands and strands the browser at 0/N. (`replaceEndLine < replaceStartLine` means insert mode: insert, remove nothing.) The `svelte-component` path never sets `sourceWritten`.
 
 ```bash
 node .agents/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
 ```
 
-Flag mapping. Keep them separate, don't collapse into `--query`:
+Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow.
 
-- `--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.
+Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to.
 
-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.
+For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` holding the variant components, and `sourceFile` the real route. The scaffold is AST-based: control-flow blocks (`{#each}`, `{#if}`) survive intact and a free each-collection crosses the contract as ONE structured prop (kind `collection`). The payload includes `componentStubMarkup` (the prop-substituted markup already written into every stub), so do not read the manifest or stubs back. EDIT `v1.svelte`, `v2.svelte`, ... in place; never delete and recreate them; keep the stub's control flow and `propContract` prop names; never flatten a loop into literal items. The stub `<style>` arrives seeded with the source rules that currently style the selection; restyle or delete them freely. On accept, any seeded rule your variant does not re-declare is REMOVED from the source (the preview never applied it, so the user approved a design without it). Use semantic class selectors, no `@scope`, no `data-impeccable-*`. Reply with `--file` set to the manifest path; the browser mounts the compiled components so Svelte HMR does not reset page state. Accept merges the chosen component back mechanically (markup restored to route expressions, CSS reconciled, params baked, indentation preserved); you have no post-accept cleanup on this path. When the selection contains constructs a detached preview cannot support (component tags, `bind:`/`use:`, await blocks, inline scripts, spread attributes), wrap returns the normal source-preview wrapper with `previewFallback: { from: "svelte-component", reason }`; just follow the returned shape.
 
-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, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
-
-For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
-
-**Params on component-preview paths go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, and both Svelte/Vue previews mount without an HTML variant wrapper. Declare params in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
+**Params on component-preview paths go in a sidecar, never as an attribute** (Svelte parses `{` in attribute values as an expression). Declare them in `componentDir/params.json` keyed by variant number, using the schema from section 7:
 
 ```json
-{
-  "1": [
-    {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
-      {"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"},{"value":"packed","label":"Packed"}
-    ]}
-  ],
-  "2": [
-    {"id":"accent","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Accent"}
-  ]
-}
+{ "1": [ {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
+    {"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"} ]} ] }
 ```
 
-Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`; wrap those selectors in `:global(...)` so the knob values the runtime sets on the mounted root reach your rules. The browser reads `params.json`, docks the panel, and drives `--p-*` / `data-p-*` on the mounted component exactly as it does for the HTML/JSX path.
+Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`, wrapped in `:global(...)` so runtime knob values on the mounted root reach your rules.
 
-`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
-
-- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
-- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
-
-Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
-
-**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
-
-- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
-- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
-- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
-
-All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
+**Fallback errors.** Wrap refuses to write into non-source files (generated, untracked): accepting into one is silent data loss. Three shapes, all with `fallback: "agent-driven"` (see **Handle fallback**): `file_is_generated` (your `--file` points at a generated file), `element_not_in_source` with `generatedMatch` (element only exists generated), `element_not_found` (likely runtime-injected).
 
 ### 3. Load the action's reference
 
-If `event.action` is `impeccable` (the default freeform action), work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md), and decide the visitor mode from the selected surface. Do not load a sub-command reference. **Freeform is not a pass to skip parameters:** you still follow the composition budget and the freeform bias in **§7 Parameters** below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.
-
-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.
+`event.action` is `impeccable` (freeform): work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md); decide the visitor mode from the surface; do not load a sub-command reference. Freeform is not a pass to skip parameters: follow the budget and freeform bias in section 7. Any other action (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): read `reference/<action>.md` before planning; its MUST params layer on top of the section 7 budget.
 
 ### 4. Plan three variants: identity first, then mode, then axes
 
-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.
-
-Four phases. Do them in order.
+Live runs on an existing surface; the brand is already chosen. The job is variation **within identity**, not selection between identities. The worst failure is three off-brand variants the user cannot accept. Four phases, in order.
 
 #### Phase A: Extract the identity (non-skippable)
 
-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 name an aesthetic family in this sentence; that is a conclusion, not observed identity data. Letting conclusions into Phase A collapses the identity lock 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.
+Sources in priority order: DESIGN.md's visual system fields; CSS custom properties (de-facto tokens); computed styles on the picked element and parent; sibling components' visual rhetoric. Write ONE sentence recording what is actually on screen: dominant surface and accent color (real values, not "warm"), the loaded font pairing, layout topology (stacked / side-by-side / grid / asymmetric / overlay), surface treatment (corners, borders, shadows, decoration density), and the voice tone read off the copy. Be specific; skip an axis rather than fabricate; do not name an aesthetic family (a conclusion, not data). This sentence is the **identity lock**: every variant must read as the same brand side by side. Absence of DESIGN.md is never an excuse.
 
 #### 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 durable product and brand truth. Trigger only when the user explicitly asks for departure in the current request or freeform prompt ("redesign this", "rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different"). A stale page critique or an old task note is not replacement authorization.
-
-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.
+**Default** preserves the identity and varies expression within it; right for ~90% of sessions. **Departure** rejects the identity; trigger ONLY on the user's explicit ask in the current request or prompt ("redesign this", "rebuild from scratch", "something completely different"); a stale critique or old note is not authorization. Unsure means default: wrong-default costs "three on-brand variants with similar feel" (recoverable), wrong-departure costs three off-brand variants (unrecoverable).
 
 #### 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:
+**Default mode.** Each variant commits to a different **primary axis**, preserving the identity sentence. The six axes: 1 **Hierarchy** (which element commands the eye), 2 **Layout topology** (stacked / side-by-side / grid / asymmetric / overlay), 3 **Typographic system** (pairing logic, scale ratio, case/weight, *within the available faces*), 4 **Color strategy** (which existing palette role carries the surface: Restrained / Committed / Full palette / Drenched; existing tokens only), 5 **Density** (minimal / comfortable / dense), 6 **Structural decomposition** (merge, split, progressive disclosure). Three variants, three DIFFERENT axes: the same brand at three angles. New fonts, new hues, or new aesthetic-family signals belong to departure mode only.
 
-1. **Hierarchy**: which element commands the eye?
-2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
-3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
-4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
-5. **Density**: minimal / comfortable / dense
-6. **Structural decomposition**: merge, split, progressive disclosure
+**Departure mode.** Each variant anchors to a different aesthetic direction derived from the brand, never a fixed catalog: read PRODUCT.md's Brand Personality words; derive physical, spatial, or material experiences that embody them; from those, derive three directions genuinely different from each other AND from the current surface; reject reflex choices whose rationale would fit a neighboring product. Each direction must be one concrete sentence naming a real-world referent ("a museum exhibition label system", not "clean and minimal").
 
-Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
-
-**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
-
-**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from PRODUCT.md's audience world and voice plus the current DESIGN.md. Do not pick from a fixed catalog; derive directions from this product.
-
-Instead, work from the brand:
-
-1. Read PRODUCT.md's Brand Personality words. Derive physical, spatial, or material experiences that embody them without starting from a design style.
-2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
-3. Reject any direction chosen by reflex rather than derived from the brand. Start over from the personality words when the rationale could fit a neighboring product.
-4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
-5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
+**In both modes, name each variant's 2 or 3 parameter knobs while planning** (section 7 budget). Parameters are part of the design; deciding "what's tunable" during planning beats retrofitting.
 
 #### 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.
+**Default:** compare each variant against the Phase A lock; palette, type voice, or rhetoric drift means it crossed into departure by accident: rework. Then confirm three different primary axes; three "tighter density" variants is failure. **Departure:** two passes, family before sentence. Family pass (non-negotiable): label each variant with a concrete family of your own choosing; shared or interchangeable labels mean rework. Sentence pass: three one-line descriptions side by side; two that rhyme mean rework. When the primary axis is color or theme, the trio must not share theme + dominant hue: three color worlds, not three shades.
 
-**Departure mode squint.** Two passes, family before sentence:
+**Action-specific invocations** must vary along the action's dimension:
 
-1. **Family pass.** Give each variant a concrete family label of your own choosing. If two variants share a label, or a label fits another variant equally well, rework. Do not use a fixed vocabulary. *This pass is non-negotiable in departure mode and catches monoculture the sentence pass misses.*
-2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
-
-**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
-
-**For action-specific invocations**, each variant must vary along the dimension the action names:
-
-- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
+- `bolder`: amplify a different dimension per variant (scale / saturation / structural change).
 - `quieter`: pull back a different dimension (color / ornament / spacing).
 - `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
-- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
-- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
-- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
-- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
-- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
-- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
-- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
-- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
+- `polish`: a different refinement axis (rhythm / hierarchy / micro-details).
+- `typeset`: different pairing AND different scale ratio each.
+- `colorize`: different hue family each; vary chroma and contrast strategy.
+- `layout`: different structural arrangement, not spacing tweaks.
+- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data).
+- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax).
+- `delight`: different flavor of personality (micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic / easter egg).
+- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions); skip its "propose and ask" step, live is non-interactive.
 
 ### 5. Apply the freeform prompt (if present)
 
-`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. 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 conflicts with a confirmed binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes or replaces it. Task-local strategy from the matching surface brief may change when the user changes that surface's goal.
+`event.freeformPrompt` is the user's ceiling on direction: all variants honor it while exploring different interpretations within the Phase B mode. Default mode: the prompt narrows the axes, not the identity ("more confident" → one variant amplifies hierarchy, one commits the accent color, one tightens density). Departure mode: the prompt narrows the lanes, not the families ("newspaper front page" → broadsheet vs tabloid vs trade journal, then run the family pass). When the prompt conflicts with a binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes it.
 
 ### 6. Deliver variants
 
-Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
-
-Colocate preview CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and keeps each delivered state internally complete (no FOUC).
-
-**Atomic default:** write CSS + all variants + parameter manifests in one edit at `insertLine`, preserving the established behavior.
-
-Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
+Complete HTML replacement of the original element per variant, not a CSS-only patch. Colocate preview CSS as a `<style>` tag inside the wrapper. **Atomic default:** CSS + all variants + parameter manifests in one edit at `insertLine`.
 
 ```html
 <!-- Variants: insert below this line -->
@@ -316,92 +189,55 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
   <!-- variant 1: full element replacement (single top-level element) -->
 </div>
 <div data-impeccable-variant="2" style="display: none">
-  <!-- variant 2: full element replacement -->
+  <!-- variant 2 -->
 </div>
 <div data-impeccable-variant="3" style="display: none">
-  <!-- variant 3: full element replacement -->
+  <!-- variant 3 -->
 </div>
 ```
 
-**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
+Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected.
 
-The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
+For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template.
 
-The browser's MutationObserver accepts either delivery shape. On the transactional progressive path it shows arrived variants and pending dots immediately; Accept and Discard are available as soon as one variant exists. Accepting an arrived variant fences the worker before the browser releases the picker, so later publications are rejected.
-
-For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
-
-**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
+**JSX / TSX targets:** wrap `<style>` content in a template literal (CSS braces would parse as JSX), use `className=` / `style={{…}}`, keep `data-impeccable-*` attributes as 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.
+The wrap script provides a single-rooted JSX wrapper with the marker comments inside; drop the block at the marker and the source stays valid TSX.
 
-### 7. Parameters (composition-sized, 0–4 per variant)
+### 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.
+Each variant can expose **coarse** knobs; the browser docks one control per parameter with zero regeneration cost (knobs drive a CSS variable or data attribute your scoped CSS is authored against). Wire an axis as soon as the user could plausibly mutter "a bit tighter" or "a touch more accent" without wanting a regeneration; micro-margins and one-off nudges are not parameters. Freeform bias: you chose the axes, so expose them; a hero with 0 params is almost always a mistake, and 1 is underweight unless the design is a genuine fixed point.
 
-**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
+Budget scales with the element's VISUAL weight (count visual children, not DOM depth):
 
-**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
+- **Leaf / tiny** (button, icon, bare heading): **0 params.**
+- **Small composition** (simple card, labeled input, ≤ ~5 visual children): **0-1**.
+- **Medium composition** (section, nav cluster, 6-15 children): **target 2**; 1 if simple.
+- **Large composition** (hero, full region, 16+ children or sub-sections): **target 2-3, up to 4** when independent axes are all authored in CSS.
 
-**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
+**Hard cap: four** per variant. For named sub-commands, the action reference's MUST params are non-negotiable when expressible; respect the cap, no duplicate knobs.
 
-**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
-
-- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
-- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
-- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
-- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
-
-**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
-
-**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
-
-**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the `svelte-component` path, do not use this attribute.** Declare params in `componentDir/params.json` keyed by variant number instead (see the component-preview paragraphs in the wrap section). The param schema below is identical for every path.
+**Declare** on the HTML/JSX path as a wrapper attribute (component-preview paths use `componentDir/params.json` instead, same schema, keyed by variant number; see the wrap section):
 
 ```html
 <div data-impeccable-variant="1" data-impeccable-params='[
   {"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
-  {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
-    {"value":"airy","label":"Airy"},
-    {"value":"snug","label":"Snug"},
-    {"value":"packed","label":"Packed"}
-  ]},
   {"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
 ]'>
-  ...variant content...
-</div>
 ```
 
-**Three kinds:**
+Three kinds: `range` (slider; drives `--p-<id>`; author `var(--p-color-amount, 0.5)`; fields min/max/step/default/label), `steps` (segmented radio; drives `data-p-<id>`; author `:scope[data-p-density="airy"] .grid { ... }`; fields options/default/label), `toggle` (drives both `--p-<id>: 0|1` and attribute presence; fields default/label). Reset on variant switch is a known limitation: each variant starts at its declared defaults.
 
-- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
-- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
-- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
-
-**Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
-
-**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
-
-**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
-
-```html
-<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->
-```
-
-The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
+**On accept**, the browser sends current values and `live-accept.mjs` writes them as a sibling comment: `<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->`. Carbonize cleanup bakes them: keep only the matching `steps`/`toggle` branch, drop the others, collapse `:scope[data-p-…]` to semantic rules; substitute `range` literals or update the var's default.
 
 ### 8. Signal done
 
@@ -409,127 +245,56 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
 node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
 ```
 
-`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
-
-Then run `live-poll.mjs` again immediately.
+`RELATIVE_PATH` is relative to project root; the browser fetches source directly if the dev server lacks HMR. Then poll 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.
+If wrap or generation fails after the browser flipped to GENERATING, tell the **browser** so its bar resets: `node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` for this (pure file mutator, browser never sees it, bar sticks on dots); `--discard` is only source-side cleanup for a discard the browser itself initiated.
 
 ## Handle fallback
 
-When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
+When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it.
 
-The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
-
-### Step 1: Identify where the element actually lives
-
-Use the error payload:
-
-- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
-- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
-- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
-
-Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
-
-### Step 2: Show three variants in the DOM for preview
-
-The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
-
-1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
-2. Insert your three variant divs inside it, same shape as the deterministic path.
-3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
-
-This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
-
-### Step 3: On accept, write to true source
-
-When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
-
-- Structural change → edit the template / component source.
-- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
-- Dynamic from data → update the data source or the render logic.
-
-Then remove the temporary wrapper from the served file if it's still there.
-
-### Step 4: On discard, clean up the served file
-
-Remove the wrapper you inserted in Step 2. Nothing else to do.
+1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template.
+2. **Preview in the served file**: manually write the same wrapper scaffold `live-wrap.mjs` produces (`<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`) into the file the browser actually loaded, insert your variant divs, `--reply EVENT_ID done --file <served file>`. This edit is temporary; a regen wiping it is fine.
+3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file.
+4. **On discard**, just remove the temporary wrapper.
 
 ## Handle `accept`
 
-Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
+Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` deterministically and acknowledged delivery; the browser DOM is already updated.
 
 - The accept event includes `pageUrl`; the poll script must forward it to `live-accept.mjs --page-url PAGE_URL` so accept-time cleanup only scrubs staged copy edits for the current page.
-- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
-- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
-- `_acceptResult.handled: true` and `carbonize: true`: post-accept cleanup is required, but it must not stall Codex's control lane. See "Required after accept (carbonize)" below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and stderr banner all point at this required follow-up; none are decorative.
-- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
-- `_acceptResult.handled: false, mode: "error"`: the operation genuinely failed. **Do not hand-edit the file**; the source was not touched and editing it yourself would either double-apply or race whoever holds it.
-  - `error: "source_locked"`: a generation publish holds the file. Run the same `live-accept.mjs` command again; it is idempotent and will succeed once the publisher releases. Do not poll past it.
-  - `error: "accept_receipt_conflict"`: this session already resolved as `priorOperation` (on `priorVariantId` for an accept), so the request contradicts durable truth. Do not edit. Run `live-status.mjs` and tell the user what the session actually resolved to.
-  - anything else: report the error briefly and run `live-status.mjs` before continuing.
-- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
+- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, finish cleanup manually if needed, then `live-complete.mjs --id EVENT_ID`.
+- `handled: true, carbonize: false`: nothing to do; poll again.
+- `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it.
+- `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll.
+- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `live-accept.mjs` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `live-status.mjs` and tell the user. Anything else: report briefly, run `live-status.mjs` first.
+- `handled: false` without `mode`: manual cleanup: read file, find markers, edit.
 
 ### Required after accept (carbonize)
 
-When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
+`carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll:
 
-Do these five steps synchronously before the next poll. The source lock, generation epoch, and expected-source hash remain the final safety gates against a generator finishing concurrently with Accept.
+1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `<!-- impeccable-carbonize-start/end SESSION_ID -->` with a `<style data-impeccable-css>` element; read the `<!-- impeccable-param-values -->` comment first when present, it drives steps 3 and 4.
+2. **Move the CSS rules** into the project's real stylesheet (whichever already owns styling for the surrounding element).
+3. **Bake param values while rewriting selectors**: retarget `@scope ([data-impeccable-variant="N"])` to real semantic classes; keep only the `:scope[data-p-<id>="VALUE"]` branch matching the chosen value; substitute `var(--p-<id>)` literals or update the var's default.
+4. **Unwrap the accepted content**: delete the inner variant div (and on JSX the outer `data-impeccable-carbonize` div); drop `data-impeccable-params` and all `data-p-*` attributes.
+5. **Delete** the inline `<style>` block, the param-values comment, both carbonize markers, and any `@scope` rules for non-accepted variants.
 
-1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
-2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
-3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the inner `<div data-impeccable-variant="N" style="display: contents">` that wraps it. On JSX/TSX, also delete the outer `<div data-impeccable-carbonize="SESSION_ID" style={{ display: 'contents' }}>` wrapper if present (accept adds it so ternary/`return` slots keep a single root). Drop `data-impeccable-params` and any `data-p-*` attributes; those are live-mode plumbing, not source.
-5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
-
-After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. Poll again only after that verification.
+Then run `live-complete.mjs --id SESSION_ID` and verify `phase: "completed"` before polling again. The command is a gate, not a formality: it refuses with `error: "source_dirty"` plus findings while any live-mode leftover remains; fix and rerun (`--force` only for false positives).
 
 ## Handle `discard`
 
-Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
+Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original and acknowledged `discarded`. Nothing to do unless `_completionAck.ok !== true`; then `live-complete.mjs --id EVENT_ID --discarded` and poll again.
 
 ## Handle `steer`
 
-Event: `{id, message, pageUrl}`. The user typed or spoke into the global bar **Steer** control: page-level direction without picking an element or launching variant generation.
-
-The mic button uses the browser **Web Speech API** (MVP): click to start, speak, stop automatically when the utterance ends, then the transcript submits as a steer event. Click again while listening to cancel without submitting.
-
-This is lighter than `generate`: no screenshot, no element context, no variant cycling. Read `message` and inspect the live page or project files as needed, then either make edits or answer in prose.
-
-When finished:
-
-```bash
-node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short note for a browser toast"]
-```
-
-On failure:
-
-```bash
-node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
-```
-
-Then poll again immediately. Do not send a separate "picked up" reply. The Steer bar stays locked until `steer_done` or `error` arrives over SSE.
+Event: `{id, message, pageUrl}`: page-level direction from the global bar's Steer control (typed or spoken), no element context, no variant cycling. Read `message`, inspect the page or files as needed, make edits or answer in prose. Reply `node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short toast"]`, or on failure `--reply EVENT_ID error "Short reason"`, then poll immediately. No separate pickup reply; the Steer bar unlocks on `steer_done` or `error`.
 
 ## Handle `prefetch`
 
-Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
-
-Resolve `pageUrl` to the underlying file:
-
-- Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
-- Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
-
-Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
-
-Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
+Event: `{pageUrl}`: fired once per route on first selection; the user is likely about to Go on a page you have not read. Resolve the route to its file (root `/` is usually the boot's `pageFile`; multi-page sites often map `/foo` to `public/foo/index.html`; SPAs map everything to one entry), read it, poll again. No `--reply`. If you cannot resolve it confidently, skip and poll.
 
 ## Handle `manual_edit_apply`
 
@@ -545,12 +310,7 @@ After source edits finish, reply exactly once with `node .agents/skills/impeccab
 
 ## Exit
 
-The user can stop live mode by:
-- Saying "stop live mode" / "exit live" in chat
-- Closing the browser tab (SSE drops, poll returns `exit` after 8s)
-- The browser's exit button
-
-When the poll returns `exit`, proceed to cleanup. If the poll is still running as a background task, kill it first.
+The user stops live mode by saying so in chat, closing the tab (SSE drops; poll returns `exit` after 8s), or the browser's exit button. On `exit`, kill any still-running background poll, then clean up.
 
 ## Cleanup
 
@@ -558,175 +318,8 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
 node .agents/skills/impeccable/scripts/live-server.mjs stop
 ```
 
-Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
+Stops the helper and runs `live-inject.mjs --remove` to strip the injected script (use `stop --keep-inject` to keep it for a quick restart; `.impeccable/live/config.json` persists as project config). Then search for and remove any leftover `impeccable-variants-start` wrappers and `impeccable-carbonize-start` blocks.
 
-Then:
-- Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
-- Remove any leftover carbonize blocks (search for `impeccable-carbonize-start` markers).
+## First-time setup
 
-## First-time setup (config missing or invalid)
-
-If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
-
-Schema:
-
-```json
-{
-  "files": ["<path-or-glob>", "<path-or-glob>", ...],
-  "exclude": ["<optional-glob>", ...],
-  "insertBefore": "</body>",
-  "commentSyntax": "html",
-  "cspChecked": true
-}
-```
-
-`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
-
-`exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
-
-`cspChecked` tracks whether the CSP detection step below has already run. Absent on first setup; set to `true` after CSP is checked (whether patched, declined, or not needed).
-
-**Hard-excluded paths (cannot be overridden).** `**/node_modules/**` and `**/.git/**` are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.
-
-**Glob syntax.** `**` matches any number of path segments (including zero), `*` matches any characters except `/`, `?` matches a single character except `/`. Paths are always relative to the project root with forward slashes.
-
-| Framework | `files` | `insertBefore` | `commentSyntax` |
-|-----------|---------|----------------|-----------------|
-| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
-| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
-| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
-| Nuxt | `["app.vue"]` | `</body>` | `html` |
-| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
-| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
-| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
-| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
-| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
-
-Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
-
-**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
-
-For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
-
-For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
-
-### Drift-heal warning
-
-On every `live.mjs` boot, after inject, the project is scanned for HTML files under common page-source roots (`public/`, `src/`, `app/`, `pages/`). If any exist that aren't covered by the resolved `files` list, the output includes a `configDrift` field:
-
-```json
-{
-  "ok": true,
-  "serverPort": 8400,
-  "pageFiles": [ "..." ],
-  "configDrift": {
-    "orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
-    "orphanCount": 2,
-    "hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
-  }
-}
-```
-
-When `configDrift` is present, surface it to the user once per session before entering the poll loop:
-
-> Noticed N HTML file(s) in the project that aren't in `config.files`:
->
-> - `public/new-section/index.html`
-> - `public/docs/new-command.html`
->
-> Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
-
-Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
-
-### CSP detection (first-time only)
-
-If `config.cspChecked === true`, skip this entire section. You already asked this user once; the answer sticks.
-
-Otherwise, run the detection helper:
-
-```bash
-node .agents/skills/impeccable/scripts/detect-csp.mjs
-```
-
-Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
-
-- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
-- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
-  - Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
-  - SvelteKit `kit.csp.directives`
-  - Nuxt `nuxt-security` module's `contentSecurityPolicy`
-- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
-  - Inline `next.config.*` `headers()` with a CSP literal
-  - Nuxt `routeRules` / `nitro.routeRules` headers
-- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
-
-#### Consent prompt template
-
-Use this phrasing so the experience is consistent across agents:
-
-> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
->
-> ```diff
-> [file: <patchTarget>]
-> [exact diff, 2–5 lines]
-> ```
->
-> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
-
-On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write `cspChecked: true` (the question's been asked).
-
-On "yes": apply the Shape-specific patch below, then write `cspChecked: true`.
-
-#### append-arrays
-
-CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.
-
-**Declare near the top of the file that holds the CSP arrays:**
-
-```ts
-// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
-const __impeccableLiveDev =
-  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
-```
-
-**Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
-
-- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
-- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
-- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
-
-Reference outputs:
-- `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
-- `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js` (SvelteKit)
-
-Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is already applied; skip asking and just mark `cspChecked: true`.
-
-#### append-string
-
-CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the `script-src` and `connect-src` directives.
-
-```ts
-// Dev-only allowance so impeccable live mode can load.
-const __impeccableLiveDev =
-  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
-```
-
-Then in the CSP value string:
-- `script-src 'self' 'unsafe-inline'` → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
-- `connect-src 'self'` → `` `connect-src 'self'${__impeccableLiveDev}` ``
-
-(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
-
-Per-framework specifics:
-- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
-- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
-
-Reference outputs:
-- `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
-- `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts` (Nuxt)
-
-### Troubleshooting
-
-If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
-
-Then re-run `live.mjs`.
+Only when `live.mjs` reports `config_missing` / `config_invalid`, or `configDrift` needs explaining, or the config lacks `cspChecked`: read [live-setup.md](live-setup.md). It owns the config schema, the per-framework `files` table, injection adapters, drift healing, and the CSP detection and consent flow.

.agents/skills/impeccable/reference/new-work.md

@@ -36,21 +36,21 @@ Keep the visual system fixed. Derive five to seven materially different structur
 
 `node .agents/skills/impeccable/scripts/concept-seed.mjs --scope surface --mode <mode>`
 
-The script assigns which structure gets built: your top-ranked structure is what every run would ship, and a single ranking is deterministic, so the dice come from outside. Dress its staging challengers in the committed identity and weigh them against your list before building. Never run the script for a local extension or a precisely specified narrow request; shape those directly.
+The script assigns which structure gets built; your top-ranked structure is what every run would ship, so the dice come from outside. Never run the script for a local extension or a precisely specified narrow request; shape those directly.
 
 ### Create or replace the visual world
 
-1. Name the product's unique mechanism in one sentence, the audience's real scene, its cultural home, and what this first surface must prove. Note the page this category always ships and its predictable opposite; name both as the rut and keep them out of the seven-candidate list, so no die face is spent on the page the category already ships. A brief that paints its own picture, a product name, a titled artifact, a governing metaphor, adds its literal reading to the rut: spend at most one candidate on it and derive the rest from elsewhere in the audience's world.
-2. From that cultural world, list seven concrete visual systems, artifacts, places, or rituals the audience knows by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. The audience's world includes its graphic and screen traditions, the notation, publications, identity programs, data graphics, and interfaces it reads daily, not only its physical objects; a nameable abstract system (a school of poster, a documentation standard, a data-graphic tradition) is as concrete a candidate as any artifact. What would this thing look like as a physical object; what did its world look like before the web? Near-duplicates count once. When more than three of the seven share one material family, the derivation stopped at the subject's most obvious artifact; the audience's world is larger than that, so dig until the list spans at least three families.
+1. Name the product's unique mechanism in one sentence, the audience's real scene, its cultural home, and what this first surface must prove. Note the page this category always ships and its predictable opposite; name both as the rut and keep them out of the seven-candidate list. A brief that paints its own picture, a product name, a titled artifact, a governing metaphor, adds its literal reading to the rut: spend at most one candidate on it and derive the rest from elsewhere in the audience's world.
+2. From that cultural world, list seven concrete visual systems, artifacts, places, or rituals the audience knows by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. The audience's world includes its graphic and screen traditions, not only its physical objects: the notation, publications, identity programs, data graphics, and interfaces it reads daily; a nameable abstract system (a school of poster, a documentation standard) is as concrete a candidate as any artifact. What would this thing look like as a physical object; what did its world look like before the web? Near-duplicates count once. When more than three of the seven share one material family, the derivation stopped at the subject's most obvious artifact; dig until the list spans at least three families.
 3. Turn that material into complete directions: each joins a reusable visual world to a concrete first-surface experience.
-4. Run `node .agents/skills/impeccable/scripts/concept-seed.mjs --scope direction --mode <mode>` and follow what it prints. The script assigns which direction gets built and deals catalog challengers. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, and clarity wins conflicts. Weigh fused challengers against the assigned direction on exactly two axes, audience identification and product clarity; losing to strong grounded material is a valid outcome, and beating a thin or tool-monoculture list is the point.
-5. Present one direction, fully committed: its world, first viewport, visitor path, signature interaction, cross-surface reach, and honest risk. Alongside it, offer the hand's challengers as named alternates, the weighing's verdict written on each as its one-line case, an honest "fuses poorly because X" included; the weighing informs the user's choice, it never pre-empts it. A hand holds at most three challengers: when the roll deals more, the three strongest join the hand and the rest wait in the re-roll pool, noted in one line; dropping a challenger from the hand itself takes a named product-truth failure, disclosed. Add re-roll with an optional one-line steer. What you never present is a ranked menu of your own grounded candidates; a lineup of those invites the safest card, while dealt challengers carry no such rut. The two channels share this structure and differ only in richness: cards and boards on the decision page, names and one-liners through the structured tool; the structured tool's option list also carries the standing exit as its last option.
+4. Run `node .agents/skills/impeccable/scripts/concept-seed.mjs --scope direction --mode <mode>` and follow what it prints. This step has no substitute and no skip condition: on a new or replacement world, writing artifact code before this script has run and its assignment is acknowledged is a contract violation, whatever the harness, the model, or the time pressure, because the roll is the mechanism that keeps every run from converging on the category default. The script assigns which direction gets built and deals catalog challengers. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, and clarity wins conflicts. Weigh fused challengers against the assigned direction on exactly two axes, audience identification and product clarity; losing to strong grounded material is a valid outcome, and beating a thin or tool-monoculture list is the point.
+5. Present one direction, fully committed: its world, first viewport, visitor path, signature interaction, cross-surface reach, and honest risk. Alongside it, offer the hand's challengers as named alternates, the weighing's verdict written on each as its one-line case, an honest "fuses poorly because X" included; the weighing informs the user's choice, it never pre-empts it. A hand holds at most three challengers: when the roll deals more, the three strongest join the hand and the rest wait in the re-roll pool, noted in one line; dropping a challenger from the hand itself takes a named product-truth failure, disclosed. Add re-roll with an optional one-line steer. Never present a ranked menu of your own grounded candidates; a lineup of those invites the safest card. The two channels share this structure and differ only in richness: cards and boards on the decision page, names and one-liners through the structured tool; the structured tool's option list also carries the standing exit as its last option.
 
-The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Give every card the same anatomy, thesis, palette, materials, first viewport, honest risk, and the challengers' case lines (run the script with `--schema` for the exact shape); the page renders identity from these fields, so a grounded direction is never a wall of text against rendered art, and a challenger's catalog image rides as labeled inspiration, never as the promise of the build. Author `canonCard` too: the category standard as one honest card with the same anatomy; the page keeps it subordinate, and the counterweights still bind you, so it is never yours to recommend. Run `node .agents/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
+The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Give every card the same anatomy, thesis, palette, materials, first viewport, honest risk, and the challengers' case lines (run the script with `--schema` for the exact shape); the page renders identity from these fields, and a challenger's catalog image rides as labeled inspiration, never as the promise of the build. Author `canonCard` too: the category standard as one honest card with the same anatomy; the page keeps it subordinate, and the counterweights still bind you. Run `node .agents/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-When image generation exists, every card also declares a `sketch` path under `.impeccable/sketches/`, the canon card included. Serve the page first, then produce the sketches; the page shimmer-waits per slot and the user may answer before they land, so generation never delays the question. Render every sketch through one shared frame so the comparison stays about direction, never rendering luck: the requested surface's first viewport as a flat, matte design sketch in that card's own palette and type character, deliberately unfinished, no photorealism, no gloss, identical framing across cards; a candidate whose sketch looks more finished than the others has broken the comparison, not won it. The only legible text in a sketch is the product's real name and one real headline; every other text region is greeked, indistinct lines standing where copy will go, because a sketch that renders invented specs, prices, or dates puts claims in front of the user that PRODUCT.md never made. Produce in the order the user reads: the assigned card, then the hand, then canon, each file written the moment it is done. When the harness runs subagents in parallel, fan the set out as one agent per card: each spawn is the shipped asset producer with a single-sketch packet, that card's fields, PRODUCT.md, the shared frame, and the card's declared path, up to four in flight at once, so the whole set lands in roughly the time of one. A slot still empty when its agent returns is regenerated inline, and a slot still empty when the user answers is dropped without ceremony; no other supervision is owed. Without parallel subagents, generate in the main thread after serving, in the same reading order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. A sketch answers which world, never which composition: the comp round still renders its full set, and the chosen card's sketch seeds at most one probe. With no image generation, the cards carry their identity in palette chips and facts, and that page is complete, not a lesser version.
+When image generation exists, every card also declares a `sketch` path under `.impeccable/sketches/`, the canon card included. Where the harness sandboxes its shell, start the page through the least-sandboxed command path it offers: a sandboxed shell cannot bind the board's port, and the first-attempt failure costs a retry every session. Serve the page first, then produce the sketches; the page shimmer-waits per slot and the user may answer before they land. Render every sketch through one shared frame so the comparison stays about direction, never rendering luck: the requested surface's first viewport as a flat, matte design sketch in that card's own palette and type character, deliberately unfinished, no photorealism, no gloss, identical framing across cards; a candidate whose sketch looks more finished than the others has broken the comparison, not won it. The frame's aspect is the surface's own: a native app or mobile-first surface sketches portrait at its device viewport, a desktop web surface landscape, and the decision page adapts to either, so a phone screen sketched landscape is a broken frame, not a neutral default. The only legible text in a sketch is the product's real name and one real headline; every other text region is greeked, indistinct lines standing where copy will go, because a sketch that renders invented specs, prices, or dates puts claims in front of the user that PRODUCT.md never made. Produce in the order the user reads: the assigned card, then the hand, then canon, each file written the moment it is done. When the harness runs subagents in parallel, fan the set out as one agent per card: each spawn is the shipped asset producer with a single-sketch packet, that card's fields, PRODUCT.md, the shared frame, and the card's declared path, up to four in flight at once. A slot still empty when its agent returns is regenerated inline, and a slot still empty when the user answers is dropped without ceremony; no other supervision is owed. Without parallel subagents, generate in the main thread after serving, in the same reading order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. A sketch answers which world, never which composition: the comp round still renders its full set, and the chosen card's sketch seeds at most one probe. With no image generation, the cards carry their identity in palette chips and facts, and that page is complete, not a lesser version.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -62,13 +62,13 @@ Pick a color strategy before picking colors: Restrained (neutrals plus one accen
 
 Choose faces like objects from the subject's world, in the mode's register. Operate and Read surfaces are well served by system stacks and workhorse UI faces; Persuade and Experience surfaces want faces with a point of view, and these training-data defaults mean you stopped looking: Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter-as-display, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans. Naming one of these faces anyway requires a reason no other face could satisfy, and a subject association is never that reason: books wanting a serif, bookshops wanting hand-lettering, and tech wanting a mono are the associations the list exists to break.
 
-Calibration: AI-generated interfaces cluster around a few looks regardless of subject: warm cream ground, high-contrast serif display, and a terracotta or signal-red accent; near-black with one neon accent and glowing edges; broadsheet-editorial hairlines, italic display serif, and small tracked mono labels. All are legitimate when the brief calls for them; the brief always wins. Where the brief leaves the aesthetic free, landing in one of them means the self-check failed: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious. Energy is not the enemy of trust: a brief's negative constraints (no gamification, no hype) rule out those devices, not exuberance, and adjectives describing the product's behavior (quiet support, calm coaching) do not dictate the surface's energy. A bookish, warm, or child-facing subject does not soften the calibration: book cloth, thread, jackets, endpapers, and shelf ephemera span the whole saturated spectrum, and cream paper is the smallest corner of that world; landing on cream plus serif for a book subject is the default wearing the subject's clothes. A brief-pinned world pins the world, not its softest rendition: the pinned world's full material range stays in play, and a rendition that matches what any model ships for that world failed the self-check at execution rather than selection.
+Calibration: AI-generated interfaces cluster around a few looks regardless of subject: warm cream ground, high-contrast serif display, and a terracotta or signal-red accent; near-black with one neon accent and glowing edges; broadsheet-editorial hairlines, italic display serif, and small tracked mono labels. All are legitimate when the brief calls for them. Where the brief leaves the aesthetic free, landing in one means the self-check failed: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious. Energy is not the enemy of trust: a brief's negative constraints (no gamification, no hype) rule out those devices, not exuberance, and adjectives describing the product's behavior (quiet support, calm coaching) do not dictate the surface's energy. A bookish, warm, or child-facing subject does not soften the calibration: book cloth, thread, jackets, endpapers, and shelf ephemera span the whole saturated spectrum, and cream paper is the smallest corner of that world; landing on cream plus serif for a book subject is the default wearing the subject's clothes. A brief-pinned world pins the world, not its softest rendition: the pinned world's full material range stays in play, and a rendition that matches what any model ships for that world failed the self-check at execution rather than selection.
 
 ## 5. Record the decision
 
-Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract.
+Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment, placed as the first child of the document's body in the root layout, never inside a slotted or child component (some compilers, Astro among them, strip a slot's leading comment while keeping deeper ones). After the first production build, grep the built output for the seed key; a contract the build erased is a contract nobody can audit. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, and the seed key the script printed. Close the comment with one more line, FINISH: the run's exit condition, verbatim "unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md". The comment tops the artifact you re-open on every edit, the one reminder that survives a long build: a page that looks complete with the FINISH line undischarged is not done, it is abandoned at the finish line. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract.
 
-On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md.
+On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and hands the design-system detector an unstable target. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md.
 
 If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it:
 
@@ -84,11 +84,14 @@ For `shape`, return the selected direction to [shape.md](shape.md) and stop befo
 
 ## 6. Build with full commitment
 
+When an approved comp exists, the comp is king, and the build happens in phases. Phase one is reproduction: rebuild the comp at its own breakpoint until a screenshot at the comp's width and height overlaps it near pixel-perfectly, materials, components, elevation, assets, and implied design language included. Exactly three concessions exist: fonts (the closest obtainable face), icons (exact match unless the user already chose an icon library), and genuine defects in the generated comp such as spelling errors. Everything else must match, and models systematically believe their HTML, CSS, and SVG recreation succeeded when it did not, so the overlap comparison is the authority, never your conviction: set the screenshot beside the freshly reopened comp image at identical dimensions after every region, never beside your memory of it, and when a region keeps losing that comparison, stop recreating it in code and produce it as a rendered asset composited into the page. The comp also outranks every written record of it: when the recorded brief or inventory commits to less than the comp shows, a softer texture, a sparser field, a sculpted plate reduced to flat CSS, correct the record upward to the comp; qualifiers like subtle, restrained, and low-contrast, and counts rounded down to a comfortable fraction, are how approved materials die between approval and build. A produced material must then survive to the screen: a texture buried under a nearly opaque color wash ships the wash, not the material, so judge every material by the screenshot beside the comp, never by the stylesheet. Only when reproduction holds does phase two begin: static regions that should live become animated or interactive, reveals and motion are added, then responsiveness across the surface's devices. Where the comp does not cover the whole surface, continue building the remainder inside the comp's recorded world and design language; a component the comp never shows inherits the recorded system's corner language, line weights, and materials, and may not introduce container styles, border weights, or chrome the comp never uses.
+
 Build the assigned direction, not a safer interpretation of it. The form supplies structure, reading order, component conventions, and native motion; the product supplies every fact. Commit every atom: nav, buttons, inputs, and links are rebuilt in the form's vocabulary, and a stock component inside a committed form is a lapse. Land the first build fully committed; committing is the hard part, and the passes that follow exist to make the committed thing clear and effective, never to dilute it. In unattended work, the safe rendition is the known risk.
 
 - **The first viewport is a thesis, not a header.** Demonstrate the mechanism immediately, at the scale the form has in life; do not trap the concept inside a standard hero or card shell. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood, the concept has not committed yet.
-- **Prove, don't claim.** Show the subject doing its job: the interface at work, the mechanism dramatized, specifics a competitor could not copy-paste. Sections that restate a claim in different words add length, not substance. Demonstration data is design material: author it at full fidelity and label it synthetic; never invent prices, customers, benchmarks, or capabilities.
-- **Author the assets; never substitute chrome.** Great surfaces live on carefully made content: names, entries, copy, covers, thumbnails, textures. In greenfield work every blank the ask round left open is yours to author at production fidelity; content is authorable, claims are labelable, no section is omittable. An unanswered commercial claim ships as a clearly marked placeholder on the user's replacement list. When image generation exists, producing the design's imagery is part of building, at the scale the composition needs: a viewport that wants atmosphere gets a full-bleed layered scene, and a library of small centered subjects standardized for tidiness forecloses that before a line of code exists. Gradients, glass, and generic icon tiles where an authored asset belongs are the gap wearing chrome; icons drawn in the world's own grammar are the remedy, not the target.
+- **Prove the hero before building past it.** When an approved comp exists, render the first viewport, capture it, and set it beside the comp's first viewport before any later section: the hero carries the run's ambition, and every following section inherits its shortfall. Judge scale and density as quantities, a field at a tenth of the comp's coverage or type at half its weight is a different design, and a five-minute retry here is what a rebuild verdict at the finish costs when this check is skipped.
+- **Prove, don't claim.** Show the subject doing its job: the interface at work, the mechanism dramatized, specifics a competitor could not copy-paste. Sections that restate a claim in different words add length, not substance. Demonstration data is design material: author it at full fidelity and label it synthetic; claims stay uninventable.
+- **Author the assets; never substitute chrome.** Great surfaces live on carefully made content: names, entries, copy, covers, thumbnails, textures. In greenfield work every blank the ask round left open is yours to author at production fidelity; content is authorable, claims are labelable, no section is omittable. An unanswered commercial claim ships as a clearly marked placeholder on the user's replacement list. When image generation exists, producing the design's imagery is part of building, at the scale the composition needs: a viewport that wants atmosphere gets a full-bleed layered scene, and a library of small centered subjects standardized for tidiness forecloses it. Gradients, glass, and generic icon tiles where an authored asset belongs are the gap wearing chrome; icons drawn in the world's own grammar are the remedy, not the target.
 - **Build the form's web leverage.** When the chosen world names a technique (canvas, WebGL, view transitions, generative motion), build the technique itself, not a static imitation of it; the graceful fallback serves constrained clients, it is not the default experience.
 - **Pace the scroll like a studio.** Vary density, scale, image, motion, and quiet inside one grammar; a dense passage earns a quiet one, and the page ends anchored by a real close. One spacing rhythm throughout, with more space above a heading than below it.
 - **Use real, verified imagery when the brief implies it.** Search for the subject's physical object rather than the category; one decisive photo beats five mediocre ones. Verify stock URLs resolve.
@@ -98,8 +101,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 ## 7. Inspect and finish
 
-Inspect desktop and mobile in one batched screenshot round, critique the render against the user's request and the direction contract, fix material gaps, and confirm with one final round; two rounds is the ceiling, and fixes batch between them rather than earning per-tweak screenshots. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary.
+Inspect desktop and mobile in one batched screenshot round, critique the render against the user's request and the direction contract, fix material gaps, and confirm with one final round; two rounds is the ceiling, and fixes batch between them rather than earning per-tweak screenshots. When an approved comp exists, the critique is a side-by-side: view the comp region and the build region together, the hero and each section as its own crop at legible scale, never one full-page thumbnail, which hides exactly the failures that matter, crude controls, wrong lettering character, flattened material, behind a superficially similar section order. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary.
 
-After the second inspection round the build thread's polishing is over: no further defect hunts, micro-edit scripts, or rebuilds here; whatever remains ships through the handoffs, where a fresh context does the finding better and cheaper. Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, run from [degraded/finish-reviewer.md](degraded/finish-reviewer.md), and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes in one batch, rebuild once, and recapture the same viewports. A recapture measures positions, loading, and overflow; it cannot measure whether a fix reached the quality the finding named, so send the recaptured screenshots back to the same reviewer for a verdict scoring every material fix resolved, partial, or unresolved (through the harness's agent continuation; without one, run the scoring fresh from [degraded/finish-reviewer.md](degraded/finish-reviewer.md)'s Verdict Pass). Fixes scored partial or unresolved get exactly one more batch, recapture, and verdict; two correction rounds is the ceiling, the second verdict ends the work whatever it says, and the reviewer's findings are the only list you work from, never your own re-opened hunt. Report the final verdict table to the user as it stands, open items included: presenting mechanical confirmation as artistic success is how a failed build gets announced as a finished one. Do not run a second detector.
+After the second inspection round the build thread's polishing is over: no further defect hunts, micro-edit scripts, or rebuilds here; whatever remains ships through the handoffs, where a fresh context does the finding better and cheaper. Where this harness runs no design hook, run `node .agents/skills/impeccable/scripts/detect.mjs --json` on the changed targets once here, fix what is mechanical, and pass the remaining findings to the reviewer; a hookless build that skips this ships every tell the hook exists to catch. Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex; `/impeccable-finish-reviewer` in Cursor; on GitHub Copilot say "Use the impeccable-finish-reviewer agent"), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, the QUALITY BAR card and approved comp paths, and the craft-floor reference path. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Never read the shipped agents' definition files before spawning; the harness loads them at spawn, and you owe only the input packet. Wait on any agent with one long timeout rather than a loop of short polls, and spend the wait on the next independent step. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread and never inherits it: spawn the reviewer fresh, with no forked conversation history (`fork_turns: 0` in codex); a reviewer that inherits your transcript inherits your framing, your optimism, and your abstractions, and everything it needs travels in the inputs above. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, run from [degraded/finish-reviewer.md](degraded/finish-reviewer.md), and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. When the reviewer's first material fix is a rebuild directive, fidelity failed wholesale rather than in patches, so skip the fix batch and execute the rebuild immediately: re-derive the named regions, produce the named assets, and send the result back for a verdict, telling the user what is happening rather than asking permission to fix a failure. The user is consulted only when a second rebuild directive arrives, both verdicts on the table, or when rebuilding would discard content the user approved. Otherwise apply the material fixes in one batch, rebuild once, and recapture the same viewports. A recapture measures positions, loading, and overflow; it cannot measure whether a fix reached the quality the finding named, so send the recaptured screenshots back to the same reviewer for a verdict scoring every material fix resolved, partial, or unresolved (through the harness's agent continuation; without one, run the scoring fresh from [degraded/finish-reviewer.md](degraded/finish-reviewer.md)'s Verdict Pass). Fixes scored partial or unresolved get another batch, recapture, and verdict. Two rounds is the budget an unattended run ends at; an attended session's ceiling belongs to the user, so when the second verdict still lists open items, put the table in front of them and let them choose between shipping as it stands and funding another round. Whoever is deciding, stop the moment a round resolves nothing, and the reviewer's findings are the only list you work from, never your own re-opened hunt. Report the final verdict table to the user as it stands, open items included, under the reviewer's own disposition word: a table with open material findings is never announced as a pass, and never under a softer label than the reviewer wrote. Do not run a second detector.
 
 Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention; without subagents the pass runs from [degraded/documenter.md](degraded/documenter.md). A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded.

.agents/skills/impeccable/reference/visualize.md

@@ -6,8 +6,9 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo
 
 ## Generate three compositional options
 
-Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
+Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session. Comp at the surface's own viewport: portrait at device size for a native app or mobile-first surface, desktop landscape otherwise; a phone screen comped landscape misstates the composition before anything gets built against it. Comps are the build thread's own work, never delegated: the thread that writes the comp prompts holds the direction's full context, and it has already seen every comp when the build starts. Open every image you produce or reference by its workspace-relative path, never an absolute one: sandboxed viewers reject absolute paths, and everything under the project root has a relative path. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
 
+- A comp is a designed surface, not a picture of the subject. Lead the generation prompt with the surface's own structure, whatever regions this design actually has, named in order with their scale relationships; a page with no navigation states that instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with the world's atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. Self-check every render: if it could hang as a poster, or reads as a photograph or scene with some text on it, it is not a comp; regenerate with the layout scaffold stated more literally.
 - When the user shortlisted multiple concepts, spread the three across them.
 - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing.
 - Show enough beyond the opening moment to prove the concept can govern the whole requested surface.
@@ -21,18 +22,28 @@ Show the three together: in the harness when it can display images, otherwise on
 
 Do not begin code until the user approves a direction or explicitly delegates the choice. If they delegate, choose using the task brief, PRODUCT.md, and DESIGN.md, and state the evidence. Approval refines the task concept; it does not modify DESIGN.md.
 
-After approval, summarize the composition and the parts of the comp that must not be literalized. Return to new-work.md, record the direction contract from the approved surface concept, then build.
+This approval point has no substitute and no skip condition. When the structured question tool errors, fall back to the decision page; only after both fail may you treat the choice as delegated, and a delegated pick is still recorded exactly as an approval is and disclosed in your first reply, not your last. The finish reviewer treats a build with generated comps and no recorded approval as carrying a material finding.
+
+After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and the approved comp's `.json` prompt sidecar gains `"approved": true` (every comp generated through `generate-image.mjs` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief. Then summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved surface concept, and build.
 
 ## Inventory implementation fidelity
 
-Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. The same written inventory names the comp's compositional commitments: navigation items and icons, headline levels and their scale relationship, signature geometry such as seams, masks, and overlaps, and each section's arrangement and density. An element never written down is the element the build silently drops, and the direction contract's 150 words cannot carry this list, so this inventory is where it lives. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped.
+Before building, read the approved comp as a design system and record it in the brief: component grammar, corner language, line weights, elevation treatment, and the type ramp, because everything the comp does not show gets built from this record, and without it the fallback is the model's stock kit of square boxes, 1px grids, bento cells, and hard shadows. Then inventory the comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. The same written inventory names the comp's compositional commitments: navigation items and icons, headline levels and their scale relationship, signature geometry such as seams, masks, and overlaps, and each section's arrangement and density. The primary action gets its own row with its own medium: when the comp dissolves, stamps, erodes, or otherwise physically works the main CTA, that treatment is signature material on the page's most important element, and shrinking it to a border trick or a few decorative pixels is the compliance-token version of commitment. An element never written down is the element the build silently drops, and the direction contract's 150 words cannot carry this list, so this inventory is where it lives.
 
-Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery.
+The medium column is where an approved design most often dies, so it obeys a gate: the medium is decided by what the comp region shows, never by what feels buildable in the current stack. A human figure, a product object, machinery, or any material with lighting and depth is raster whatever the stack, and so is any texture by that name alone: woven cloth, paper grain, fabric, leather, brushed metal need no depth argument, because a CSS gradient or layered background is not a texture medium and "layered CSS textures" is not a medium at all. Writing "silhouette" for a photographic figure, or "CSS" for a sculpted panel's finish or a cotton field's weave, is not a medium choice, it is the quiet deletion of the approved design, and it is how a comp full of physical material becomes a flat page with the same section order. Style does not move this boundary: a comp region with perspective, shading, figure drawing, or dense mechanical detail is illustration however line-drawn it looks, and no build session can author illustration as vectors, so it regenerates as raster like any photograph. Authored SVG covers what a session can specify exactly, diagrams with countable elements, controls, flat shape systems, and it ends where drawing skill begins; an instruction-manual world does not convert its illustrations into diagrams, it makes them line-art illustrations. Produce such regions by regenerating them cleanly, with the approved comp and its embedded prompt as the reference for a fresh render at asset resolution; never crop pixels out of the comp itself, whose effective resolution sits far below asset grade. Dropping an image-native region instead of producing it is a scope decision the user makes at the approval point, never a silent flattening after it. Generated imagery is a material, not a claim: evidence rules bind assertions, specs, testimonials, and photographs presented as real, never render fidelity, so "no photography on hand" forbids fake proof, not an illustrated hero.
+
+The gate runs both ways: precise geometry, hard-edged shape systems, diagrams, expressive motion, shaders, and anything interactive are vector and GPU territory (SVG, canvas, WebGL), where a raster flattens what should move, scale, and respond, and code executed safely and professionally remains first-class there. A field or texture built from many small elements carries a quantity commitment either way: write down its approximate density and coverage ("thousands of glyphs over two-thirds of the fold, dense at the top fading into the path"), because a field rebuilt at a tenth of its density passes every checklist and still is not the design. TYPE rows carry the same discipline: name the face's compression class, and render one headline word against the comp before building on it; a visibly wider or lighter silhouette means the face is wrong, and every section built on it inherits the miss. Raster is for what the world paints; code is for what the world draws, animates, or reacts with, and choosing code there is ambition, not economy. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped.
+
+Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies.
 
 Treat the comp as a north star, not something to trace, and know what that allows: translation into semantic, responsive, accessible code, never recomposition. Keeping the palette and mood while redrawing the topology is a second art direction, not an adaptation. Do not rasterize core UI text or controls. Do not substitute a different visual driver after approval without asking.
 
 ## Produce only the assets the build needs
 
-When clean raster ingredients are required and the harness runs subagents, use the shipped asset producer, `impeccable-asset-producer` (`impeccable_asset_producer` in codex): give it the approved comp, output paths, required dimensions and formats, transparency needs, crop notes, and what must remain semantic code. Otherwise produce the minimum required assets in the current thread by the book: load [degraded/asset-producer.md](degraded/asset-producer.md) and follow it inline, with whatever generation exists, the native tool or generate-image.mjs.
+Generation context is part of the asset: a build composed by a thread that never saw the prompts places assets it does not understand. So prefer generating build-critical imagery in the build thread when the budget allows, and when a subagent produces assets instead, every asset must carry its prompt, and the builder reads those prompts before composing a single one of them. The carrier is uniform across harnesses: after generating any image with any tool, native or `generate-image.mjs` (which does it automatically), run `node .agents/skills/impeccable/scripts/embed-prompt.mjs <image> --prompt "<the prompt used>"` so the intent lives inside the file itself and survives copies between machines and harnesses; `--read` recovers it from any impeccable-generated image.
+
+When the harness runs subagents, spawn the shipped asset producer every time, even when the inventory's produce bucket looks empty: its manifest is the independent second opinion on your media, and runs that skipped the spawn are the runs whose cotton became CSS. An honestly empty manifest costs one cheap spawn; a wrongly empty produce bucket costs the build its materials. Use the producer, `impeccable-asset-producer` (`impeccable_asset_producer` in codex; `/impeccable-asset-producer` in Cursor; on GitHub Copilot say "Use the impeccable-asset-producer agent"): give it the approved comp, output paths, required dimensions and formats, transparency needs, crop notes, and what must remain semantic code. Otherwise produce the minimum required assets in the current thread by the book: load [degraded/asset-producer.md](degraded/asset-producer.md) and follow it inline, with whatever generation exists, the native tool or generate-image.mjs.
+
+Convert images with a converter context.mjs reported at boot (the IMAGE_TOOLS line); probe only when it reported none, at most once per session, never per image.
 
 Return to [new-work.md](new-work.md) for the direction contract, implementation, and the finishing pass.

.agents/skills/impeccable/scripts/concept-seed.mjs

@@ -29,7 +29,7 @@
  *     win over thin categories, which is the intended shape.
  *   - RE-ROLL (--reroll <n>): round n of the same base key. The script
  *     recomputes what rounds 0..n-1 drew, excludes all of it, and rolls a
- *     fresh assigned index, challengers, and staging. One base key therefore
+ *     fresh assigned index, challengers, and compositions. One base key therefore
  *     reproduces the entire chain of rounds.
  *   - RATINGS: the reviewer's approval ratings weight the challenger draw
  *     (3-star doubles the odds, 1-star sits out); the approved pool itself
@@ -38,13 +38,26 @@
  * Usage:
  *   node scripts/concept-seed.mjs --scope direction --mode persuade
  *   node scripts/concept-seed.mjs --scope surface --mode operate --from <key>
+ *   node scripts/concept-seed.mjs --scope surface --mode operate --grain flow
  *   node scripts/concept-seed.mjs --scope direction --candidate-count 6
  *   node scripts/concept-seed.mjs --scope direction --mode persuade --from <key> --reroll 1
  *   node scripts/concept-seed.mjs --chosen <challenger-id> --from <key> --scope direction
  *
+ * --grain names how much of the product is in play: product, flow, view, or
+ * region. A docs site, an onboarding flow, a landing page and a data table are
+ * four different amounts of product and want different compositions. Grain is a
+ * preference: it deals matching compositions first and tops up from the rest of
+ * the register, and the rendered seed says how many actually matched so a
+ * borrowed structure is never mistaken for a supplied one.
+ *
+ * --platform names the delivery target (web, ios, android). Unlike grain this is
+ * a hard filter: a composition that needs hover or a pointer does not degrade on
+ * a phone, it stops working. --mode also gates which worlds are eligible, for
+ * worlds whose reviewer marked them as carrying only some modes.
+ *
  * --mode names the requested surface's mode (persuade, operate, read,
- * experience) so the appended staging matches its register of work; omitted,
- * the staging rolls from the full approved pool.
+ * experience) so the appended compositions match its register of work; omitted,
+ * they roll from the full approved pool.
  *
  * Challenger data resolves in order: a local catalog directory (the private
  * service repo, evals, and tests set IMPECCABLE_CATALOG_DIR), then the roll
@@ -64,12 +77,18 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   approvedPoolRevision,
-  deterministicRank,
   readConceptCatalog,
   validateConceptCatalog,
   WELL_TIERS,
 } from './lib/concept-catalog.mjs';
 import { readCompositionCatalog } from './lib/composition-catalog.mjs';
+import {
+  COMPOSITION_GRAINS,
+  COMPOSITION_PLATFORMS,
+  runSyncSelection,
+  selectApprovedChallengers as selectApprovedChallengersCore,
+  selectApprovedCompositions as selectApprovedCompositionsCore,
+} from './lib/roll-selection.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -123,9 +142,11 @@ function requireLocalConcepts() {
   return local;
 }
 
-async function fetchRoll({ scope, key, mode, reroll }) {
+async function fetchRoll({ scope, key, mode, grain, platform, reroll }) {
   const params = new URLSearchParams({ scope, key, reroll: String(reroll) });
   if (mode) params.set('mode', mode);
+  if (grain) params.set('grain', grain);
+  if (platform) params.set('platform', platform);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), apiBudgetMs());
   try {
@@ -187,151 +208,44 @@ ${system}
      QUALITY BAR: board ${board} · hero ${hero}`;
 }
 
-export function renderStaging(composition, index = null) {
+export function renderComposition(composition, index = null) {
   const grammar = composition.grammar.map(rule => `       - ${rule}`).join('\n');
   return `  ${index == null ? '' : `${index + 1}. `}${composition.form}
      SOURCE ID: ${composition.id}
      SPARK: ${composition.spark}
-     STAGING GRAMMAR:
+     COMPOSITION GRAMMAR:
 ${grammar}
      WEB LEVERAGE: ${composition.webLeverage}`;
 }
 
-// Three approved, identity-free staging inputs are rolled deterministically.
-// One input was too weak a counterweight to a model's habitual page skeleton:
-// it became a single optional flourish beside six identity challengers rather
-// than a real search over composition. Prefer distinct staging families so a
-// roll tests materially different hierarchy, sequence, and interaction laws.
-// Cross-mode fallback would make the input misleading, so an absent mode still
-// returns no staging. Re-rolls exclude every earlier set until the pool runs out.
-export function selectApprovedStagings({ scope, key, reroll = 0, mode = null, sourceCompositions = null, count = 3 }) {
-  const pool = sourceCompositions ?? requireLocalConcepts().compositions;
-  // Stagings honour the same breadth gate as worlds: a staging too specific to
-  // serve an arbitrary build stays approved for direct briefs and leaves the
-  // challenger pool. Falls back to the full approved set rather than returning
-  // nothing if every approved staging is marked niche.
-  let approved = pool.filter(composition => composition.status === 'approved');
-  const broad = approved.filter(composition => composition.review?.breadth !== 'niche');
-  if (broad.length > 0) approved = broad;
-  if (approved.length === 0) return [];
-  if (mode) {
-    const matching = approved.filter(composition => composition.surface === mode);
-    if (matching.length === 0) return [];
-    approved = matching;
-  }
-  const prior = new Set();
-  let picks = [];
-  for (let round = 0; round <= reroll; round += 1) {
-    const available = approved.filter(composition => !prior.has(composition.id));
-    const ranked = deterministicRank(
-      available.length >= Math.min(count, approved.length) ? available : approved,
-      round === 0 ? `${scope}:${key}:staging` : `${scope}:${key}:staging:reroll-${round}`
-    );
-    const families = new Set();
-    picks = [];
-    for (const composition of ranked) {
-      const family = composition.familyId ?? composition.id;
-      if (families.has(family)) continue;
-      picks.push(composition);
-      families.add(family);
-      if (picks.length >= count) break;
-    }
-    for (const composition of ranked) {
-      if (picks.length >= count) break;
-      if (!picks.some(pick => pick.id === composition.id)) picks.push(composition);
-    }
-    if (round < reroll) picks.forEach(composition => prior.add(composition.id));
-  }
-  return picks;
+// Selection itself lives in lib/roll-selection.mjs so this script and the roll
+// API run one algorithm rather than two that drifted. These wrappers add only
+// what is local to the skill: resolving the catalog when no pool is passed, and
+// driving the generator with Node's synchronous hash, which keeps a local render
+// synchronous for prepared eval sessions and tests.
+function driveSelection(generator) {
+  return runSyncSelection(generator, input => crypto.createHash('sha256').update(input).digest('hex'));
+}
+
+export function dealCompositions({ scope, key, reroll = 0, mode = null, grain = null, platform = null, sourceCompositions = null, count = 3 }) {
+  const compositions = sourceCompositions ?? requireLocalConcepts().compositions;
+  return driveSelection(selectApprovedCompositionsCore({ scope, key, reroll, mode, grain, platform, compositions, count }));
+}
+
+// Array-returning form, which is what every caller wanted before the match
+// report existed.
+export function selectApprovedCompositions(options) {
+  return dealCompositions(options).picks;
 }
 
 // Compatibility for callers that need a single smoke-test sample.
-export function selectApprovedStaging(options) {
-  return selectApprovedStagings({ ...options, count: 1 })[0] ?? null;
+export function selectApprovedComposition(options) {
+  return selectApprovedCompositions({ ...options, count: 1 })[0] ?? null;
 }
 
-export function selectApprovedChallengers({ scope, key, reroll = 0, sourceConcepts = null }) {
+export function selectApprovedChallengers({ scope, key, reroll = 0, mode = null, sourceConcepts = null }) {
   const source = sourceConcepts ?? requireLocalConcepts().concepts;
-  const approved = source.filter(concept => concept.status === 'approved');
-  // Direction chooses a durable identity, so it draws worlds; surface designs
-  // one page inside a committed identity, so it draws stagings. Duals serve
-  // both. A tier with no matching-strength approvals falls back to its full
-  // approved pool rather than starving the roll.
-  const wanted = scope === 'direction'
-    ? new Set(['world', 'dual'])
-    : new Set(['composition', 'dual']);
-  const approvedByTier = new Map();
-  for (const concept of approved) {
-    const tier = approvedByTier.get(concept.wellTier) || [];
-    tier.push(concept);
-    approvedByTier.set(concept.wellTier, tier);
-  }
-  if (WELL_TIERS.some(tier => !(approvedByTier.get(tier) || []).length)) {
-    throw new Error('concept-seed: every challenger tier needs at least one approved concept');
-  }
-  for (const [tier, pool] of approvedByTier) {
-    const matching = pool.filter(concept => wanted.has(concept.strength));
-    if (matching.length > 0) approvedByTier.set(tier, matching);
-  }
-  // Two challengers per tier, so every roll carries near-zero-translation
-  // graphic systems beside instrument languages and atmosphere worlds, with
-  // the second pick preferring a different family for diversity. Tier order
-  // in the rendered list is rolled too, to avoid positional bias.
-  // Two separate axes, and both can exclude. Rating grades quality: a 3-star
-  // earns a second ticket, a 1-star marginal keep leaves the pool. Breadth says
-  // whether a world can serve an arbitrary build at all, so a niche world
-  // leaves the pool however good it is. Breadth was split out of rating because
-  // the only way to hold a narrow world back used to be calling it marginal,
-  // which made "excellent but narrow" unrecordable and corrupted the ratings as
-  // a calibration signal for the next authoring round.
-  const ticketsFor = pool => pool.flatMap(concept => {
-    const rating = concept.review?.rating;
-    // Two independent exclusions: a marginal world is too weak to challenge,
-    // a niche world too narrow. Either one keeps its approval for direct
-    // briefs and leaves the pool.
-    if (rating === 1 || concept.review?.breadth === 'niche') return [];
-    return rating === 3
-      ? [{ concept, ticket: 0 }, { concept, ticket: 1 }]
-      : [{ concept, ticket: 0 }];
-  });
-  const pickRound = (round, excluded) => {
-    const salt = round === 0 ? '' : `:reroll-${round}`;
-    const tierOrder = deterministicRank(
-      WELL_TIERS.map(id => ({ id })),
-      `${scope}:${key}:tiers${salt}`
-    ).map(item => item.id);
-    return tierOrder.flatMap((tier, index) => {
-      let pool = approvedByTier.get(tier).filter(concept => !excluded.has(concept.id));
-      // A tier exhausted by prior rounds falls back to reuse over starvation.
-      if (pool.length === 0) pool = approvedByTier.get(tier);
-      let tickets = ticketsFor(pool);
-      if (tickets.length === 0) tickets = pool.map(concept => ({ concept, ticket: 0 }));
-      const ranked = deterministicRank(
-        tickets,
-        `${scope}:${key}:challenger-${index}${salt}`,
-        entry => `${entry.concept.id}#${entry.ticket}`
-      );
-      const order = [];
-      const seen = new Set();
-      for (const entry of ranked) {
-        if (seen.has(entry.concept.id)) continue;
-        seen.add(entry.concept.id);
-        order.push(entry.concept);
-      }
-      const first = order[0];
-      const second = order.find(concept => concept.familyId !== first.familyId)
-        || order.find(concept => concept.id !== first.id);
-      return second ? [first, second] : [first];
-    });
-  };
-  // Round n of a re-roll chain excludes everything rounds 0..n-1 drew, so the
-  // same base key reproduces the whole chain.
-  const excluded = new Set();
-  let picks = pickRound(0, excluded);
-  for (let round = 1; round <= reroll; round += 1) {
-    for (const pick of picks) excluded.add(pick.id);
-    picks = pickRound(round, excluded);
-  }
+  const { approved, picks } = driveSelection(selectApprovedChallengersCore({ scope, key, reroll, mode, concepts: source }));
   return {
     approved,
     picks,
@@ -347,6 +261,8 @@ export function renderConceptSeed({
   key = process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex'),
   reroll = 0,
   mode = null,
+  grain = null,
+  platform = null,
   candidateCount = 7,
   catalogDir = CATALOG_DIR,
   _resolvedData = undefined,
@@ -360,6 +276,14 @@ export function renderConceptSeed({
   if (mode !== null && !SEED_MODES.has(mode)) {
     throw new Error('concept-seed: --mode must be persuade, operate, read, or experience');
   }
+  // Grain needs no mode: how much of the product is in play is independent of
+  // which register of work it is.
+  if (grain !== null && !COMPOSITION_GRAINS.includes(grain)) {
+    throw new Error(`concept-seed: --grain must be one of ${COMPOSITION_GRAINS.join(', ')}`);
+  }
+  if (platform !== null && !COMPOSITION_PLATFORMS.includes(platform)) {
+    throw new Error(`concept-seed: --platform must be one of ${COMPOSITION_PLATFORMS.join(', ')}`);
+  }
   if (!Number.isInteger(candidateCount) || candidateCount < 5 || candidateCount > 7) {
     throw new Error('concept-seed: --candidate-count must be an integer from 5 to 7');
   }
@@ -381,6 +305,7 @@ export function renderConceptSeed({
         scope,
         key,
         reroll,
+        mode,
         sourceConcepts: local.concepts,
       });
       data = {
@@ -389,16 +314,21 @@ export function renderConceptSeed({
         approvedCount: approved.length,
         catalogCount,
         challengers: picks,
-        stagings: selectApprovedStagings({ scope, key, reroll, mode, sourceCompositions: local.compositions }),
+        ...(() => {
+          const dealt = dealCompositions({ scope, key, reroll, mode, grain, platform, sourceCompositions: local.compositions });
+          return { compositions: dealt.picks, compositionMatch: dealt.match };
+        })(),
       };
     } else {
       // Keep local renders synchronous for prepared eval sessions and tests;
       // installed skills without a bundled catalog resolve through the API.
-      return fetchRoll({ scope, key, mode, reroll }).then(roll => renderConceptSeed({
+      return fetchRoll({ scope, key, mode, grain, platform, reroll }).then(roll => renderConceptSeed({
         scope,
         key,
         reroll,
         mode,
+        grain,
+        platform,
         candidateCount,
         catalogDir,
         _resolvedData: roll ? {
@@ -407,7 +337,11 @@ export function renderConceptSeed({
           approvedCount: roll.approvedCount,
           catalogCount: roll.catalogCount,
           challengers: roll.challengers,
-          stagings: Array.isArray(roll.stagings) ? roll.stagings : roll.staging ? [roll.staging] : [],
+          compositions: Array.isArray(roll.compositions)
+            ? roll.compositions
+            : Array.isArray(roll.stagings)
+              ? roll.stagings
+              : roll.staging ? [roll.staging] : [],
         } : null,
       }));
     }
@@ -471,13 +405,18 @@ ASSIGNED INDEX: ${buildIndex}
   The assignment exists to refuse the model's ranking rut, never to outrank
   the user or the brief. Never expose assignment metadata in user-facing labels.
 No challengers this run: the roll service was unreachable and no local
-catalog exists. A sandboxed exec tool with no network access causes exactly
-this; before accepting degradation, rerun this command once through the
-harness's network-enabled command tool. A sandboxed shell without network egress is the most common
-cause: if this harness can rerun the command with network access granted,
-do that once before proceeding. Otherwise proceed with the grounded
-candidates alone; the assignment
-above still applies at full strength. Tell the user plainly that this roll
+catalog exists. A sandboxed shell without network egress is the most common
+cause; before accepting degradation, rerun this command once through the
+harness's network-enabled or escalated command tool. When that rerun needs
+an approval, state exactly what the approver must know: this script's only
+network contact is one GET to https://impeccable.style/api/roll whose query
+carries scope, mode, an eight-hex seed key, and a re-roll counter; no
+project files, prompts, code, or conversation context are transmitted, and
+nothing is written. An approval request naming that URL and payload judges
+the real action; a bare "run with network" invites rejection for contacting
+an unspecified domain. If the rerun is still refused, proceed with the
+grounded candidates alone; the assignment above still applies at full
+strength. Tell the user plainly that this roll
 ran degraded, with no challengers and no quality-bar boards; do not present
 the outcome as a full roll. A degraded roll changes the cards, not the
 channel: when a browser can open, present the direction on the decision page
@@ -490,15 +429,46 @@ ${buildIndex} of your own grounded list; seed key ${key}.
 `;
   }
 
-  const stagings = Array.isArray(data.stagings)
-    ? data.stagings
-    : data.staging ? [data.staging] : [];
-  const stagingBlock = stagings.length > 0
-    ? `\n${scope === 'direction' ? 'FIRST-SURFACE STAGING INPUTS (identity-free; test them with shortlisted worlds and keep world plus staging one decision):' : 'STAGING CHALLENGERS (identity-free; dress them in the committed visual identity before judging):'}
-${stagings.map((staging, index) => renderStaging(staging, index)).join('\n')}
-Stagings organize attention, sequence, and manipulation; they never bring a
-palette, typeface, or material. Use them as serious alternatives to the model's
-habitual composition, but keep only structures that strengthen this product.\n`
+  // Field order is the migration: `compositions` is current, `stagings` is what
+  // the API emitted while these were called stagings, and `staging` is the
+  // single-pick shape from before it dealt three. Older installs keep working.
+  // Compositions are pulled from the deal until the expanded catalog is
+  // ready for prime time: the current pool crowds the decision more than it
+  // widens it. IMPECCABLE_COMPOSITIONS=1 re-enables rendering for catalog
+  // development; the draw machinery, axes, and grain report stay intact.
+  const compositionsEnabled = process.env.IMPECCABLE_COMPOSITIONS === '1';
+  const compositions = !compositionsEnabled ? []
+    : Array.isArray(data.compositions)
+      ? data.compositions
+      : Array.isArray(data.stagings)
+        ? data.stagings
+        : data.staging ? [data.staging] : [];
+  // The grain report. A top-up keeps the deal at three, which is right, but it
+  // must not read as three on-target inputs: a flow request answered entirely by
+  // view-grain compositions means the model has to derive the flow's own
+  // structure and borrow only their sequence law. Silence here would reproduce
+  // the exact failure this axis exists to fix.
+  const match = data.compositionMatch ?? null;
+  const grainNote = (() => {
+    if (!match?.grain) return '';
+    if (match.grainAvailable === 0) {
+      return `\nNONE of these sit at the requested ${match.grain} grain, because the catalog holds no ${match.grain}-grain composition yet. Derive that structure yourself and borrow only their sequence and attention laws.`;
+    }
+    if (match.atGrain === 0) {
+      return `\nNONE of these sit at the requested ${match.grain} grain, though ${match.grainAvailable} exist; these were topped up from the rest of the register. Treat their structure as borrowed.`;
+    }
+    if (match.atGrain < compositions.length) {
+      return `\n${match.atGrain} of ${compositions.length} sit at the requested ${match.grain} grain; the rest were topped up from the register and their structure is borrowed.`;
+    }
+    return '';
+  })();
+  const compositionBlock = compositions.length > 0
+    ? `\n${scope === 'direction' ? 'FIRST-SURFACE COMPOSITION INPUTS (identity-free; test them with shortlisted worlds and keep world plus composition one decision):' : 'COMPOSITION CHALLENGERS (identity-free; dress them in the committed visual identity before judging):'}
+${compositions.map((composition, index) => renderComposition(composition, index)).join('\n')}
+Each one asks the same question of this build: what is the cleverest way to
+present, organize, or make interactive the problem in front of you? They carry
+structure only, never a palette, typeface, or material. Treat them as serious
+rivals to your habitual layout, and keep only what makes this product clearer.${grainNote}\n`
     : '';
   const rerollBlock = reroll > 0
     ? `RE-ROLL ROUND ${reroll}: every candidate presented in earlier rounds, grounded
@@ -519,7 +489,7 @@ ${rerollBlock}ASSIGNED INDEX: ${buildIndex}
   the user or the brief. Never expose assignment metadata in user-facing labels.
 CHALLENGERS:
 ${data.challengers.map(renderChallenger).join('\n')}
-${stagingBlock}${challengerInstruction}
+${compositionBlock}${challengerInstruction}
 When you can view images, open the QUALITY BAR board and hero for any
 challenger you weigh seriously and for the world you build. They exist as a
 craft bar, the finish level and commitment the build is expected to reach,
@@ -538,6 +508,8 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
   const scopeIdx = args.indexOf('--scope');
   const rerollIdx = args.indexOf('--reroll');
   const modeIdx = args.indexOf('--mode');
+  const grainIdx = args.indexOf('--grain');
+  const platformIdx = args.indexOf('--platform');
   const candidateCountIdx = args.indexOf('--candidate-count');
   const chosenIdx = args.indexOf('--chosen');
   try {
@@ -571,6 +543,8 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
           : (process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex')),
         reroll: rerollIdx !== -1 ? Number(args[rerollIdx + 1]) : 0,
         mode: modeIdx !== -1 ? args[modeIdx + 1] : null,
+        grain: grainIdx !== -1 ? args[grainIdx + 1] : null,
+        platform: platformIdx !== -1 ? args[platformIdx + 1] : null,
         candidateCount: candidateCountIdx !== -1 ? Number(args[candidateCountIdx + 1]) : 7,
       }));
     }

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

@@ -22,7 +22,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { loadContext, extractPlatform } from './context.mjs';
-import { getCritiqueDir } from './lib/impeccable-paths.mjs';
+import { readLatestSnapshotAcrossTargets } from './critique-storage.mjs';
 
 /** Is there code here at all, or just context files / an empty repo? */
 function hasCode(cwd) {
@@ -34,23 +34,13 @@ function hasCode(cwd) {
 }
 
 /**
- * The most recent critique snapshot across all targets. Filenames are
- * timestamp-prefixed (`<iso>__<slug>.md`), so a lexical sort is chronological.
- * Parses the small frontmatter for score + P0/P1 counts.
+ * Summarize the most recent critique snapshot across all targets.
  */
 function latestCritique(cwd) {
   try {
-    const dir = getCritiqueDir(cwd);
-    if (!fs.existsSync(dir)) return null;
-    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
-    if (!files.length) return null;
-    const newest = files[files.length - 1];
-    const text = fs.readFileSync(path.join(dir, newest), 'utf-8');
-    const front = text.split('---')[1] || '';
-    const get = (k) => {
-      const m = front.match(new RegExp(`^${k}:\\s*(.+)$`, 'm'));
-      return m ? m[1].trim() : null;
-    };
+    const latest = readLatestSnapshotAcrossTargets({ cwd });
+    if (!latest) return null;
+    const get = (key) => latest.meta[key] ?? null;
     const num = (v) => {
       const n = Number(v);
       return Number.isFinite(n) ? n : null;
@@ -61,7 +51,7 @@ function latestCritique(cwd) {
       p0: num(get('p0')),
       p1: num(get('p1')),
       timestamp: get('timestamp'),
-      file: path.relative(cwd, path.join(dir, newest)),
+      file: path.relative(cwd, latest.path),
     };
   } catch {
     return null;

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

@@ -27,6 +27,7 @@
  * shape rather than the markdown block.
  */
 import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -1146,6 +1147,7 @@ async function cli() {
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
+    appendImageToolsDirective(parts);
     appendStalenessDirective(parts, ctx, cliOptions);
     if (updateDirective) parts.push(updateDirective);
     process.stdout.write(parts.join('\n\n---\n\n') + '\n');
@@ -1180,6 +1182,7 @@ async function cli() {
       `# NATIVE PLATFORM REFERENCE: ${reference.name.toUpperCase()} (reference/${reference.name}.md)\n\n${reference.content.trim()}`,
     );
   }
+  appendImageToolsDirective(parts);
   appendStalenessDirective(parts, ctx, cliOptions);
   if (!ctx.platform) {
     // A `## Platform` section that names something we don't recognize (a
@@ -1275,9 +1278,10 @@ function appendImageGenDirective(parts) {
   if (!process.env.OPENAI_API_KEY) return;
   const scriptsPath = path.dirname(fileURLToPath(import.meta.url));
   parts.push([
-    'IMAGE_GEN_AVAILABLE: An OpenAI key is present, so image generation works even without a harness-native image tool:',
-    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render).`,
-    'Prefer the harness-native image tool when one exists. Visualizing a direction before building it measurably strengthens the result.',
+    'IMAGE_GEN_AVAILABLE: your harness-native image tool is always the first choice for generation; use it whenever one exists.',
+    'This environment also carries an OpenAI key as the fallback for harnesses with no native tool:',
+    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render, and never reach for it when a native tool exists).`,
+    'Visualizing a direction before building it measurably strengthens the result.',
   ].join(' '));
 }
 
@@ -1332,6 +1336,19 @@ function appendDetectorFallback(parts, ctx) {
 // markdown already in memory, a bounded set of stats, or one of the small JSON
 // files the boot reads regardless. The deep pass (git drift, token divergence,
 // cross-workspace sweep) belongs to the doctor command, not to every session.
+// One boot-time probe replaces every session re-deriving its image toolchain:
+// harnesses and OSes differ (cwebp, sips on macOS, magick, ffmpeg), and the
+// agent should read this line instead of running command -v per image.
+function appendImageToolsDirective(parts) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const found = ['cwebp', 'sips', 'magick', 'ffmpeg'].filter((tool) => {
+    try { return spawnSync(probe, [tool], { stdio: 'ignore' }).status === 0; } catch { return false; }
+  });
+  parts.push(found.length
+    ? `IMAGE_TOOLS: available image converters on this machine: ${found.join(', ')}. Use the first suitable one; never probe again this session.`
+    : 'IMAGE_TOOLS: no image converter found (cwebp, sips, magick, ffmpeg). Ship PNG output unconverted rather than probing per image.');
+}
+
 function appendStalenessDirective(parts, ctx, options) {
   const projectRoot = ctx.projectRoot || process.cwd();
   if (stalenessCheckDisabled([projectRoot, ctx.repoRoot])) return;

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

@@ -105,28 +105,37 @@ function parseFrontmatter(text) {
 }
 
 /**
- * Return all snapshot files for `slug`, sorted oldest → newest.
+ * Return snapshot files matching `suffix`, sorted oldest → newest.
  */
-function listSnapshotsForSlug(slug, cwd) {
+const SNAPSHOT_FILENAME = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z__.+\.md$/;
+
+function listSnapshots(suffix, cwd) {
   const dir = getCritiqueDir(cwd);
   if (!fs.existsSync(dir)) return [];
-  const suffix = `__${slug}.md`;
   return fs.readdirSync(dir)
-    .filter((f) => f.endsWith(suffix))
+    .filter((f) => SNAPSHOT_FILENAME.test(f) && f.endsWith(suffix))
     .sort()
     .map((f) => path.join(dir, f));
 }
 
+function readLatestSnapshotMatching(suffix, cwd) {
+  const filePath = listSnapshots(suffix, cwd).at(-1);
+  if (!filePath) return null;
+  const body = fs.readFileSync(filePath, 'utf-8');
+  return { path: filePath, body, meta: parseFrontmatter(body) };
+}
+
 /**
  * Return the most recent snapshot for `slug`, or null. Polish reads this
  * to find its fix backlog when the slug matches.
  */
 export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
-  const all = listSnapshotsForSlug(slug, cwd);
-  if (!all.length) return null;
-  const latest = all[all.length - 1];
-  const body = fs.readFileSync(latest, 'utf-8');
-  return { path: latest, body, meta: parseFrontmatter(body) };
+  return readLatestSnapshotMatching(`__${slug}.md`, cwd);
+}
+
+/** Return the most recent snapshot across all targets, or null. */
+export function readLatestSnapshotAcrossTargets({ cwd = process.cwd() } = {}) {
+  return readLatestSnapshotMatching('.md', cwd);
 }
 
 /**
@@ -134,7 +143,7 @@ export function readLatestSnapshot(slug, { cwd = process.cwd() } = {}) {
  * Critique appends a one-line trend to its output using this.
  */
 export function readTrend(slug, { limit = 5, cwd = process.cwd() } = {}) {
-  const all = listSnapshotsForSlug(slug, cwd);
+  const all = listSnapshots(`__${slug}.md`, cwd);
   const slice = all.slice(-limit);
   return slice.map((file) => parseFrontmatter(fs.readFileSync(file, 'utf-8')));
 }

.agents/skills/impeccable/scripts/detector/design-system.mjs

@@ -142,10 +142,73 @@ function stripInlineYamlComment(s) {
   return s;
 }
 
+// YAML double-quoted scalars process backslash escapes. Stripping the outer
+// quotes without unescaping leaves them in place, so a nested font family like
+//   fontFamily: "\"IBM Plex Sans\", system-ui, sans-serif"
+// reaches allowedFonts as '\"ibm plex sans' and never matches the same family
+// declared in CSS. Scanner instead of a regex: the escape set is small and the
+// backslash handling stays readable.
+// The full YAML 1.2 double-quote escape set (spec section 5.7).
+const YAML_SIMPLE_ESCAPES = {
+  '0': '\0',
+  a: '\x07',
+  b: '\b',
+  t: '\t',
+  n: '\n',
+  v: '\v',
+  f: '\f',
+  r: '\r',
+  e: '\x1b',
+  ' ': ' ',
+  '"': '"',
+  '/': '/',
+  '\\': '\\',
+  N: '\u0085',
+  _: '\u00a0',
+  L: '\u2028',
+  P: '\u2029',
+};
+const YAML_HEX_ESCAPE_LENGTHS = { x: 2, u: 4, U: 8 };
+
+function unescapeYamlDoubleQuoted(body) {
+  let out = '';
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch !== '\\' || i === body.length - 1) {
+      out += ch;
+      continue;
+    }
+    const next = body[i + 1];
+    if (Object.prototype.hasOwnProperty.call(YAML_SIMPLE_ESCAPES, next)) {
+      out += YAML_SIMPLE_ESCAPES[next];
+      i++;
+      continue;
+    }
+    // \xNN, \uNNNN, \UNNNNNNNN. Malformed or out-of-range sequences stay
+    // literal rather than corrupting the rest of the scalar.
+    const hexLen = YAML_HEX_ESCAPE_LENGTHS[next];
+    if (hexLen) {
+      const hex = body.slice(i + 2, i + 2 + hexLen);
+      const codePoint = hex.length === hexLen && /^[0-9a-fA-F]+$/.test(hex) ? parseInt(hex, 16) : -1;
+      if (codePoint >= 0 && codePoint <= 0x10ffff) {
+        out += String.fromCodePoint(codePoint);
+        i += 1 + hexLen;
+        continue;
+      }
+    }
+    out += ch;
+  }
+  return out;
+}
+
 function parseScalar(raw) {
   const s = raw.trim();
-  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-    return s.slice(1, -1);
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return unescapeYamlDoubleQuoted(s.slice(1, -1));
+  }
+  // Single-quoted YAML escapes only the quote itself, by doubling it.
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1).split("''").join("'");
   }
   if (s === 'true') return true;
   if (s === 'false') return false;

.agents/skills/impeccable/scripts/detector/detect-antipatterns-browser.js

@@ -139,16 +139,6 @@ const ANTIPATTERNS = [
     skillSection: 'Typography',
     skillGuideline: 'overused fonts like Inter',
   },
-  {
-    id: 'single-font',
-    category: 'slop',
-    scopes: ['type'],
-    name: 'Single font without hierarchy',
-    description:
-      'Only one font family is used for the entire page. A single family can work when weight and size contrast carry the hierarchy; otherwise pair a distinctive display font with a refined body font.',
-    skillSection: 'Typography',
-    skillGuideline: 'only one font family for the entire page',
-  },
   {
     id: 'flat-type-hierarchy',
     category: 'slop',
@@ -1863,9 +1853,11 @@ function collectMarqueeKeyframes(content) {
 // bound to a keyframe loop that travels a large horizontal distance.
 // Rotation/opacity animations never qualify (no X travel); JS-driven
 // carousels with user controls have no infinite CSS X-loop to match.
-function scanCssTextForMarquee(content) {
+// `content` is CSS-bearing text; `markup` (defaulting to the same string
+// for single-corpus callers) is where the <marquee> tag itself lives.
+function scanCssTextForMarquee(content, markup = content) {
   const findings = [];
-  if (/<marquee\b/i.test(content)) {
+  if (/<marquee\b/i.test(markup)) {
     findings.push({ id: 'marquee', snippet: '<marquee> element' });
   }
   const marqueeKeyframes = collectMarqueeKeyframes(content);
@@ -2044,10 +2036,14 @@ function selectorHitsLandmark(content, selector, ranges) {
 // element sits inside a header/nav landmark is the hero liveness cliché
 // and is promoted to error severity; occurrences elsewhere keep the
 // registry default severity.
-function scanCssTextForPulsingDot(content) {
+//
+// `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
+// to the same string for single-corpus callers like the regex source
+// engine — is where landmark ranges and Tailwind class attributes live.
+function scanCssTextForPulsingDot(content, markup = content) {
   const customProps = collectCssCustomProps(content);
   const keyframes = collectPulseKeyframes(content);
-  const heroRanges = landmarkSourceRanges(content);
+  const heroRanges = landmarkSourceRanges(markup);
   const findings = [];
   const seen = new Set();
 
@@ -2096,7 +2092,7 @@ function scanCssTextForPulsingDot(content) {
 
     if (seen.has(selector)) continue;
     seen.add(selector);
-    const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
+    const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
     findings.push({
       id: 'pulsing-dot',
       snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -2106,10 +2102,11 @@ function scanCssTextForPulsingDot(content) {
   }
 
   // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
-  // element declared entirely in the class attribute.
+  // element declared entirely in the class attribute. Scanned in the markup
+  // corpus so the match index lines up with the landmark ranges.
   const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
   let cm;
-  while ((cm = classRe.exec(content)) !== null) {
+  while ((cm = classRe.exec(markup)) !== null) {
     const cls = cm[1] || cm[2] || '';
     const anim = cls.match(/\banimate-(ping|pulse)\b/);
     if (!anim) continue;
@@ -2190,20 +2187,64 @@ function scanHtmlForShapeAssembledIllustration(html) {
   return findings;
 }
 
+// Scoped scan corpora for the page-level pattern checks. CSS-property
+// regexes run over the whole source string fire on documentation ABOUT
+// css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
+// comments — so the checks scan only the strings that actually style the
+// page:
+//   styleText — <style> block contents plus style="…" attribute values.
+//     Attribute values keep their `style="…"` form so block-scoped
+//     scanners (grid background) keep treating each attribute as one
+//     declaration block, exactly as they did against raw source. Engines
+//     that already read more CSS (linked stylesheets) prepend it.
+//   classText — class attribute values, for utility-class scans.
+// Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
+// landmark ranges) and rendered-text checks (theater phrases) keep the
+// full source. This extraction serves callers without a parsed document
+// (the browser bundle scanning outerHTML); attribute reads are tag-scoped
+// so escaped code samples (&lt;div style="…"&gt;) never contribute. The
+// static engine passes richer corpora built from its parsed document.
+// Bare CSS input (no markup at all) is its own style text, which keeps
+// direct checkHtmlPatterns(css) callers behaving as before.
+function buildHtmlPatternCorpora(html) {
+  const source = String(html || '');
+  if (!/<[a-zA-Z!/]/.test(source)) {
+    return { styleText: source, classText: source };
+  }
+  const styleParts = [];
+  const classParts = [];
+  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let m;
+  while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
+  const tagRe = /<[a-zA-Z][^>]*>/g;
+  while ((m = tagRe.exec(source)) !== null) {
+    const tag = m[0];
+    const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
+    if (sm) styleParts.push(`style=${sm[1]}`);
+    const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+    if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
+  }
+  return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
+}
+
 /**
  * Regex-on-HTML checks shared between browser and Node page-level detection.
- * These don't need DOM access, just the raw HTML string.
+ * These don't need DOM access, just the raw HTML string. CSS-property and
+ * utility-class patterns scan the scoped corpora (styleText / classText —
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
+ * markup-shaped and rendered-text checks read the full source.
  */
-function checkHtmlPatterns(html) {
+function checkHtmlPatterns(html, corpora) {
+  const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
   const findings = [];
 
   // --- Color ---
 
   // AI color palette: purple/violet
   const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
-  if (purpleHexRe.test(html)) {
+  if (purpleHexRe.test(styleText)) {
     const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
-    if (purpleTextRe.test(html)) {
+    if (purpleTextRe.test(styleText)) {
       findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
     }
   }
@@ -2211,15 +2252,15 @@ function checkHtmlPatterns(html) {
   // Gradient text (background-clip: text + gradient)
   const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
   let gm;
-  while ((gm = gradientRe.exec(html)) !== null) {
+  while ((gm = gradientRe.exec(styleText)) !== null) {
     const start = Math.max(0, gm.index - 200);
-    const context = html.substring(start, gm.index + gm[0].length + 200);
+    const context = styleText.substring(start, gm.index + gm[0].length + 200);
     if (/gradient/i.test(context)) {
       findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
       break;
     }
   }
-  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
+  if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
     findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
   }
 
@@ -2228,10 +2269,10 @@ function checkHtmlPatterns(html) {
   // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
   // (no border property involved, so the element-level border checks and
   // the border-left regexes never see it).
-  findings.push(...scanCssTextForPseudoStripe(html));
+  findings.push(...scanCssTextForPseudoStripe(styleText));
 
   // Side-tab accent stripe drawn as a single-edge inset box-shadow.
-  findings.push(...scanCssTextForInsetStripe(html));
+  findings.push(...scanCssTextForInsetStripe(styleText));
 
   // --- Layout ---
 
@@ -2239,20 +2280,20 @@ function checkHtmlPatterns(html) {
   const spacingValues = [];
   const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
   let sm;
-  while ((sm = spacingRe.exec(html)) !== null) {
+  while ((sm = spacingRe.exec(styleText)) !== null) {
     const v = parseInt(sm[1], 10);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
   const gapRe = /gap\s*:\s*(\d+)px/gi;
-  while ((sm = gapRe.exec(html)) !== null) {
+  while ((sm = gapRe.exec(styleText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10));
   }
   const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
-  while ((sm = twSpaceRe.exec(html)) !== null) {
+  while ((sm = twSpaceRe.exec(classText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10) * 4);
   }
   const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
-  while ((sm = remSpacingRe.exec(html)) !== null) {
+  while ((sm = remSpacingRe.exec(styleText)) !== null) {
     const v = Math.round(parseFloat(sm[1]) * 16);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
@@ -2276,7 +2317,7 @@ function checkHtmlPatterns(html) {
 
   // Bounce/elastic animation names
   const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
-  const bounceMatch = bounceRe.exec(html);
+  const bounceMatch = bounceRe.exec(styleText);
   if (bounceMatch) {
     const animationToken = bounceMatch[1]
       .split(/[,\s]+/)
@@ -2287,7 +2328,7 @@ function checkHtmlPatterns(html) {
   // Overshoot cubic-bezier
   const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
   let bm;
-  while ((bm = bezierRe.exec(html)) !== null) {
+  while ((bm = bezierRe.exec(styleText)) !== null) {
     const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
     if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
       findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
@@ -2298,7 +2339,7 @@ function checkHtmlPatterns(html) {
   // Layout property transitions
   const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
   let tm;
-  while ((tm = transRe.exec(html)) !== null) {
+  while ((tm = transRe.exec(styleText)) !== null) {
     const val = tm[1].toLowerCase();
     if (/\ball\b/.test(val)) continue;
     const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -2308,30 +2349,32 @@ function checkHtmlPatterns(html) {
     }
   }
 
-  // Pulsing status dots (tiny circular elements on infinite pulse animations)
-  findings.push(...scanCssTextForPulsingDot(html));
+  // Pulsing status dots (tiny circular elements on infinite pulse animations).
+  // The CSS rules come from styleText; the markup carries the landmark
+  // ranges and Tailwind class attributes.
+  findings.push(...scanCssTextForPulsingDot(styleText, html));
 
   // Shape-assembled illustrations (large pictorial SVGs built from primitives)
   findings.push(...scanHtmlForShapeAssembledIllustration(html));
 
   // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
-  findings.push(...scanCssTextForMarquee(html));
+  findings.push(...scanCssTextForMarquee(styleText, html));
 
   // --- Dark glow / chromatic halo shadows ---
 
-  const glowHits = scanCssTextForGlow(html);
+  const glowHits = scanCssTextForGlow(styleText);
   if (glowHits.length > 0) {
     findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
   }
 
   // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
-  const haloHits = scanCssTextForRadialHalo(html);
+  const haloHits = scanCssTextForRadialHalo(styleText);
   if (haloHits.length > 0) {
     findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
   }
 
   // --- Generated-UI tells: repeating-gradient stripes ---
-  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
+  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(styleText)) {
     findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
   }
 
@@ -2348,7 +2391,7 @@ function checkHtmlPatterns(html) {
   // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
   // nested parens, so match the hairline stop directly rather than parsing
   // whole gradient layers.
-  const gridHits = scanCssTextForGridBackground(html);
+  const gridHits = scanCssTextForGridBackground(styleText);
   if (gridHits.length > 0) {
     findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
   }
@@ -2370,7 +2413,7 @@ function checkHtmlPatterns(html) {
   // hover:rotate / hover:translate utility on an <img>. Each distinct
   // mechanism is its own finding.
   const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
-  if (imgHoverCss.test(html)) {
+  if (imgHoverCss.test(styleText)) {
     findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
   }
   const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
@@ -3271,7 +3314,11 @@ function isKickerCandidate(opts) {
     || isSmallCaps;
   if (!isUppercased) return false;
   if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
-  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
+  // Proportional only, no absolute floor: the wild's most common recipe is
+  // 0.08em at a sub-13px size, which computes to under 1px and sailed past
+  // the old Math.max(1, ...) floor (observed live: a page whose kickers were
+  // literally class="kicker" produced zero findings).
+  const minTrackedSpacing = kickerFontSize * 0.06;
   if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
   return true;
 }
@@ -4655,12 +4702,6 @@ function checkTypography() {
       if (isBrandFontOnOwnDomain(font)) continue;
       findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
     }
-
-    // Single-font check: only one distinct primary font across all text
-    if (fontUsage.size === 1) {
-      const only = [...fontUsage.keys()][0];
-      findings.push({ type: 'single-font', detail: `only font used is ${only}` });
-    }
   }
 
   const sizes = new Set();
@@ -4922,14 +4963,6 @@ function checkPageTypography(doc, win) {
     findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
   }
 
-  // Single font
-  if (fonts.size === 1) {
-    const els = doc.querySelectorAll('*');
-    if (els.length >= 20) {
-      findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
-    }
-  }
-
   // Flat type hierarchy
   const sizes = new Set();
   const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');

.agents/skills/impeccable/scripts/detector/detect-antipatterns.mjs

@@ -35,6 +35,7 @@ export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.m
 export { detectText, extractStyleBlocks, extractCSSinJS } from './engines/regex/detect-text.mjs';
 export {
   walkDir,
+  hasScannableExtension,
   SCANNABLE_EXTENSIONS,
   SKIP_DIRS,
   buildImportGraph,

.agents/skills/impeccable/scripts/detector/engines/browser/detect-url.mjs

@@ -7,6 +7,38 @@ import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profi
 import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
 import { checkContentHiddenAtRest } from '../../rules/checks.mjs';
 
+// On Windows, puppeteer's bundled Chrome lives in a user-writable cache
+// directory. Its GPU process can be denied (STATUS_ACCESS_DENIED) by security
+// software or the GPU sandbox because it launches from an untrusted path.
+// Chrome then crash-loops the GPU process, and each relaunch briefly flashes a
+// compositor surface, the black window users report during `detect <url>`
+// (issue #372). The system-installed Chrome runs from a trusted location with a
+// healthy GPU, so channel:'chrome' avoids the crash entirely; both use hardware
+// GPU, so contrast measurement is unaffected. Scope this to Windows only: other
+// platforms do not have the bug, so they keep the pinned bundled build for
+// consistent measurement across machines. Fall back to bundled when the switch
+// fails (Chrome not installed, or channel resolution fails). If the bundled
+// launch then also fails, surface the original system-Chrome error as the
+// cause so the real failure is not lost.
+async function launchBrowser(puppeteer, { headless = true, args = [] } = {}) {
+  let channelError;
+  if (process.platform === 'win32') {
+    try {
+      return await puppeteer.default.launch({ channel: 'chrome', headless, args });
+    } catch (err) {
+      // System Chrome unavailable or unlaunchable; fall through to the bundled
+      // browser, but keep the error in case the fallback fails too.
+      channelError = err;
+    }
+  }
+  try {
+    return await puppeteer.default.launch({ headless, args });
+  } catch (err) {
+    if (channelError && err && err.cause === undefined) err.cause = channelError;
+    throw err;
+  }
+}
+
 // Reveal sweep + invisible-text measurement for the content-hidden-at-rest
 // rule. Scrolls through the document with instant jumps (bypasses CSS
 // scroll-behavior: smooth) so IntersectionObserver / scroll reveal handlers
@@ -178,7 +210,7 @@ async function detectUrl(url, options = {}) {
     phase: 'load',
     ruleId: 'launch-browser',
     target: url,
-  }, () => puppeteer.default.launch({ headless: true, args: launchArgs }));
+  }, () => launchBrowser(puppeteer, { headless: options?.headless ?? true, args: launchArgs }));
   const page = await profileStepAsync(profile, {
     engine: 'browser',
     phase: 'load',
@@ -312,7 +344,7 @@ async function createBrowserDetector(options = {}) {
     throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
   }
   const launchArgs = options.launchArgs || (process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : []);
-  const browser = options.browser || await puppeteer.default.launch({
+  const browser = options.browser || await launchBrowser(puppeteer, {
     headless: options.headless ?? true,
     args: launchArgs,
   });
@@ -337,4 +369,4 @@ async function createBrowserDetector(options = {}) {
   };
 }
 
-export { runVisualContrastFallback, detectUrl, createBrowserDetector };
+export { runVisualContrastFallback, detectUrl, createBrowserDetector, launchBrowser };

.agents/skills/impeccable/scripts/detector/engines/regex/detect-text.mjs

@@ -12,7 +12,8 @@ import { profileFindings, profileStep } from '../../profile/profiler.mjs';
 // Regex fallback (non-HTML files: CSS, JSX, TSX, etc.)
 // ---------------------------------------------------------------------------
 
-const hasRounded = (line) => /\brounded(?:-\w+)?\b/.test(line);
+const hasRounded = (line) =>
+  /\brounded(?:-\w+)?\b/.test(line.replace(/\brounded-none\b/g, ''));
 const hasBorderRadius = (line) => /border-radius/i.test(line);
 const isSafeElement = (line) => /<(?:blockquote|nav[\s>]|pre[\s>]|code[\s>]|a\s|input[\s>]|span[\s>])/i.test(line);
 
@@ -40,6 +41,221 @@ function shouldRunPageAnalyzers(content, filePath) {
   return !ext || PAGE_ANALYZER_EXTS.has(ext);
 }
 
+const JS_SOURCE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const REGEX_PREFIX_KEYWORDS = new Set(['await', 'case', 'default', 'delete', 'do', 'else', 'in', 'instanceof', 'new', 'of', 'return', 'throw', 'typeof', 'void', 'yield']);
+const BLOCK_BRACE_PREFIX_KEYWORDS = new Set(['do', 'else', 'finally', 'try']);
+
+function isInsideOpeningJsxTag(source) {
+  const tagStart = source.lastIndexOf('<');
+  if (tagStart === -1 || !/^<[A-Za-z][\w.:-]*/.test(source.slice(tagStart))) return false;
+
+  let quote = '';
+  for (let cursor = tagStart + 1; cursor < source.length; cursor++) {
+    const char = source[cursor];
+    if (quote) {
+      if (char === '\\') cursor++;
+      else if (char === quote) quote = '';
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === '>') {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Blank JavaScript comments without moving any following source. Regex
+ * findings keep their original line numbers, while prose examples inside
+ * comments cannot masquerade as rendered markup.
+ */
+function stripJsComments(content, options = {}) {
+  let state = 'code';
+  let output = '';
+  let lastSignificant = '';
+  let previousSignificant = '';
+  let antePreviousSignificant = '';
+  let currentWord = '';
+  let currentWordPrefix = '';
+  let wordSeparated = false;
+  let regexCharClass = false;
+  let jsxExpressionDepth = 0;
+  let lastClosedBraceKind = '';
+  const braceKinds = [];
+  const templateExpressionDepths = [];
+
+  const braceKind = (startsJsxExpression = false) => (
+    !startsJsxExpression && (
+      !lastSignificant ||
+      lastSignificant === ')' ||
+      lastSignificant === ';' ||
+      lastSignificant === '}' ||
+      (previousSignificant === '=' && lastSignificant === '>') ||
+      BLOCK_BRACE_PREFIX_KEYWORDS.has(currentWord)
+    ) ? 'block' : 'expression'
+  );
+
+  const recordSignificant = (char) => {
+    if (/\s/.test(char)) {
+      wordSeparated = true;
+      return;
+    }
+    const isWordChar = /[\w$]/.test(char);
+    if (isWordChar && (wordSeparated || !currentWord)) {
+      currentWord = '';
+      currentWordPrefix = lastSignificant;
+    } else if (!isWordChar) {
+      currentWordPrefix = '';
+    }
+    wordSeparated = false;
+    antePreviousSignificant = previousSignificant;
+    previousSignificant = lastSignificant;
+    lastSignificant = char;
+    currentWord = isWordChar ? currentWord + char : '';
+  };
+
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (state === 'line-comment') {
+      if (char === '\n') {
+        output += char;
+        state = 'code';
+      } else {
+        output += ' ';
+      }
+      continue;
+    }
+
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        output += '  ';
+        i++;
+        state = 'code';
+      } else {
+        output += char === '\n' ? '\n' : ' ';
+      }
+      continue;
+    }
+
+    if (state === 'regex') {
+      output += char;
+      if (char === '\\' && next) {
+        output += next;
+        i++;
+      } else if (char === '[') {
+        regexCharClass = true;
+      } else if (char === ']') {
+        regexCharClass = false;
+      } else if (char === '/' && !regexCharClass) {
+        state = 'code';
+        recordSignificant('/');
+      }
+      continue;
+    }
+
+    if (state === 'template' && char === '$' && next === '{') {
+      output += '${';
+      i++;
+      recordSignificant('$');
+      recordSignificant('{');
+      templateExpressionDepths.push(1);
+      braceKinds.push('expression');
+      if (jsxExpressionDepth) jsxExpressionDepth++;
+      state = 'code';
+      continue;
+    }
+
+    if (state !== 'code') {
+      output += char;
+      if (char === '\\' && next) {
+        output += next;
+        i++;
+      } else if (
+        (state === 'single-quote' && char === "'") ||
+        (state === 'double-quote' && char === '"') ||
+        (state === 'template' && char === '`')
+      ) {
+        state = 'code';
+        recordSignificant(char);
+      }
+      continue;
+    }
+
+    const jsxUrlSeparator = options.jsx && char === '/' && next === '/' &&
+      jsxExpressionDepth === 0 &&
+      (output.endsWith('http:') ||
+        output.endsWith('https:') ||
+        (/<[A-Za-z](?:[^>]*[^/])?>[^<]*$/.test(output.slice(output.lastIndexOf('\n') + 1)) &&
+          /^[\w.-]+\.[A-Za-z]{2,}(?=[:/?#\s<]|$)/.test(content.slice(i + 2))));
+    const afterPostfixUpdate = (lastSignificant === '+' || lastSignificant === '-') &&
+      previousSignificant === lastSignificant &&
+      antePreviousSignificant !== lastSignificant;
+    if (char === '/' && next === '/' && jsxUrlSeparator) {
+      output += '//';
+      i++;
+      recordSignificant('/');
+      recordSignificant('/');
+    } else if (char === '/' && next === '/') {
+      output += '  ';
+      i++;
+      state = 'line-comment';
+    } else if (char === '/' && next === '*') {
+      output += '  ';
+      i++;
+      state = 'block-comment';
+    } else if (templateExpressionDepths.length && char === '{') {
+      output += char;
+      templateExpressionDepths[templateExpressionDepths.length - 1]++;
+      braceKinds.push(braceKind());
+      if (jsxExpressionDepth) jsxExpressionDepth++;
+      recordSignificant(char);
+    } else if (templateExpressionDepths.length && char === '}') {
+      output += char;
+      const depthIndex = templateExpressionDepths.length - 1;
+      templateExpressionDepths[depthIndex]--;
+      lastClosedBraceKind = braceKinds.pop() || '';
+      if (jsxExpressionDepth) jsxExpressionDepth--;
+      recordSignificant(char);
+      if (templateExpressionDepths[depthIndex] === 0) {
+        templateExpressionDepths.pop();
+        state = 'template';
+      }
+    } else if (
+      char === '/' &&
+      (!lastSignificant ||
+        (/[=([{!?:;,&|+\-*%^~<>]/.test(lastSignificant) && !afterPostfixUpdate) ||
+        (lastSignificant === '}' && lastClosedBraceKind === 'block') ||
+        (previousSignificant === '=' && lastSignificant === '>') ||
+        (currentWordPrefix !== '.' && REGEX_PREFIX_KEYWORDS.has(currentWord)))
+    ) {
+      output += char;
+      state = 'regex';
+      regexCharClass = false;
+    } else {
+      output += char;
+      const startsJsxExpression = options.jsx && char === '{' && jsxExpressionDepth === 0 &&
+        (/<[A-Za-z](?:[^>]*[^/])?>[^<]*$/.test(output.slice(output.lastIndexOf('\n') + 1, -1)) ||
+          isInsideOpeningJsxTag(output.slice(0, -1)));
+      if (char === '{') braceKinds.push(braceKind(startsJsxExpression));
+      else if (char === '}') lastClosedBraceKind = braceKinds.pop() || '';
+      if (char === '{' && (jsxExpressionDepth || startsJsxExpression)) jsxExpressionDepth++;
+      else if (char === '}' && jsxExpressionDepth) jsxExpressionDepth--;
+      recordSignificant(char);
+      if (char === "'") state = 'single-quote';
+      else if (char === '"') state = 'double-quote';
+      else if (char === '`') state = 'template';
+    }
+  }
+
+  return output;
+}
+
+function stripCssComments(content) {
+  return content.replace(/\/\*[\s\S]*?\*\//g, comment => comment.replace(/[^\n]/g, ' '));
+}
+
 function firstOverusedGoogleFont(text) {
   return extractGoogleFontFamilies(text).find(f => OVERUSED_FONTS.has(f)) || '';
 }
@@ -240,24 +456,6 @@ const REGEX_MATCHERS = [
 ];
 
 const REGEX_ANALYZERS = [
-  // Single font
-  (content, filePath) => {
-    const fontFamilyRe = /font-family\s*:\s*([^;}]+)/gi;
-    const fonts = new Set();
-    let m;
-    while ((m = fontFamilyRe.exec(content)) !== null) {
-      for (const f of m[1].split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase())) {
-        if (f && !GENERIC_FONTS.has(f)) fonts.add(f);
-      }
-    }
-    for (const f of extractGoogleFontFamilies(content)) fonts.add(f);
-    if (fonts.size !== 1 || content.split('\n').length < 20) return [];
-    const name = [...fonts][0];
-    const lines = content.split('\n');
-    let line = 1;
-    for (let i = 0; i < lines.length; i++) { if (lines[i].toLowerCase().includes(name)) { line = i + 1; break; } }
-    return [finding('single-font', filePath, `only font used is ${name}`, line)];
-  },
   // Flat type hierarchy
   (content, filePath) => {
     const sizes = new Set();
@@ -545,18 +743,198 @@ function extractStyleBlocks(content, ext) {
 
 const CSS_IN_JS_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx']);
 
+function findQuotedStringEnd(content, start, quote) {
+  for (let cursor = start + 1; cursor < content.length; cursor++) {
+    if (content[cursor] === '\\') cursor++;
+    else if (content[cursor] === quote) return cursor;
+  }
+  return -1;
+}
+
+function findRegexLiteralEnd(content, start) {
+  let inCharacterClass = false;
+  for (let cursor = start + 1; cursor < content.length; cursor++) {
+    const char = content[cursor];
+    if (char === '\\') {
+      cursor++;
+    } else if (char === '[') {
+      inCharacterClass = true;
+    } else if (char === ']') {
+      inCharacterClass = false;
+    } else if (char === '/' && !inCharacterClass) {
+      while (/[A-Za-z]/.test(content[cursor + 1] || '')) cursor++;
+      return cursor;
+    } else if (char === '\n' || char === '\r') {
+      return -1;
+    }
+  }
+  return -1;
+}
+
+function findTemplateExpressionEnd(content, start) {
+  let depth = 1;
+  let lastSignificant = '';
+  let previousSignificant = '';
+  let antePreviousSignificant = '';
+  let currentWord = '';
+  let currentWordPrefix = '';
+  let wordSeparated = false;
+  let lastClosedBraceKind = '';
+  const braceKinds = [];
+
+  const braceKind = () => (
+    lastSignificant === ')' ||
+    lastSignificant === ';' ||
+    lastSignificant === '}' ||
+    (previousSignificant === '=' && lastSignificant === '>') ||
+    BLOCK_BRACE_PREFIX_KEYWORDS.has(currentWord)
+      ? 'block'
+      : 'expression'
+  );
+
+  const recordSignificant = (char) => {
+    if (/\s/.test(char)) {
+      wordSeparated = true;
+      return;
+    }
+    const isWordChar = /[\w$]/.test(char);
+    if (isWordChar && (wordSeparated || !currentWord)) {
+      currentWord = '';
+      currentWordPrefix = lastSignificant;
+    } else if (!isWordChar) {
+      currentWordPrefix = '';
+    }
+    wordSeparated = false;
+    antePreviousSignificant = previousSignificant;
+    previousSignificant = lastSignificant;
+    lastSignificant = char;
+    currentWord = isWordChar ? currentWord + char : '';
+  };
+
+  for (let cursor = start; cursor < content.length; cursor++) {
+    const char = content[cursor];
+    const next = content[cursor + 1];
+    const afterPostfixUpdate = (lastSignificant === '+' || lastSignificant === '-') &&
+      previousSignificant === lastSignificant &&
+      antePreviousSignificant !== lastSignificant;
+    if (char === "'" || char === '"') {
+      cursor = findQuotedStringEnd(content, cursor, char);
+      if (cursor === -1) return -1;
+      recordSignificant(')');
+    } else if (char === '/' && next === '/') {
+      const lineEnd = content.indexOf('\n', cursor + 2);
+      if (lineEnd === -1) return -1;
+      cursor = lineEnd;
+    } else if (char === '/' && next === '*') {
+      const commentEnd = content.indexOf('*/', cursor + 2);
+      if (commentEnd === -1) return -1;
+      cursor = commentEnd + 1;
+    } else if (
+      char === '/' &&
+      (!lastSignificant ||
+        (/[=([{!?:;,&|+\-*%^~<>]/.test(lastSignificant) && !afterPostfixUpdate) ||
+        (lastSignificant === '}' && lastClosedBraceKind === 'block') ||
+        (previousSignificant === '=' && lastSignificant === '>') ||
+        (currentWordPrefix !== '.' && REGEX_PREFIX_KEYWORDS.has(currentWord)))
+    ) {
+      cursor = findRegexLiteralEnd(content, cursor);
+      if (cursor === -1) return -1;
+      recordSignificant(')');
+    } else if (char === '`') {
+      cursor = findTemplateLiteralEnd(content, cursor);
+      if (cursor === -1) return -1;
+      recordSignificant(')');
+    } else if (char === '{') {
+      depth++;
+      braceKinds.push(braceKind());
+      recordSignificant(char);
+    } else if (char === '}') {
+      depth--;
+      if (depth === 0) return cursor;
+      lastClosedBraceKind = braceKinds.pop() || '';
+      recordSignificant(char);
+    } else {
+      recordSignificant(char);
+    }
+  }
+  return -1;
+}
+
+function findTemplateLiteralEnd(content, start) {
+  for (let cursor = start + 1; cursor < content.length; cursor++) {
+    const char = content[cursor];
+    if (char === '\\') {
+      cursor++;
+    } else if (char === '`') {
+      return cursor;
+    } else if (char === '$' && content[cursor + 1] === '{') {
+      cursor = findTemplateExpressionEnd(content, cursor + 2);
+      if (cursor === -1) return -1;
+    }
+  }
+  return -1;
+}
+
+function findCSSinJSTemplates(content) {
+  const templates = [];
+  const tagRe = /\b(?:styled(?:\.\w+|\([^)]+\))|css)/g;
+  let match;
+  while ((match = tagRe.exec(content)) !== null) {
+    let cursor = match.index + match[0].length;
+    while (/\s/.test(content[cursor] || '')) cursor++;
+
+    if (content[cursor] === '<') {
+      let depth = 0;
+      while (cursor < content.length) {
+        const char = content[cursor];
+        if (char === '<') depth++;
+        else if (char === '>' && content[cursor - 1] !== '=') depth--;
+        cursor++;
+        if (depth === 0) break;
+      }
+      if (depth !== 0) continue;
+      while (/\s/.test(content[cursor] || '')) cursor++;
+    }
+
+    if (content[cursor] !== '`') continue;
+    const contentStart = cursor + 1;
+    cursor = findTemplateLiteralEnd(content, cursor);
+    if (cursor === -1) continue;
+
+    templates.push({
+      tagStart: match.index,
+      contentStart,
+      contentEnd: cursor,
+    });
+    tagRe.lastIndex = cursor + 1;
+  }
+  return templates;
+}
+
 function extractCSSinJS(content, ext) {
   ext = ext.toLowerCase();
   if (!CSS_IN_JS_EXTENSIONS.has(ext)) return [];
-  const blocks = [];
-  const re = /(?:styled(?:\.\w+|\([^)]+\))|css)\s*`([\s\S]*?)`/g;
-  let m;
-  while ((m = re.exec(content)) !== null) {
-    const before = content.substring(0, m.index);
+  return findCSSinJSTemplates(content).map((template) => {
+    const before = content.substring(0, template.tagStart);
     const startLine = before.split('\n').length;
-    blocks.push({ content: m[1], startLine });
+    return {
+      content: content.slice(template.contentStart, template.contentEnd),
+      startLine,
+    };
+  });
+}
+
+function stripCssInJsComments(content, ext) {
+  if (!CSS_IN_JS_EXTENSIONS.has(ext.toLowerCase())) return content;
+  const templates = findCSSinJSTemplates(content);
+  let output = '';
+  let cursor = 0;
+  for (const template of templates) {
+    output += content.slice(cursor, template.contentStart);
+    output += stripCssComments(content.slice(template.contentStart, template.contentEnd));
+    cursor = template.contentEnd;
   }
-  return blocks;
+  return output + content.slice(cursor);
 }
 
 function runRegexMatchers(lines, filePath, lineOffset = 0, blockContext = null, options = {}) {
@@ -625,10 +1003,11 @@ const TEXT_CONTENT_ANALYZER_IDS = [
 function runTextContentAnalyzers(content, filePath, options = {}) {
   const profile = options?.profile;
   if (!shouldRunPageAnalyzers(content, filePath)) return [];
-  // The 3 text-content analyzers are at indices 3-5 in REGEX_ANALYZERS.
+  // The 3 text-content analyzers are at indices 2-4 in REGEX_ANALYZERS
+  // (single-font's removal on 2026-07-29 shifted every index down one).
   const findings = [];
   for (let i = 0; i < TEXT_CONTENT_ANALYZER_IDS.length; i++) {
-    const analyzer = REGEX_ANALYZERS[3 + i];
+    const analyzer = REGEX_ANALYZERS[2 + i];
     const ruleId = TEXT_CONTENT_ANALYZER_IDS[i];
     findings.push(...profileFindings(profile, {
       engine: 'regex',
@@ -643,8 +1022,12 @@ function runTextContentAnalyzers(content, filePath, options = {}) {
 function detectText(content, filePath, options = {}) {
   const profile = options?.profile;
   const findings = [];
-  const lines = content.split('\n');
   const ext = extFromFilePath(filePath);
+  const commentStrippedSource = JS_SOURCE_EXTS.has(ext) ? stripJsComments(content, {
+    jsx: ext === '.js' || ext === '.jsx' || ext === '.tsx',
+  }) : content;
+  const source = stripCssInJsComments(commentStrippedSource, ext);
+  const lines = source.split('\n');
 
   // Run regex matchers on the full file content (catches Tailwind classes, inline styles)
   // Enable block context for CSS files where related properties span multiple lines
@@ -677,8 +1060,8 @@ function detectText(content, filePath, options = {}) {
     phase: 'source',
     ruleId: 'codex-grid-background',
     target: filePath,
-  }, () => scanCssTextForGridBackground(content).map(hit => {
-    const line = content.substring(0, hit.index).split('\n').length;
+  }, () => scanCssTextForGridBackground(source).map(hit => {
+    const line = source.substring(0, hit.index).split('\n').length;
     return finding('codex-grid-background', filePath, hit.snippet, line);
   })));
 
@@ -714,16 +1097,17 @@ function detectText(content, filePath, options = {}) {
       phase: 'extract',
       ruleId: 'css-in-js',
       target: filePath,
-    }, () => extractCSSinJS(content, ext))
-    : extractCSSinJS(content, ext);
+    }, () => extractCSSinJS(source, ext))
+    : extractCSSinJS(source, ext);
   for (const block of cssJsBlocks) {
-    const blockLines = block.content.split('\n');
+    const blockContent = stripCssComments(block.content);
+    const blockLines = blockContent.split('\n');
     findings.push(...runRegexMatchers(blockLines, filePath, block.startLine - 1, true, {
       profile,
       phase: 'css-in-js',
     }));
-    findings.push(...scanInsetStripeCss(block.content, filePath, block.startLine - 1));
-    findings.push(...pseudoStripeFindings(block.content, block.startLine - 1));
+    findings.push(...scanInsetStripeCss(blockContent, filePath, block.startLine - 1));
+    findings.push(...pseudoStripeFindings(blockContent, block.startLine - 1));
   }
 
   if (options?.designSystem) {
@@ -749,7 +1133,6 @@ function detectText(content, filePath, options = {}) {
   // Page-level analyzers only run on full pages
   if (shouldRunPageAnalyzers(content, filePath)) {
     const analyzerIds = [
-      'single-font',
       'flat-type-hierarchy',
       'monotonous-spacing',
       'em-dash-overuse',

.agents/skills/impeccable/scripts/detector/engines/static-html/css-cascade.mjs

@@ -952,7 +952,10 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
     const rel = link.attribs?.rel || '';
     const href = link.attribs?.href || '';
     if (!/\bstylesheet\b/i.test(rel) || !href || /^(https?:)?\/\//i.test(href)) continue;
-    const cssPath = path.resolve(fileDir, href);
+    // Cache-busting hrefs (styles.css?v=3) resolve to the file, not to a
+    // literal path with the query in it; a versioned link otherwise made the
+    // whole stylesheet invisible to every element-level check.
+    const cssPath = path.resolve(fileDir, href.split(/[?#]/)[0]);
     try {
       const css = profileStep(profile, {
         engine: 'static-html',

.agents/skills/impeccable/scripts/detector/engines/static-html/detect-html.mjs

@@ -60,9 +60,6 @@ function checkStaticPageTypography(document, window) {
   for (const font of overusedFound) {
     findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
   }
-  if (fonts.size === 1 && document.querySelectorAll('*').length >= 20) {
-    findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
-  }
   const sizes = new Set();
   for (const el of document.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div')) {
     const fontSize = parseFloat(window.getComputedStyle(el).fontSize);
@@ -220,7 +217,25 @@ async function detectHtml(filePath, options = {}) {
     for (const f of runPageCheck('skipped-heading', () => checkPageQualityFromDoc(document))) {
       findings.push(finding(f.id, filePath, f.snippet));
     }
-    for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
+    // Scoped corpora for the pattern checks (see buildHtmlPatternCorpora in
+    // rules/checks.mjs): CSS-property regexes must not fire on prose ABOUT
+    // css — `<code>background-clip: text</code>` in a changelog is
+    // documentation, not styling. cssText already carries the <style>
+    // blocks and any linked local stylesheets; style/class attributes come
+    // from the parsed document, so escaped code samples never contribute.
+    const styleAttrParts = [];
+    const classAttrParts = [];
+    for (const el of document.querySelectorAll('*')) {
+      const styleAttr = el.getAttribute('style');
+      if (styleAttr) styleAttrParts.push(`style="${styleAttr}"`);
+      const classAttr = el.getAttribute('class');
+      if (classAttr) classAttrParts.push(classAttr);
+    }
+    const patternCorpora = {
+      styleText: [cssText, ...styleAttrParts].join('\n'),
+      classText: classAttrParts.join('\n'),
+    };
+    for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html, patternCorpora).filter(item =>
       item.id !== 'bounce-easing' && item.id !== 'layout-transition'
     ))) {
       const item = finding(f.id, filePath, f.snippet);

.agents/skills/impeccable/scripts/detector/node/file-system.mjs

@@ -26,11 +26,26 @@ const HIDDEN_SOURCE_DIRS = new Set(['.vitepress', '.vuepress', '.storybook']);
 const SCANNABLE_EXTENSIONS = new Set([
   '.html', '.htm', '.css', '.scss', '.sass', '.less',
   '.jsx', '.tsx', '.js', '.ts',
-  '.vue', '.svelte', '.astro',
+  '.vue', '.svelte', '.astro', '.blade.php',
 ]);
 
 const HTML_EXTENSIONS = new Set(['.html', '.htm']);
 
+function hasScannableExtension(filename) {
+  const lower = filename.toLowerCase();
+  if (SCANNABLE_EXTENSIONS.has(path.extname(lower))) return true;
+  for (const ext of SCANNABLE_EXTENSIONS) {
+    if (ext.indexOf('.', 1) !== -1 && lower.endsWith(ext)) return true;
+  }
+  return false;
+}
+
+const IMPORT_SPECIFIER_PATTERNS = [
+  /import\s+(?:[\s\S]*?from\s+)?['"]([^'"]+)['"]/g,
+  /@import\s+(?:url\(\s*)?['"]?([^'");\s]+)['"]?\s*\)?/g,
+  /@(?:use|forward)\s+['"]([^'"]+)['"]/g,
+];
+
 function walkDir(dir) {
   const files = [];
   let entries;
@@ -40,7 +55,7 @@ function walkDir(dir) {
     if (entry.isDirectory() && entry.name.startsWith('.') && !HIDDEN_SOURCE_DIRS.has(entry.name)) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) files.push(...walkDir(full));
-    else if (SCANNABLE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) files.push(full);
+    else if (hasScannableExtension(entry.name)) files.push(full);
   }
   return files;
 }
@@ -75,26 +90,11 @@ function buildImportGraph(files) {
     const dir = path.dirname(file);
     const imports = new Set();
 
-    // ES imports: import ... from '...' and import '...'
-    const esRe = /import\s+(?:[\s\S]*?from\s+)?['"]([^'"]+)['"]/g;
-    let m;
-    while ((m = esRe.exec(content)) !== null) {
-      const resolved = resolveImport(m[1], dir, fileSet);
-      if (resolved) imports.add(resolved);
-    }
-
-    // CSS @import
-    const cssRe = /@import\s+(?:url\(\s*)?['"]?([^'");\s]+)['"]?\s*\)?/g;
-    while ((m = cssRe.exec(content)) !== null) {
-      const resolved = resolveImport(m[1], dir, fileSet);
-      if (resolved) imports.add(resolved);
-    }
-
-    // SCSS @use / @forward
-    const scssRe = /@(?:use|forward)\s+['"]([^'"]+)['"]/g;
-    while ((m = scssRe.exec(content)) !== null) {
-      const resolved = resolveImport(m[1], dir, fileSet);
-      if (resolved) imports.add(resolved);
+    for (const pattern of IMPORT_SPECIFIER_PATTERNS) {
+      for (const match of content.matchAll(pattern)) {
+        const resolved = resolveImport(match[1], dir, fileSet);
+        if (resolved) imports.add(resolved);
+      }
     }
 
     graph.set(file, imports);
@@ -203,6 +203,7 @@ export {
   SKIP_DIRS,
   SCANNABLE_EXTENSIONS,
   HTML_EXTENSIONS,
+  hasScannableExtension,
   walkDir,
   resolveImport,
   buildImportGraph,

.agents/skills/impeccable/scripts/detector/registry/antipatterns.mjs

@@ -28,16 +28,6 @@ const ANTIPATTERNS = [
     skillSection: 'Typography',
     skillGuideline: 'overused fonts like Inter',
   },
-  {
-    id: 'single-font',
-    category: 'slop',
-    scopes: ['type'],
-    name: 'Single font without hierarchy',
-    description:
-      'Only one font family is used for the entire page. A single family can work when weight and size contrast carry the hierarchy; otherwise pair a distinctive display font with a refined body font.',
-    skillSection: 'Typography',
-    skillGuideline: 'only one font family for the entire page',
-  },
   {
     id: 'flat-type-hierarchy',
     category: 'slop',

.agents/skills/impeccable/scripts/detector/rules/checks.mjs

@@ -1062,9 +1062,11 @@ function collectMarqueeKeyframes(content) {
 // bound to a keyframe loop that travels a large horizontal distance.
 // Rotation/opacity animations never qualify (no X travel); JS-driven
 // carousels with user controls have no infinite CSS X-loop to match.
-function scanCssTextForMarquee(content) {
+// `content` is CSS-bearing text; `markup` (defaulting to the same string
+// for single-corpus callers) is where the <marquee> tag itself lives.
+function scanCssTextForMarquee(content, markup = content) {
   const findings = [];
-  if (/<marquee\b/i.test(content)) {
+  if (/<marquee\b/i.test(markup)) {
     findings.push({ id: 'marquee', snippet: '<marquee> element' });
   }
   const marqueeKeyframes = collectMarqueeKeyframes(content);
@@ -1243,10 +1245,14 @@ function selectorHitsLandmark(content, selector, ranges) {
 // element sits inside a header/nav landmark is the hero liveness cliché
 // and is promoted to error severity; occurrences elsewhere keep the
 // registry default severity.
-function scanCssTextForPulsingDot(content) {
+//
+// `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
+// to the same string for single-corpus callers like the regex source
+// engine — is where landmark ranges and Tailwind class attributes live.
+function scanCssTextForPulsingDot(content, markup = content) {
   const customProps = collectCssCustomProps(content);
   const keyframes = collectPulseKeyframes(content);
-  const heroRanges = landmarkSourceRanges(content);
+  const heroRanges = landmarkSourceRanges(markup);
   const findings = [];
   const seen = new Set();
 
@@ -1295,7 +1301,7 @@ function scanCssTextForPulsingDot(content) {
 
     if (seen.has(selector)) continue;
     seen.add(selector);
-    const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
+    const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
     findings.push({
       id: 'pulsing-dot',
       snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -1305,10 +1311,11 @@ function scanCssTextForPulsingDot(content) {
   }
 
   // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
-  // element declared entirely in the class attribute.
+  // element declared entirely in the class attribute. Scanned in the markup
+  // corpus so the match index lines up with the landmark ranges.
   const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
   let cm;
-  while ((cm = classRe.exec(content)) !== null) {
+  while ((cm = classRe.exec(markup)) !== null) {
     const cls = cm[1] || cm[2] || '';
     const anim = cls.match(/\banimate-(ping|pulse)\b/);
     if (!anim) continue;
@@ -1389,20 +1396,64 @@ function scanHtmlForShapeAssembledIllustration(html) {
   return findings;
 }
 
+// Scoped scan corpora for the page-level pattern checks. CSS-property
+// regexes run over the whole source string fire on documentation ABOUT
+// css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
+// comments — so the checks scan only the strings that actually style the
+// page:
+//   styleText — <style> block contents plus style="…" attribute values.
+//     Attribute values keep their `style="…"` form so block-scoped
+//     scanners (grid background) keep treating each attribute as one
+//     declaration block, exactly as they did against raw source. Engines
+//     that already read more CSS (linked stylesheets) prepend it.
+//   classText — class attribute values, for utility-class scans.
+// Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
+// landmark ranges) and rendered-text checks (theater phrases) keep the
+// full source. This extraction serves callers without a parsed document
+// (the browser bundle scanning outerHTML); attribute reads are tag-scoped
+// so escaped code samples (&lt;div style="…"&gt;) never contribute. The
+// static engine passes richer corpora built from its parsed document.
+// Bare CSS input (no markup at all) is its own style text, which keeps
+// direct checkHtmlPatterns(css) callers behaving as before.
+function buildHtmlPatternCorpora(html) {
+  const source = String(html || '');
+  if (!/<[a-zA-Z!/]/.test(source)) {
+    return { styleText: source, classText: source };
+  }
+  const styleParts = [];
+  const classParts = [];
+  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let m;
+  while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
+  const tagRe = /<[a-zA-Z][^>]*>/g;
+  while ((m = tagRe.exec(source)) !== null) {
+    const tag = m[0];
+    const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
+    if (sm) styleParts.push(`style=${sm[1]}`);
+    const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+    if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
+  }
+  return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
+}
+
 /**
  * Regex-on-HTML checks shared between browser and Node page-level detection.
- * These don't need DOM access, just the raw HTML string.
+ * These don't need DOM access, just the raw HTML string. CSS-property and
+ * utility-class patterns scan the scoped corpora (styleText / classText —
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
+ * markup-shaped and rendered-text checks read the full source.
  */
-function checkHtmlPatterns(html) {
+function checkHtmlPatterns(html, corpora) {
+  const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
   const findings = [];
 
   // --- Color ---
 
   // AI color palette: purple/violet
   const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
-  if (purpleHexRe.test(html)) {
+  if (purpleHexRe.test(styleText)) {
     const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
-    if (purpleTextRe.test(html)) {
+    if (purpleTextRe.test(styleText)) {
       findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
     }
   }
@@ -1410,15 +1461,15 @@ function checkHtmlPatterns(html) {
   // Gradient text (background-clip: text + gradient)
   const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
   let gm;
-  while ((gm = gradientRe.exec(html)) !== null) {
+  while ((gm = gradientRe.exec(styleText)) !== null) {
     const start = Math.max(0, gm.index - 200);
-    const context = html.substring(start, gm.index + gm[0].length + 200);
+    const context = styleText.substring(start, gm.index + gm[0].length + 200);
     if (/gradient/i.test(context)) {
       findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
       break;
     }
   }
-  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
+  if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
     findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
   }
 
@@ -1427,10 +1478,10 @@ function checkHtmlPatterns(html) {
   // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
   // (no border property involved, so the element-level border checks and
   // the border-left regexes never see it).
-  findings.push(...scanCssTextForPseudoStripe(html));
+  findings.push(...scanCssTextForPseudoStripe(styleText));
 
   // Side-tab accent stripe drawn as a single-edge inset box-shadow.
-  findings.push(...scanCssTextForInsetStripe(html));
+  findings.push(...scanCssTextForInsetStripe(styleText));
 
   // --- Layout ---
 
@@ -1438,20 +1489,20 @@ function checkHtmlPatterns(html) {
   const spacingValues = [];
   const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
   let sm;
-  while ((sm = spacingRe.exec(html)) !== null) {
+  while ((sm = spacingRe.exec(styleText)) !== null) {
     const v = parseInt(sm[1], 10);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
   const gapRe = /gap\s*:\s*(\d+)px/gi;
-  while ((sm = gapRe.exec(html)) !== null) {
+  while ((sm = gapRe.exec(styleText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10));
   }
   const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
-  while ((sm = twSpaceRe.exec(html)) !== null) {
+  while ((sm = twSpaceRe.exec(classText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10) * 4);
   }
   const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
-  while ((sm = remSpacingRe.exec(html)) !== null) {
+  while ((sm = remSpacingRe.exec(styleText)) !== null) {
     const v = Math.round(parseFloat(sm[1]) * 16);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
@@ -1475,7 +1526,7 @@ function checkHtmlPatterns(html) {
 
   // Bounce/elastic animation names
   const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
-  const bounceMatch = bounceRe.exec(html);
+  const bounceMatch = bounceRe.exec(styleText);
   if (bounceMatch) {
     const animationToken = bounceMatch[1]
       .split(/[,\s]+/)
@@ -1486,7 +1537,7 @@ function checkHtmlPatterns(html) {
   // Overshoot cubic-bezier
   const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
   let bm;
-  while ((bm = bezierRe.exec(html)) !== null) {
+  while ((bm = bezierRe.exec(styleText)) !== null) {
     const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
     if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
       findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
@@ -1497,7 +1548,7 @@ function checkHtmlPatterns(html) {
   // Layout property transitions
   const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
   let tm;
-  while ((tm = transRe.exec(html)) !== null) {
+  while ((tm = transRe.exec(styleText)) !== null) {
     const val = tm[1].toLowerCase();
     if (/\ball\b/.test(val)) continue;
     const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -1507,30 +1558,32 @@ function checkHtmlPatterns(html) {
     }
   }
 
-  // Pulsing status dots (tiny circular elements on infinite pulse animations)
-  findings.push(...scanCssTextForPulsingDot(html));
+  // Pulsing status dots (tiny circular elements on infinite pulse animations).
+  // The CSS rules come from styleText; the markup carries the landmark
+  // ranges and Tailwind class attributes.
+  findings.push(...scanCssTextForPulsingDot(styleText, html));
 
   // Shape-assembled illustrations (large pictorial SVGs built from primitives)
   findings.push(...scanHtmlForShapeAssembledIllustration(html));
 
   // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
-  findings.push(...scanCssTextForMarquee(html));
+  findings.push(...scanCssTextForMarquee(styleText, html));
 
   // --- Dark glow / chromatic halo shadows ---
 
-  const glowHits = scanCssTextForGlow(html);
+  const glowHits = scanCssTextForGlow(styleText);
   if (glowHits.length > 0) {
     findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
   }
 
   // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
-  const haloHits = scanCssTextForRadialHalo(html);
+  const haloHits = scanCssTextForRadialHalo(styleText);
   if (haloHits.length > 0) {
     findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
   }
 
   // --- Generated-UI tells: repeating-gradient stripes ---
-  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
+  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(styleText)) {
     findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
   }
 
@@ -1547,7 +1600,7 @@ function checkHtmlPatterns(html) {
   // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
   // nested parens, so match the hairline stop directly rather than parsing
   // whole gradient layers.
-  const gridHits = scanCssTextForGridBackground(html);
+  const gridHits = scanCssTextForGridBackground(styleText);
   if (gridHits.length > 0) {
     findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
   }
@@ -1569,7 +1622,7 @@ function checkHtmlPatterns(html) {
   // hover:rotate / hover:translate utility on an <img>. Each distinct
   // mechanism is its own finding.
   const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
-  if (imgHoverCss.test(html)) {
+  if (imgHoverCss.test(styleText)) {
     findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
   }
   const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
@@ -2470,7 +2523,11 @@ function isKickerCandidate(opts) {
     || isSmallCaps;
   if (!isUppercased) return false;
   if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
-  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
+  // Proportional only, no absolute floor: the wild's most common recipe is
+  // 0.08em at a sub-13px size, which computes to under 1px and sailed past
+  // the old Math.max(1, ...) floor (observed live: a page whose kickers were
+  // literally class="kicker" produced zero findings).
+  const minTrackedSpacing = kickerFontSize * 0.06;
   if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
   return true;
 }
@@ -3854,12 +3911,6 @@ function checkTypography() {
       if (isBrandFontOnOwnDomain(font)) continue;
       findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
     }
-
-    // Single-font check: only one distinct primary font across all text
-    if (fontUsage.size === 1) {
-      const only = [...fontUsage.keys()][0];
-      findings.push({ type: 'single-font', detail: `only font used is ${only}` });
-    }
   }
 
   const sizes = new Set();
@@ -4121,14 +4172,6 @@ function checkPageTypography(doc, win) {
     findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
   }
 
-  // Single font
-  if (fonts.size === 1) {
-    const els = doc.querySelectorAll('*');
-    if (els.length >= 20) {
-      findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
-    }
-  }
-
   // Flat type hierarchy
   const sizes = new Set();
   const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');
@@ -5450,6 +5493,7 @@ export {
   cssLengthToPx,
   scanCssTextForPulsingDot,
   scanHtmlForShapeAssembledIllustration,
+  buildHtmlPatternCorpora,
   checkHtmlPatterns,
   readOwnBackgroundColor,
   resolveBackground,

.agents/skills/impeccable/scripts/embed-prompt.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Embed a generation prompt into an image so the intent travels with the file,
+// across harnesses and machines. Read it back with --read.
+//
+//   node embed-prompt.mjs <image> --prompt "the prompt text"
+//   node embed-prompt.mjs <image> --prompt-file prompt.txt
+//   node embed-prompt.mjs <image> --read
+//
+// Formats: PNG (tEXt chunk, keyword "impeccable:prompt"), JPEG (COM segment).
+// WebP and anything else fall back to a `<image>.json` sidecar; --read checks
+// the sidecar for every format, so the fallback stays recoverable. Embedding
+// rewrites a few MB at most: latency is milliseconds, generation is minutes.
+// Caveat worth knowing: image optimizers in build pipelines often strip
+// metadata from their OUTPUT files; the intent lives on the source asset,
+// which is the one a builder reads.
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+const KEYWORD = 'impeccable:prompt';
+const args = process.argv.slice(2);
+const file = args.find(a => !a.startsWith('--'));
+const readMode = args.includes('--read');
+const argOf = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : null; };
+
+if (!file || !fs.existsSync(file)) { console.error('embed-prompt: image file required'); process.exit(1); }
+
+const buf = fs.readFileSync(file);
+const isPng = buf.length > 8 && buf.readUInt32BE(0) === 0x89504e47;
+const isJpeg = buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8;
+
+const crcTable = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0; }
+  return t;
+})();
+const crc32 = (data) => { let c = 0xffffffff; for (const b of data) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+
+function pngChunk(type, data) {
+  const out = Buffer.alloc(12 + data.length);
+  out.writeUInt32BE(data.length, 0);
+  out.write(type, 4, 'ascii');
+  data.copy(out, 8);
+  out.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, 'ascii'), data])), 8 + data.length);
+  return out;
+}
+
+function readPngText(b) {
+  let off = 8;
+  while (off + 12 <= b.length) {
+    const len = b.readUInt32BE(off);
+    const type = b.toString('ascii', off + 4, off + 8);
+    if (type === 'tEXt' || type === 'zTXt') {
+      const data = b.subarray(off + 8, off + 8 + len);
+      const nul = data.indexOf(0);
+      if (nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD) {
+        if (type === 'tEXt') return data.toString('utf8', nul + 1);
+        return zlib.inflateSync(data.subarray(nul + 2)).toString('utf8');
+      }
+    }
+    off += 12 + len;
+  }
+  return null;
+}
+
+function readJpegCom(b) {
+  let off = 2;
+  while (off + 4 <= b.length && b[off] === 0xff) {
+    const marker = b[off + 1];
+    if (marker === 0xda) break; // start of scan: no more segments
+    const len = b.readUInt16BE(off + 2);
+    if (marker === 0xfe) {
+      const text = b.toString('utf8', off + 4, off + 2 + len);
+      if (text.startsWith(KEYWORD + '\0')) return text.slice(KEYWORD.length + 1);
+    }
+    off += 2 + len;
+  }
+  return null;
+}
+
+const sidecar = `${file}.json`;
+if (readMode) {
+  let prompt = null;
+  if (isPng) prompt = readPngText(buf);
+  else if (isJpeg) prompt = readJpegCom(buf);
+  if (prompt == null && fs.existsSync(sidecar)) {
+    try { prompt = JSON.parse(fs.readFileSync(sidecar, 'utf8')).prompt ?? null; } catch { /* fall through */ }
+  }
+  if (prompt == null) { console.error('embed-prompt: no embedded prompt found'); process.exit(2); }
+  console.log(prompt);
+  process.exit(0);
+}
+
+const prompt = argOf('--prompt') ?? (argOf('--prompt-file') ? fs.readFileSync(argOf('--prompt-file'), 'utf8') : null);
+if (!prompt) { console.error('embed-prompt: --prompt or --prompt-file required'); process.exit(1); }
+
+if (isPng) {
+  // Insert (or replace) our tEXt chunk immediately before IEND.
+  const iend = buf.indexOf(Buffer.from('IEND', 'ascii')) - 4;
+  if (iend < 8) { console.error('embed-prompt: malformed PNG'); process.exit(1); }
+  // Drop any existing chunk with our keyword to keep embedding idempotent.
+  let body = buf.subarray(8, iend);
+  const existing = readPngText(buf);
+  if (existing != null) {
+    const parts = [];
+    let off = 8;
+    while (off + 12 <= buf.length && off < iend + 12) {
+      const len = buf.readUInt32BE(off);
+      const type = buf.toString('ascii', off + 4, off + 8);
+      const chunk = buf.subarray(off, off + 12 + len);
+      const data = buf.subarray(off + 8, off + 8 + len);
+      const nul = data.indexOf(0);
+      const ours = (type === 'tEXt' || type === 'zTXt') && nul !== -1 && data.toString('latin1', 0, nul) === KEYWORD;
+      if (!ours && type !== 'IEND') parts.push(chunk);
+      off += 12 + len;
+    }
+    body = Buffer.concat(parts).subarray(8 * 0); // parts exclude signature
+    fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 8), body, pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), pngChunk('IEND', Buffer.alloc(0))]));
+  } else {
+    fs.writeFileSync(file, Buffer.concat([buf.subarray(0, iend), pngChunk('tEXt', Buffer.concat([Buffer.from(KEYWORD, 'latin1'), Buffer.from([0]), Buffer.from(prompt, 'utf8')])), buf.subarray(iend)]));
+  }
+  console.log(`EMBEDDED: ${file} (png tEXt, ${prompt.length} chars)`);
+} else if (isJpeg) {
+  const seg = Buffer.from(`${KEYWORD}\0${prompt}`, 'utf8');
+  if (seg.length + 2 > 0xffff) { console.error('embed-prompt: prompt too long for a JPEG segment'); process.exit(1); }
+  const com = Buffer.alloc(4 + seg.length);
+  com[0] = 0xff; com[1] = 0xfe; com.writeUInt16BE(seg.length + 2, 2); seg.copy(com, 4);
+  fs.writeFileSync(file, Buffer.concat([buf.subarray(0, 2), com, buf.subarray(2)]));
+  console.log(`EMBEDDED: ${file} (jpeg COM, ${prompt.length} chars)`);
+} else {
+  fs.writeFileSync(sidecar, JSON.stringify({ prompt, createdAt: new Date().toISOString() }, null, 2));
+  console.log(`EMBEDDED: ${sidecar} (sidecar fallback for this format)`);
+}

.agents/skills/impeccable/scripts/generate-image.mjs

@@ -229,4 +229,12 @@ if (!b64) {
   process.exit(1);
 }
 fs.writeFileSync(out, Buffer.from(b64, 'base64'));
-console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key)`);
+// The prompt travels with the asset: embedded in the file itself (EXIF-class
+// metadata via embed-prompt.mjs) so intent survives copies across harnesses,
+// plus a sidecar for anything that indexes rather than opens the image.
+try {
+  const { spawnSync } = await import('node:child_process');
+  spawnSync(process.execPath, [new URL('./embed-prompt.mjs', import.meta.url).pathname, out, '--prompt', prompt], { stdio: 'ignore' });
+  fs.writeFileSync(`${out}.json`, JSON.stringify({ prompt, createdAt: new Date().toISOString(), tool: 'generate-image.mjs', model: 'gpt-image-2' }, null, 2));
+} catch { /* embedding is best-effort */ }
+console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); prompt embedded + sidecar at ${out}.json`);

.agents/skills/impeccable/scripts/hook-admin.mjs

@@ -10,7 +10,7 @@
  *   node hook-admin.mjs off                            # set enabled: false
  *   node hook-admin.mjs ignore-rule <rule-id>          # append to ignoreRules
  *   node hook-admin.mjs ignore-rule overused-font --all-values
- *   node hook-admin.mjs ignore-file <glob>             # append to ignoreFiles
+ *   node hook-admin.mjs ignore-file <glob> [--shared|--local]   # append to ignoreFiles
  *   node hook-admin.mjs ignore-value <rule> <value>    # append to shared ignoreValues
  *   node hook-admin.mjs ignore-value <rule> <value> --local
  *   node hook-admin.mjs ignore-value <rule> "*" --file <glob>   # rule off in <glob> only
@@ -166,7 +166,7 @@ function readRawConfigFile(filePath) {
   }
 }
 
-const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
+const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem', 'advisoryRules']);
 
 function hookSection(unified) {
   return unified && typeof unified === 'object' && !Array.isArray(unified) && unified.hook && typeof unified.hook === 'object' && !Array.isArray(unified.hook)
@@ -200,6 +200,15 @@ function stripDetectorKeys(raw) {
   return out;
 }
 
+function pickDetectorKeys(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (DETECTOR_CONFIG_KEYS.has(key)) out[key] = value;
+  }
+  return out;
+}
+
 // Write hook runtime config under `hook`, leaving detector filters in
 // `detector` and preserving sibling keys such as updateCheck.
 function writeHookConfig(cwd, hookConfig, opts = {}) {
@@ -207,10 +216,19 @@ function writeHookConfig(cwd, hookConfig, opts = {}) {
   if (opts.local) ensureHookGitExcludes(cwd);
   const existingRaw = readRawConfigFile(filePath).raw;
   const existing = existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw) ? existingRaw : {};
-  const existingHook = stripDetectorKeys(hookSection(existing));
+  const existingHookSection = hookSection(existing);
+  const existingHook = stripDetectorKeys(existingHookSection);
+  const legacyDetector = pickDetectorKeys(existingHookSection);
   // Merge over the existing hook object so fields the merge helpers don't manage
   // (consent, quiet, auditLog) survive an Impeccable hooks edit.
   const next = { ...existing, hook: { ...existingHook, ...hookConfig } };
+  if (Object.keys(legacyDetector).length > 0) {
+    const existingDetector = detectorSection(existing) || {};
+    next.detector = {
+      ...existingDetector,
+      ...mergeDetectorConfig(existingDetector, mergeDetectorConfig(legacyDetector)),
+    };
+  }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
   return filePath;
@@ -222,10 +240,14 @@ function writeDetectorConfig(cwd, detectorConfig, opts = {}) {
   const existingRaw = readRawConfigFile(filePath).raw;
   const existing = existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw) ? existingRaw : {};
   const nextHook = stripDetectorKeys(hookSection(existing));
-  const existingDetector = mergeDetectorConfig(detectorSection(existing));
+  const existingDetectorSection = detectorSection(existing) || {};
+  const existingDetector = mergeDetectorConfig(existingDetectorSection);
   const next = {
     ...existing,
-    detector: mergeDetectorConfig(detectorConfig, existingDetector),
+    detector: {
+      ...existingDetectorSection,
+      ...mergeDetectorConfig(detectorConfig, existingDetector),
+    },
   };
   if (Object.keys(nextHook).length > 0) next.hook = nextHook;
   else delete next.hook;
@@ -259,12 +281,18 @@ function mergeDetectorConfig(existing, seed = null) {
   if (seed?.designSystem && typeof seed.designSystem === 'object' && !Array.isArray(seed.designSystem)) {
     out.designSystem = { ...seed.designSystem };
   }
+  if (seed?.advisoryRules === 'include' || seed?.advisoryRules === 'exclude') {
+    out.advisoryRules = seed.advisoryRules;
+  }
   if (base.designSystem && typeof base.designSystem === 'object' && !Array.isArray(base.designSystem)) {
     out.designSystem = {
       ...(out.designSystem || {}),
       enabled: base.designSystem.enabled === false ? false : true,
     };
   }
+  if (base.advisoryRules === 'include' || base.advisoryRules === 'exclude') {
+    out.advisoryRules = base.advisoryRules;
+  }
   if (Array.isArray(base.ignoreRules)) {
     out.ignoreRules = Array.from(new Set([...out.ignoreRules, ...base.ignoreRules.map(String)]));
   }
@@ -558,12 +586,44 @@ function addIgnoreRule(cwd, args) {
   return `Added "${rule}" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
 }
 
-function addIgnoreFile(cwd, glob) {
+function parseIgnoreFileArgs(args) {
+  const positionals = [];
+  let shared = false;
+  let local = false;
+
+  for (const raw of args) {
+    const arg = String(raw || '');
+    if (arg === '--shared') {
+      shared = true;
+    } else if (arg === '--local') {
+      local = true;
+    } else if (arg === '--reason' || arg.startsWith('--reason=')) {
+      throw new Error('--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits');
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown ignore-file flag: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  if (shared && local) throw new Error('Pass only one scope flag: --shared or --local');
+  if (positionals.length > 1) throw new Error('Pass exactly one glob to ignore-file');
+
+  return {
+    glob: positionals[0],
+    local,
+  };
+}
+
+function addIgnoreFile(cwd, args) {
+  const parsed = parseIgnoreFileArgs(args);
+  const glob = parsed.glob;
   if (!glob) throw new Error(`Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "src/legacy/**"`);
-  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
+  const config = mergeDetectorConfig(readRawDetectorConfig(cwd, { local: parsed.local }));
   if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
-  writeDetectorConfig(cwd, config);
-  return `Added "${glob}" to detector.ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
+  const target = writeDetectorConfig(cwd, config, { local: parsed.local });
+  const scope = parsed.local ? 'local detector.ignoreFiles' : 'shared detector.ignoreFiles';
+  return `Added "${glob}" to ${scope} (${path.relative(cwd, target) || target}). Current: ${config.ignoreFiles.join(', ')}`;
 }
 
 // An empty glob used to be dropped by filter(Boolean), so `--file=` reported
@@ -727,7 +787,7 @@ function main() {
       case 'on':     out = setEnabled(cwd, true); break;
       case 'off':    out = setEnabled(cwd, false); break;
       case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
-      case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
+      case 'ignore-file': out = addIgnoreFile(cwd, rest); break;
       case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
       case 'reset':  out = reset(cwd); break;
     }

.agents/skills/impeccable/scripts/hook-before-edit.mjs

@@ -23,6 +23,7 @@ import {
   designSystemOptions,
   filterFindings,
   isNativePlatform,
+  isScanTargetInsideProject,
   loadDetector,
   matchConfiguredExtension,
   matchesAnyGlob,
@@ -161,7 +162,7 @@ function replaceOnce(original, oldString, newString) {
 }
 
 function readExistingProjectFile(filePath, cwd) {
-  if (!isInsideProject(filePath, cwd)) return null;
+  if (!isScanTargetInsideProject(filePath, cwd)) return null;
   if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
   try {
     const stat = fs.statSync(filePath);
@@ -232,7 +233,7 @@ function shellCopiedFileContent(command, cwd) {
   const source = shellCopyPaths(command)?.source;
   if (!source) return '';
   const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
-  if (!isInsideProject(sourcePath, cwd)) return '';
+  if (!isScanTargetInsideProject(sourcePath, cwd)) return '';
   if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
   try {
     const stat = fs.statSync(sourcePath);
@@ -328,15 +329,6 @@ function relativePath(filePath, cwd) {
   }
 }
 
-function isInsideProject(filePath, cwd) {
-  try {
-    const rel = path.relative(cwd, filePath);
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-  } catch {
-    return false;
-  }
-}
-
 // The static HTML engine reads its input from disk, but preToolUse only has
 // the proposed content. Stage it in a temp file so html-engine targets get the
 // same DOM-structural rules pre-write that runHook applies post-edit.
@@ -414,7 +406,7 @@ async function main() {
   };
 
   if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
-  if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
+  if (!isScanTargetInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
   if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
   if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
 

.agents/skills/impeccable/scripts/hook-lib.mjs

@@ -880,6 +880,9 @@ function extractFindingIgnoreValueRaw(finding, rule = normalizeIgnoreRule(findin
     const primary = text.match(/Primary font:\s*([^()\n;]+)/i);
     if (primary) return cleanIgnoreValueDisplay(primary[1]);
 
+    const googleLabel = text.match(/Google Fonts:\s*([^()\n;]+)/i);
+    if (googleLabel) return cleanIgnoreValueDisplay(googleLabel[1]);
+
     const family = text.match(/font-family\s*:\s*["']?([^'",;\n]+)/i);
     if (family) return cleanIgnoreValueDisplay(family[1]);
 
@@ -1332,6 +1335,51 @@ function isInsideProject(filePath, projectCwd) {
   }
 }
 
+// Resolve a path to its canonical (symlink-free) form. When the path does
+// not exist yet — the before-edit hook gates proposed Writes — canonicalize
+// the nearest existing ancestor and re-append the remainder, so a new file
+// under a symlinked root still compares equal to its canonical project.
+// Memoized: the hook runs as a fresh process per tool event, so the cache
+// amounts to once-per-event work — the scan loops re-check the same project
+// root for every target file. The cap only matters to long-lived importers
+// like the test runner.
+const canonicalPathCache = new Map();
+const CANONICAL_PATH_CACHE_MAX = 1024;
+
+function canonicalPath(p) {
+  const resolved = path.resolve(p);
+  if (canonicalPathCache.has(resolved)) return canonicalPathCache.get(resolved);
+  let canonical = resolved;
+  let dir = resolved;
+  const tail = [];
+  while (true) {
+    try {
+      canonical = tail.length ? path.join(fs.realpathSync(dir), ...tail) : fs.realpathSync(dir);
+      break;
+    } catch { /* keep climbing */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    tail.unshift(path.basename(dir));
+    dir = parent;
+  }
+  if (canonicalPathCache.size >= CANONICAL_PATH_CACHE_MAX) canonicalPathCache.clear();
+  canonicalPathCache.set(resolved, canonical);
+  return canonical;
+}
+
+// Containment gate shared by the before-edit hook and both scan passes. A
+// session routinely touches files that belong to no project or to a
+// different one — harness scratchpad dirs under the system temp root,
+// sibling checkouts, one-off throwaway HTML — and findings against those are
+// judged with THIS project's config and DESIGN.md palette, which is never
+// right. Skip them (audit reason: outside-project). Paths are canonicalized
+// first so a symlinked root (macOS /tmp -> /private/tmp) doesn't split the
+// comparison.
+export function isScanTargetInsideProject(filePath, projectCwd) {
+  if (!filePath || !projectCwd) return false;
+  return isInsideProject(canonicalPath(filePath), canonicalPath(projectCwd));
+}
+
 export function parseStaticStyleImports(content, fromFile, projectCwd) {
   if (!content || typeof content !== 'string') return [];
   const dir = path.dirname(fromFile);
@@ -1690,6 +1738,10 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =
         lastSkip = 'file-missing';
         continue;
       }
+      if (!isScanTargetInsideProject(filePath, projectCwd)) {
+        lastSkip = 'outside-project';
+        continue;
+      }
 
       const maxFileBytes = config.limits?.maxFileBytes ?? DEFAULT_CONFIG.limits.maxFileBytes;
       if (maxFileBytes > 0) {
@@ -2020,6 +2072,10 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       const relForMatch = relativize(filePath, projectCwd);
       if (matchesAnyGlob(relForMatch, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) continue;
       if (!fs.existsSync(filePath)) continue;
+      // Caches written before this gate existed can still hold out-of-project
+      // paths, so the Stop pass re-checks containment rather than trusting
+      // the per-edit pass to have filtered them.
+      if (!isScanTargetInsideProject(filePath, projectCwd)) continue;
 
       scanned += 1;
       let content = '';

.agents/skills/impeccable/scripts/lib/composition-catalog.mjs

@@ -1,8 +1,13 @@
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { CONCEPT_STATUSES, normalizeConceptForm } from './concept-catalog.mjs';
+// Defined in roll-selection.mjs for the same reason WELL_TIERS is: this file
+// reads the filesystem, and the roll API imports the taxonomy to validate its
+// grain and platform parameters. Re-exported so importers have one place to look.
+import { COMPOSITION_GRAINS, COMPOSITION_PLATFORMS, isGrain, isPlatform } from './roll-selection.mjs';
+export { COMPOSITION_GRAINS, COMPOSITION_PLATFORMS, isGrain, isPlatform };
 
-// Catalog B: stagings rather than styles. A composition organizes attention,
+// Catalog B: compositions rather than styles. A composition organizes attention,
 // sequence, or manipulation on a surface and must survive being dressed in
 // any committed visual identity; it deliberately carries no palette or type
 // half. Surface-scope seeds draw from here (plus catalog A duals); direction
@@ -15,10 +20,11 @@ export const COMPOSITION_GRAMMAR_PREFIXES = [
   'Adaptation:',
 ];
 
-// Surfaces align with the skill's modes: a persuade staging and an operate
-// staging are different species, and read/experience surfaces get their own.
+// Surfaces align with the skill's modes: a persuade composition and an operate
+// composition are different species, and read/experience surfaces get their own.
 export const COMPOSITION_SURFACES = new Set(['persuade', 'operate', 'read', 'experience']);
 
+
 export function compositionContentHash(composition) {
   const payload = [
     composition?.form ?? '',
@@ -57,6 +63,26 @@ export function validateCompositionEntry(composition, { existingForms = new Map(
   if (!COMPOSITION_SURFACES.has(composition?.surface)) {
     errors.push(`composition ${id} needs a surface of ${[...COMPOSITION_SURFACES].join(', ')}`);
   }
+  // Grain: how much of the product this composes. Optional, and absence means
+  // eligible at any grain, so nothing needs backfilling.
+  if (composition?.grain !== undefined && composition.grain !== null && !isGrain(composition.grain)) {
+    errors.push(`composition ${id} grain "${composition.grain}" must be one of ${COMPOSITION_GRAINS.join(', ')}`);
+  }
+  // Platforms this composition survives. Absence means all of them, so listing
+  // every platform is the same as omitting the field and is rejected in favour of
+  // leaving it out; an empty array would exclude the entry from every roll.
+  if (composition?.platforms !== undefined && composition.platforms !== null) {
+    const list = composition.platforms;
+    if (!Array.isArray(list) || list.length === 0) {
+      errors.push(`composition ${id} platforms must be a non-empty array, or omitted to allow every platform`);
+    } else if (list.some(entry => !isPlatform(entry))) {
+      errors.push(`composition ${id} platforms may only contain ${COMPOSITION_PLATFORMS.join(', ')}`);
+    } else if (new Set(list).size !== list.length) {
+      errors.push(`composition ${id} platforms must not repeat a platform`);
+    } else if (list.length === COMPOSITION_PLATFORMS.length) {
+      errors.push(`composition ${id} platforms lists every platform; omit the field instead`);
+    }
+  }
   if (!Array.isArray(composition?.tags)
     || composition.tags.length !== 3
     || composition.tags.some(tag => typeof tag !== 'string' || !tag.trim())) {
@@ -149,6 +175,15 @@ export function validateCompositionCatalog(catalog, reviewData, { minimumTotal }
         errors.push(`composition review ${id} is stale: content changed since review`);
       }
     }
+    // Mirrors the concept catalog: an optional 1-3 grade on approved entries
+    // only, read as a calibration signal and used to weight challenger draws.
+    if (review?.rating !== undefined) {
+      if (![1, 2, 3].includes(review.rating)) {
+        errors.push(`review ${id} rating must be 1, 2, or 3`);
+      } else if (review.status !== 'approved') {
+        errors.push(`review ${id} rating only applies to approved compositions`);
+      }
+    }
     if (review?.note !== undefined && (typeof review.note !== 'string' || !review.note.trim() || review.note.length > 500)) {
       errors.push(`composition review ${id} note must be a non-empty string of 500 characters or fewer`);
     }

.agents/skills/impeccable/scripts/lib/concept-catalog.mjs

@@ -1,11 +1,12 @@
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
+import { WELL_TIERS } from './roll-selection.mjs';
 
 export const CONCEPT_STATUSES = new Set(['approved', 'rejected']);
 
 // What a concept is actually strong at. Worlds carry a durable visual
 // identity (their palette/type half is the magnet); compositions carry a
-// staging or interaction idea (their topology half is the magnet) that can be
+// composition or interaction idea (their topology half is the magnet) that can be
 // dressed in any committed identity; duals fuse both inseparably. Direction
 // seeds draw world|dual, surface seeds draw composition|dual.
 export const CONCEPT_STRENGTHS = new Set(['world', 'composition', 'dual']);
@@ -15,7 +16,20 @@ export const CONCEPT_STRENGTHS = new Set(['world', 'composition', 'dual']);
 // atmosphere worlds need the largest translation step. Every seed roll draws
 // one challenger from each tier so at least one directly-usable graphic
 // system is always on the table.
-export const WELL_TIERS = ['graphic', 'interaction', 'atmosphere'];
+// Defined in roll-selection.mjs, the dependency-free leaf both the seeder and
+// the roll API import. It cannot depend on this file: this one reads the
+// filesystem, and a Pages Function must not pull node:fs into its bundle.
+// Imported and re-exported rather than re-exported alone: a bare
+// `export { X } from` does not bind X in this module's own scope, and
+// validateConceptCatalog needs it.
+export { WELL_TIERS };
+
+// Reviewer axes that gate the challenger draw without touching approval.
+export const CONCEPT_BREADTHS = new Set(['general', 'niche']);
+// The registers of work a roll can be asked for. Kept here beside the review
+// validation that uses it; roll-selection.mjs filters on it and the seeder
+// validates the --mode flag against the same four.
+export const SEED_MODES = new Set(['persuade', 'operate', 'read', 'experience']);
 
 const WEB_LEVERAGE_RE = /(?:\b3d\b|\badaptive\b|\banimat(?:e|ed|ion)\b|\bapi\b|\baria\b|\baudio\b|\bautomated?\b|\bbarcode\b|\bbroadcastchannel\b|\bbrowser\b|\bcamera\b|canvas\b|\bcaption\b|\bcollaborat(?:e|ive|ion)\b|\bcompar(?:e|ison)\b|\bcomput(?:e|ed|ation)\b|\bcomputer[- ]vision\b|\bconstraint[- ]solving\b|\bcryptographic?\b|\bcss\b|\bdeep[- ]link(?:ing)?\b|\bdirect manipulation\b|\bdom\b|\bdrag\b|\bfilter\b|\bfocus\b|\bgenerative\b|\bgeolocat(?:e|ed|ion)\b|\bgesture\b|\bgpu\b|\bgraph\b|\bhistory\b|\bindexeddb\b|\binteractive\b|\bintersectionobserver\b|\bkeyboard\b|\blive\b|\blocal\b|\bmicrophone\b|\bmotion\b|\bmultiplayer\b|\bnative\b|\bnotification\b|\boffline\b|\bpersonaliz(?:e|ed|ation)\b|\bplayable\b|\bpointer\b|\bprocedural\b|\bprovenance\b|\breal[- ]?time\b|\bresizeobserver\b|\bresponsive\b|\breveal\b|\bscrub\b|\bsearch\b|\bsearchparams\b|\bsensor\b|\bserver[- ]sent\b|\bservice worker\b|\bshader\b|\bsimulat(?:e|ed|ion|or)\b|\bspatial\b|\bstate\b|\bstream(?:ing)?\b|\bsvg\b|\bsynchroniz(?:e|ed|ation)\b|\btimeline\b|\btouch\b|\burl|\bvideo\b|\bweb(?:gl|socket|vtt)?\b|\bworker\b|\bzoom\b)/i;
 export const SYSTEM_PREFIXES = [
@@ -36,9 +50,36 @@ export function normalizeConceptForm(value) {
     .trim();
 }
 
-export function validateConceptEntry(concept, { existingForms = new Map() } = {}) {
+export function validateConceptEntry(concept, { existingForms = new Map(), axes = null } = {}) {
   const errors = [];
   const id = concept?.id || '(unknown)';
+
+  // Recorded aesthetic axis values. Optional, and absent means the value is
+  // inferred from the system rules instead. Some axes cannot be inferred at all:
+  // depth's keyword probe matched worlds that said "no cast shadow anywhere",
+  // and motion and colour strategy describe properties the rules never state, so
+  // a wave that assigns those has to record them or the assignment is lost.
+  // Validated against the axes definition when the caller supplies it, because a
+  // typo would read as "unrecorded" and silently fall back to a probe that is
+  // known not to work.
+  if (concept?.axes !== undefined && concept.axes !== null) {
+    if (typeof concept.axes !== 'object' || Array.isArray(concept.axes)) {
+      errors.push(`concept ${id} axes must be an object of axis id to value id`);
+    } else if (axes) {
+      const byId = new Map((axes.axes || []).map(axis => [axis.id, axis]));
+      for (const [axisId, valueId] of Object.entries(concept.axes)) {
+        const axis = byId.get(axisId);
+        if (!axis) {
+          errors.push(`concept ${id} names unknown axis "${axisId}"`);
+        } else if (!(axis.values || []).some(value => value.id === valueId)) {
+          errors.push(
+            `concept ${id} axis "${axisId}" has unknown value "${valueId}" `
+            + `(expected one of ${(axis.values || []).map(v => v.id).join(', ')})`
+          );
+        }
+      }
+    }
+  }
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(concept?.id || '')) {
     errors.push(`invalid concept id: ${String(concept?.id)}`);
   }
@@ -68,6 +109,18 @@ export function validateConceptEntry(concept, { existingForms = new Map() } = {}
     || concept.tags.some(tag => typeof tag !== 'string' || !tag.trim())) {
     errors.push(`concept ${id} must have exactly three structural tags`);
   }
+  // The slop this world in particular is at risk of. Optional, because 541
+  // entries predate it and none of them are wrong for lacking it. A world built
+  // from posters is at risk of shouting and one built from instruments is at
+  // risk of dead greys; a global detector cannot know which, and the author can.
+  if (concept?.avoid !== undefined) {
+    if (!Array.isArray(concept.avoid)
+      || concept.avoid.length < 2
+      || concept.avoid.length > 3
+      || concept.avoid.some(item => typeof item !== 'string' || item.trim().length < 12 || item.trim().length > 160)) {
+      errors.push(`concept ${id} avoid must be two or three negations of 12–160 characters`);
+    }
+  }
   if (!Array.isArray(concept?.system)
     || concept.system.length !== SYSTEM_PREFIXES.length
     || concept.system.some(rule => typeof rule !== 'string' || rule.trim().length < 12 || rule.trim().length > 180)) {
@@ -282,6 +335,27 @@ export function validateConceptCatalog(catalog, reviewData, {
         errors.push(`review ${id} rating only applies to approved concepts`);
       }
     }
+    // Breadth: a world too narrow to serve an arbitrary build keeps its approval
+    // and leaves the challenger pool. Selection has honoured this for a while but
+    // nothing validated it, so a typo would silently read as "general".
+    if (review?.breadth !== undefined && !CONCEPT_BREADTHS.has(review.breadth)) {
+      errors.push(`review ${id} breadth must be one of ${[...CONCEPT_BREADTHS].join(', ')}`);
+    }
+    // Mode eligibility: which registers of work this world can carry. Absent
+    // means all of them, which is why it needs no backfill. Listing every mode
+    // is the same as omitting it, and an empty list would deal nothing, so both
+    // are rejected in favour of leaving the field out.
+    if (review?.allowedModes !== undefined) {
+      if (!Array.isArray(review.allowedModes) || review.allowedModes.length === 0) {
+        errors.push(`review ${id} allowedModes must be a non-empty array, or omitted to allow every mode`);
+      } else if (review.allowedModes.some(mode => !SEED_MODES.has(mode))) {
+        errors.push(`review ${id} allowedModes may only contain ${[...SEED_MODES].join(', ')}`);
+      } else if (new Set(review.allowedModes).size !== review.allowedModes.length) {
+        errors.push(`review ${id} allowedModes must not repeat a mode`);
+      } else if (review.allowedModes.length === SEED_MODES.size) {
+        errors.push(`review ${id} allowedModes lists every mode; omit the field instead`);
+      }
+    }
   }
 
   const wellTierById = new Map((catalog?.wells || []).map(well => [well.id, well.tier]));
@@ -320,10 +394,3 @@ export function approvedPoolRevision(concepts) {
   return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 12);
 }
 
-export function deterministicRank(items, input, idFor = item => item.id) {
-  return [...items].sort((a, b) => {
-    const scoreA = crypto.createHash('sha256').update(`${input}:${idFor(a)}`).digest('hex');
-    const scoreB = crypto.createHash('sha256').update(`${input}:${idFor(b)}`).digest('hex');
-    return scoreB.localeCompare(scoreA) || idFor(a).localeCompare(idFor(b));
-  });
-}

.agents/skills/impeccable/scripts/lib/design-parser.mjs

@@ -2,15 +2,20 @@
 // the live-mode design-system panel can render. Deterministic, dependency-free.
 //
 // Two-layer: YAML frontmatter (machine-readable tokens) + markdown body
-// (prose with six canonical H2 sections). When frontmatter is present, it's
+// (prose with eight canonical H2 sections). When frontmatter is present, it's
 // exposed on `model.frontmatter` alongside the prose-scraped sections;
 // consumers can prefer frontmatter values and fall back to prose.
 
+// Array order is also match precedence: matchCanonicalSection's keyword-contained
+// pass returns the first entry a heading contains, so reordering this changes
+// which section an ambiguous heading resolves to.
 const CANONICAL_SECTIONS = [
   'Overview',
   'Colors',
   'Typography',
+  'Layout',
   'Elevation',
+  'Shapes',
   'Components',
   "Do's and Don'ts",
 ];
@@ -115,10 +120,71 @@ function stripInlineYamlComment(s) {
   return s;
 }
 
+// YAML double-quoted scalars process backslash escapes. Stripping the outer
+// quotes without unescaping leaves them in place, so a nested font family like
+//   fontFamily: "\"IBM Plex Sans\", system-ui, sans-serif"
+// keeps its literal backslashes and never matches the same family in CSS.
+// The full YAML 1.2 double-quote escape set (spec section 5.7).
+const YAML_SIMPLE_ESCAPES = {
+  '0': '\0',
+  a: '\x07',
+  b: '\b',
+  t: '\t',
+  n: '\n',
+  v: '\v',
+  f: '\f',
+  r: '\r',
+  e: '\x1b',
+  ' ': ' ',
+  '"': '"',
+  '/': '/',
+  '\\': '\\',
+  N: '\u0085',
+  _: '\u00a0',
+  L: '\u2028',
+  P: '\u2029',
+};
+const YAML_HEX_ESCAPE_LENGTHS = { x: 2, u: 4, U: 8 };
+
+function unescapeYamlDoubleQuoted(body) {
+  let out = '';
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch !== '\\' || i === body.length - 1) {
+      out += ch;
+      continue;
+    }
+    const next = body[i + 1];
+    if (Object.prototype.hasOwnProperty.call(YAML_SIMPLE_ESCAPES, next)) {
+      out += YAML_SIMPLE_ESCAPES[next];
+      i++;
+      continue;
+    }
+    // \xNN, \uNNNN, \UNNNNNNNN. Malformed or out-of-range sequences stay
+    // literal rather than corrupting the rest of the scalar.
+    const hexLen = YAML_HEX_ESCAPE_LENGTHS[next];
+    if (hexLen) {
+      const hex = body.slice(i + 2, i + 2 + hexLen);
+      const codePoint = hex.length === hexLen && /^[0-9a-fA-F]+$/.test(hex) ? parseInt(hex, 16) : -1;
+      if (codePoint >= 0 && codePoint <= 0x10ffff) {
+        out += String.fromCodePoint(codePoint);
+        i += 1 + hexLen;
+        continue;
+      }
+    }
+    out += ch;
+  }
+  return out;
+}
+
 function parseScalar(raw) {
   const s = raw.trim();
-  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-    return s.slice(1, -1);
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return unescapeYamlDoubleQuoted(s.slice(1, -1));
+  }
+  // Single-quoted YAML escapes only the quote itself, by doubling it.
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1).split("''").join("'");
   }
   if (s === 'true') return true;
   if (s === 'false') return false;
@@ -330,17 +396,16 @@ function extractOverview(section) {
   if (!section) return null;
   const text = section.lines.join('\n');
   const northStar = text.match(/\*\*Creative North Star:\s*"([^"]+)"\*\*/);
-  const keyChars = [];
   const keyCharMatch = text.match(/\*\*Key Characteristics:\*\*\s*\n([\s\S]+?)(?:\n##|\n###|$)/);
-  if (keyCharMatch) {
-    for (const line of keyCharMatch[1].split('\n')) {
-      const m = line.match(/^\s*[-*]\s+(.+)$/);
-      if (m) keyChars.push(stripBold(m[1].trim()));
-    }
-  }
+  const keyChars = keyCharMatch
+    ? collectBullets(keyCharMatch[1].split('\n')).map((bullet) => stripBold(bullet.trim()))
+    : [];
+  const prose = keyCharMatch
+    ? text.slice(0, keyCharMatch.index) + text.slice(keyCharMatch.index + keyCharMatch[0].length)
+    : text;
 
   // Philosophy paragraphs: everything that isn't a rule header or key-char block
-  const paragraphs = collectParagraphs(section.lines).filter(
+  const paragraphs = collectParagraphs(prose.split('\n')).filter(
     (p) =>
       !p.startsWith('**Creative North Star') &&
       !p.startsWith('**Key Characteristics')
@@ -602,11 +667,19 @@ function parseTypeBullet(bullet) {
   };
 }
 
-function extractElevation(section) {
+function extractGuidance(section) {
   if (!section) return null;
   const subs = splitSubsections(section.lines);
+  return {
+    subtitle: section.subtitle,
+    description: collectParagraphs(subs[0].lines).join(' ') || null,
+    rules: extractNamedRules(section.lines),
+  };
+}
 
-  const description = collectParagraphs(subs[0].lines).join(' ') || null;
+function extractElevation(section) {
+  const guidance = extractGuidance(section);
+  if (!guidance) return null;
 
   const shadows = [];
   const seen = new Set();
@@ -631,12 +704,7 @@ function extractElevation(section) {
     for (const inline of extractInlineShadows(b)) dedupe(inline);
   }
 
-  return {
-    subtitle: section.subtitle,
-    description,
-    shadows,
-    rules: extractNamedRules(section.lines),
-  };
+  return { ...guidance, shadows };
 }
 
 function extractInlineShadows(text) {
@@ -768,6 +836,15 @@ function extractDosDonts(section) {
 
 // ---------- Coverage assessment ----------
 
+// Sections whose model is description-plus-rules only (see extractGuidance).
+const guidanceCoverage = (guidance) =>
+  guidance
+    ? {
+        description: Boolean(guidance.description),
+        rules: guidance.rules.length,
+      }
+    : 'missing';
+
 function assessCoverage(model) {
   const report = {};
 
@@ -796,6 +873,8 @@ function assessCoverage(model) {
       }
     : 'missing';
 
+  report.layout = guidanceCoverage(model.layout);
+
   report.elevation = model.elevation
     ? {
         shadows: model.elevation.shadows.length,
@@ -804,6 +883,8 @@ function assessCoverage(model) {
       }
     : 'missing';
 
+  report.shapes = guidanceCoverage(model.shapes);
+
   report.components = model.components
     ? {
         count: model.components.components.length,
@@ -833,7 +914,9 @@ export function parseDesignMd(md) {
     overview: extractOverview(sections['Overview']),
     colors: extractColors(sections['Colors']),
     typography: extractTypography(sections['Typography']),
+    layout: extractGuidance(sections['Layout']),
     elevation: extractElevation(sections['Elevation']),
+    shapes: extractGuidance(sections['Shapes']),
     components: extractComponents(sections['Components']),
     dosDonts: extractDosDonts(sections["Do's and Don'ts"]),
   };

.agents/skills/impeccable/scripts/lib/impeccable-config.mjs

@@ -529,6 +529,9 @@ function extractFindingIgnoreValueRaw(finding, rule = normalizeIgnoreRule(findin
     const primary = text.match(/Primary font:\s*([^()\n;]+)/i);
     if (primary) return cleanIgnoreValueDisplay(primary[1]);
 
+    const googleLabel = text.match(/Google Fonts:\s*([^()\n;]+)/i);
+    if (googleLabel) return cleanIgnoreValueDisplay(googleLabel[1]);
+
     const family = text.match(/font-family\s*:\s*["']?([^'",;\n]+)/i);
     if (family) return cleanIgnoreValueDisplay(family[1]);
 

.agents/skills/impeccable/scripts/lib/open-system-browser.mjs

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+
+export function browserOpenCommand(url, {
+  platform = process.platform,
+  comspec = process.env.ComSpec || process.env.COMSPEC || 'cmd.exe',
+} = {}) {
+  if (platform === 'darwin') return { command: 'open', args: [url] };
+  if (platform === 'win32') return { command: comspec, args: ['/c', 'start', '', url] };
+  return { command: 'xdg-open', args: [url] };
+}
+
+export function openSystemBrowser(url, {
+  platform = process.platform,
+  comspec = process.env.ComSpec || process.env.COMSPEC || 'cmd.exe',
+  spawnImpl = spawn,
+} = {}) {
+  const { command, args } = browserOpenCommand(url, { platform, comspec });
+  try {
+    const child = spawnImpl(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}

.agents/skills/impeccable/scripts/lib/roll-selection.mjs

@@ -0,0 +1,369 @@
+// The one implementation of world-roll selection.
+//
+// Two copies of this logic used to exist: this repo's concept-seed.mjs and the
+// service repo's functions/api/_worldroll-core.js, whose header claimed they
+// matched "exactly". They did not. The API had no breadth gate on either pool,
+// no rating weighting for compositions, and dealt one composition where the
+// seeder dealt three. Because the catalog never ships with the skill, every real
+// user rolls through that API, so those gates reached nobody.
+//
+// Why generators. The two callers cannot agree on a hash: Node has a
+// synchronous one, Workers only have async crypto.subtle, and concept-seed's
+// local render path is deliberately synchronous so prepared eval sessions and
+// tests can call it without awaiting. Rather than fork the logic or force the
+// whole seeder async, the selection is written once as a generator that yields
+// batches of strings to hash and resumes with their digests. runSyncSelection
+// and runAsyncSelection below are the only runtime-specific code, about eight
+// lines each. Both digests are the same bytes, so a roll is identical either way.
+//
+// Nothing here reads a file, an environment variable, or the network: callers
+// pass pools in.
+
+export const WELL_TIERS = ['graphic', 'interaction', 'atmosphere'];
+
+// Grain: how much of the product a composition composes. Named grain rather than
+// scope because scope already means direction-or-surface on every roll, and
+// 'surface' is already a register value, so a scope of 'surface' would collide
+// with both.
+//
+// This axis is framed by what the skill can be asked for, not by what the
+// catalog happens to hold. A user asks for a docs site, an onboarding flow, a
+// landing page, or a data table, and those are four different amounts of
+// product. Register says what kind of work it is; grain says how much of it.
+// Without grain, a request for a hero section can be dealt a whole-site
+// navigation structure and nothing notices.
+//
+// Measured when this was added: 137 of 173 approved compositions were view
+// grain, product grain was empty, and flow grain held one entry. That is why an
+// onboarding request had nothing to draw.
+export const COMPOSITION_GRAINS = [
+  'product', // a whole site or app: its information architecture
+  'flow',    // a sequence of views with one outcome: onboarding, checkout, setup
+  'view',    // one page or screen
+  'region',  // a section inside a view: a hero, a feature grid, a table
+];
+
+// Delivery targets a composition can survive. Mirrors the skill's platform axis
+// minus 'adaptive', which is a project-level value meaning both native targets
+// rather than something a single composition is authored for.
+//
+// A composition that leans on hover, a pointer, or a wide viewport does not
+// survive a phone, and nothing in the schema could say so before this.
+export const COMPOSITION_PLATFORMS = ['web', 'ios', 'android'];
+
+// Both fields are optional and absence means eligible everywhere, so no entry
+// has to be backfilled before this ships and no existing roll changes.
+export function isGrain(value) {
+  return COMPOSITION_GRAINS.includes(value);
+}
+
+export function isPlatform(value) {
+  return COMPOSITION_PLATFORMS.includes(value);
+}
+
+
+/**
+ * Drives a selection generator with a synchronous hash.
+ * @param {Generator} generator yields string[] to hash, resumes with hex string[]
+ * @param {(input: string) => string} hash
+ */
+export function runSyncSelection(generator, hash) {
+  let step = generator.next();
+  while (!step.done) step = generator.next(step.value.map(hash));
+  return step.value;
+}
+
+/**
+ * Drives a selection generator with an asynchronous hash.
+ * @param {Generator} generator
+ * @param {(input: string) => Promise<string>} hash
+ */
+export async function runAsyncSelection(generator, hash) {
+  let step = generator.next();
+  while (!step.done) step = generator.next(await Promise.all(step.value.map(hash)));
+  return step.value;
+}
+
+// Ranks items by the digest of `${input}:${id}`, descending, with the id as a
+// stable tiebreak. Yields every needed digest in one batch so the async driver
+// can resolve them concurrently.
+function* rank(items, input, idFor = item => item.id) {
+  const ids = items.map(idFor);
+  const digests = yield ids.map(id => `${input}:${id}`);
+  return items
+    .map((item, index) => ({ item, id: ids[index], score: digests[index] }))
+    .sort((a, b) => b.score.localeCompare(a.score) || a.id.localeCompare(b.id))
+    .map(entry => entry.item);
+}
+
+// Rating sets how many tickets a world holds; breadth decides whether it draws
+// at all. A niche world leaves the pool however good it is, keeping its approval
+// for direct briefs. Breadth was split out of rating because the only way to
+// hold a narrow world back used to be calling it marginal, which made "excellent
+// but narrow" unrecordable and corrupted ratings as a calibration signal.
+//
+// Two tickets for a 3-star, one for everything else, was too sharp. Measured
+// against the catalog as it stood: 3-star worlds absorbed 57% of the graphic
+// draw from 65 of 163 eligible worlds, 46% of atmosphere from 13 of 43, and
+// 75% of interaction from 15 of 25. The reviewer's complaint, that the same
+// worlds keep coming back, is what a rating multiplier does to a pool whose
+// thinnest tier holds 25 worlds.
+//
+// So a 3-star no longer outdraws a 2-star, and a 1-star draws at half rather
+// than not at all. A marginal keep is still worth showing sometimes: the
+// judgement it records is "narrow or unexceptional", not "wrong", and excluding
+// it entirely made a rating do a job breadth already does properly.
+const RATING_TICKETS = { 1: 1, 2: 2, 3: 2 };
+const ticketsForRating = rating => RATING_TICKETS[rating] ?? 2;
+
+function challengerTickets(pool) {
+  return pool.flatMap(concept => {
+    if (concept.review?.breadth === 'niche') return [];
+    return Array.from({ length: ticketsForRating(concept.review?.rating) },
+      (_, ticket) => ({ concept, ticket }));
+  });
+}
+
+function compositionTickets(pool) {
+  return pool.flatMap(composition => Array.from(
+    { length: ticketsForRating(composition.review?.rating) },
+    (_, ticket) => ({ composition, ticket })));
+}
+
+/**
+ * Six challengers, two per translation tier, from an explicit approved pool.
+ * Drive with runSyncSelection or runAsyncSelection.
+ *
+ * @param {object} options
+ * @param {'direction'|'surface'} options.scope
+ * @param {string} options.key              same key reproduces the roll
+ * @param {number} [options.reroll]         round of the re-roll chain
+ * @param {number|null} [options.minRating] optional floor, skipped per tier it would empty
+ * @param {Array} options.concepts          merged concepts with status, review, wellTier, familyId
+ * @returns {Generator<string[], {approved: Array, picks: Array}, string[]>}
+ */
+// A world with no allowedModes is eligible everywhere, which is what keeps this
+// additive: nothing has to be backfilled for the filter to be safe.
+function modeAllows(concept, mode) {
+  const allowed = concept.review?.allowedModes;
+  if (!Array.isArray(allowed) || allowed.length === 0) return true;
+  return allowed.includes(mode);
+}
+
+export function* selectApprovedChallengers({ scope, key, reroll = 0, minRating = null, mode = null, concepts }) {
+  const approved = concepts.filter(concept => concept.status === 'approved');
+  // Direction chooses a durable identity, so it draws worlds; surface designs
+  // one page inside a committed identity, so it draws compositions. Duals serve
+  // both. A tier with no matching-strength approvals falls back to its full
+  // approved pool rather than starving the roll.
+  const wanted = scope === 'direction'
+    ? new Set(['world', 'dual'])
+    : new Set(['composition', 'dual']);
+
+  const approvedByTier = new Map();
+  for (const concept of approved) {
+    const tier = approvedByTier.get(concept.wellTier) || [];
+    tier.push(concept);
+    approvedByTier.set(concept.wellTier, tier);
+  }
+  if (WELL_TIERS.some(tier => !(approvedByTier.get(tier) || []).length)) {
+    throw new Error('concept-seed: every challenger tier needs at least one approved concept');
+  }
+
+  // Optional minimum-rating gate, applied per tier and skipped for any tier it
+  // would empty, so a thin tier degrades to its full approved pool.
+  if (minRating) {
+    for (const [tier, pool] of approvedByTier) {
+      const rated = pool.filter(concept => (concept.review?.rating || 0) >= minRating);
+      if (rated.length > 0) approvedByTier.set(tier, rated);
+    }
+  }
+  // Mode eligibility, per tier and skipped where it would empty a tier. Worlds
+  // used to be drawn with no mode awareness at all, so a build asking for an app
+  // UI could get six worlds that only make sense on a landing page. A world is an
+  // identity and identities transfer further than compositions do, so this is a
+  // ceiling the reviewer sets rather than a category assignment: eligible
+  // everywhere until someone says otherwise.
+  if (mode) {
+    for (const [tier, pool] of approvedByTier) {
+      const eligible = pool.filter(concept => modeAllows(concept, mode));
+      if (eligible.length > 0) approvedByTier.set(tier, eligible);
+    }
+  }
+  for (const [tier, pool] of approvedByTier) {
+    const matching = pool.filter(concept => wanted.has(concept.strength));
+    if (matching.length > 0) approvedByTier.set(tier, matching);
+  }
+
+  // Two challengers per tier, so every roll carries near-zero-translation
+  // graphic systems beside instrument languages and atmosphere worlds, with the
+  // second pick preferring a different family. Tier order is rolled too, to
+  // avoid positional bias.
+  function* pickRound(round, excluded) {
+    const salt = round === 0 ? '' : `:reroll-${round}`;
+    const tierOrder = (yield* rank(
+      WELL_TIERS.map(id => ({ id })),
+      `${scope}:${key}:tiers${salt}`
+    )).map(item => item.id);
+    const picks = [];
+    for (const [index, tier] of tierOrder.entries()) {
+      let pool = approvedByTier.get(tier).filter(concept => !excluded.has(concept.id));
+      // A tier exhausted by prior rounds falls back to reuse over starvation.
+      if (pool.length === 0) pool = approvedByTier.get(tier);
+      let tickets = challengerTickets(pool);
+      if (tickets.length === 0) tickets = pool.map(concept => ({ concept, ticket: 0 }));
+      const ranked = yield* rank(
+        tickets,
+        `${scope}:${key}:challenger-${index}${salt}`,
+        entry => `${entry.concept.id}#${entry.ticket}`
+      );
+      const order = [];
+      const seen = new Set();
+      for (const entry of ranked) {
+        if (seen.has(entry.concept.id)) continue;
+        seen.add(entry.concept.id);
+        order.push(entry.concept);
+      }
+      const first = order[0];
+      const second = order.find(concept => concept.familyId !== first.familyId)
+        || order.find(concept => concept.id !== first.id);
+      picks.push(...(second ? [first, second] : [first]));
+    }
+    return picks;
+  }
+
+  // Round n of a re-roll chain excludes everything rounds 0..n-1 drew, so the
+  // same base key reproduces the whole chain.
+  const excluded = new Set();
+  let picks = yield* pickRound(0, excluded);
+  for (let round = 1; round <= reroll; round += 1) {
+    for (const pick of picks) excluded.add(pick.id);
+    picks = yield* pickRound(round, excluded);
+  }
+  return { approved, picks };
+}
+
+function emptyMatch(grain, platform, platformExcluded = 0) {
+  return { grain: grain ?? null, atGrain: grain ? 0 : null, grainAvailable: grain ? 0 : null, platform: platform ?? null, platformExcluded };
+}
+
+/**
+ * Three identity-free composition inputs from an explicit approved pool.
+ * Drive with runSyncSelection or runAsyncSelection.
+ *
+ * One input was too weak a counterweight to a model's habitual page skeleton:
+ * it became a single optional flourish beside six identity challengers rather
+ * than a real search over composition. Distinct composition families are preferred
+ * so a roll tests materially different hierarchy, sequence, and interaction
+ * laws. Cross-mode fallback would make the input misleading, so an absent mode
+ * returns nothing rather than borrowing. Re-rolls exclude every earlier set
+ * until the pool runs out.
+ *
+ * @param {object} options
+ * @param {'direction'|'surface'} options.scope
+ * @param {string} options.key
+ * @param {number} [options.reroll]
+ * @param {string|null} [options.mode]  surface register to stay inside
+ * @param {string|null} [options.grain]     how much of the product is in play
+ * @param {string|null} [options.platform]  delivery target the result has to survive
+ * @param {Array} options.compositions  merged compositions with status, review, surface, familyId
+ * @param {number} [options.count]
+ * @returns {Generator<string[], {picks: Array, match: object}, string[]>}
+ */
+export function* selectApprovedCompositions({ scope, key, reroll = 0, mode = null, grain = null, platform = null, compositions, count = 3 }) {
+  // Compositions honour the same breadth gate as worlds: one too specific to serve
+  // an arbitrary build stays approved for direct briefs and leaves the
+  // challenger pool. Falls back to the full approved set rather than returning
+  // nothing if every approved composition is niche.
+  let approved = compositions.filter(composition => composition.status === 'approved');
+  const broad = approved.filter(composition => composition.review?.breadth !== 'niche');
+  if (broad.length > 0) approved = broad;
+  if (approved.length === 0) return { picks: [], match: emptyMatch(grain, platform) };
+  if (mode) {
+    const matching = approved.filter(composition => composition.surface === mode);
+    if (matching.length === 0) return { picks: [], match: emptyMatch(grain, platform) };
+    approved = matching;
+  }
+  // Platform is a hard filter, unlike grain. A composition that needs hover or a
+  // pointer does not degrade on a phone into something slightly worse; it stops
+  // working, so borrowing it would be a defect rather than a stretch. Absent
+  // platforms means it survives anywhere.
+  let platformExcluded = 0;
+  if (platform) {
+    const survives = approved.filter(composition => {
+      const only = composition.platforms;
+      return !Array.isArray(only) || only.length === 0 || only.includes(platform);
+    });
+    platformExcluded = approved.length - survives.length;
+    // No fallback here either: dealing a hover-only composition to a phone build
+    // is worse than dealing nothing, and an empty deal is a visible gap.
+    approved = survives;
+    if (approved.length === 0) return { picks: [], match: emptyMatch(grain, platform, platformExcluded) };
+  }
+
+  const prior = new Set();
+  let picks = [];
+  for (let round = 0; round <= reroll; round += 1) {
+    const available = approved.filter(composition => !prior.has(composition.id));
+    const base = available.length >= Math.min(count, approved.length) ? available : approved;
+    // Rating weights the draw as it does for worlds. It matters more here
+    // because the per-surface pools are small, so an unweighted shuffle repeats
+    // a weak composition far more often. Each ticket carries its index so the rank
+    // sees a distinct key per ticket: ranking bare duplicates would hash
+    // identically and the pick loop's id-dedupe would silently discard the
+    // second copy, making the weighting a no-op.
+    let tickets = compositionTickets(base);
+    // A pool of nothing but 1-star keeps still has to yield compositions.
+    if (tickets.length === 0) tickets = base.map(composition => ({ composition, ticket: 0 }));
+    const ranked = (yield* rank(
+      tickets,
+      // The salt keeps the word "staging" deliberately. It is hash input, so
+      // renaming it would re-deal every roll anyone has ever reproduced by key.
+      round === 0 ? `${scope}:${key}:staging` : `${scope}:${key}:staging:reroll-${round}`,
+      entry => `${entry.composition.id}#${entry.ticket}`
+    )).map(entry => entry.composition);
+
+    // Grain is a preference, not a filter: requesting an onboarding flow deals
+    // flow-grain compositions first and tops up from the rest of the register
+    // rather than dealing fewer than three. A stable partition of an already
+    // deterministic ranking is still deterministic.
+    //
+    // The top-up is why match is reported. Dealing three plausible view-grain
+    // compositions against a flow request, with no signal that none matched, is
+    // the same silent-plausibility failure this whole axis exists to fix: the
+    // model would improvise the flow structure while believing it was handed one.
+    const ordered = grain
+      ? [...ranked.filter(composition => composition.grain === grain),
+         ...ranked.filter(composition => composition.grain !== grain)]
+      : ranked;
+
+    const families = new Set();
+    picks = [];
+    for (const composition of ordered) {
+      const family = composition.familyId ?? composition.id;
+      if (families.has(family)) continue;
+      picks.push(composition);
+      families.add(family);
+      if (picks.length >= count) break;
+    }
+    for (const composition of ordered) {
+      if (picks.length >= count) break;
+      if (!picks.some(pick => pick.id === composition.id)) picks.push(composition);
+    }
+    if (round < reroll) picks.forEach(composition => prior.add(composition.id));
+  }
+
+  const atGrain = grain ? picks.filter(composition => composition.grain === grain).length : null;
+  return {
+    picks,
+    match: {
+      grain: grain ?? null,
+      // How many of the dealt compositions actually sit at the requested grain.
+      // 0 with a grain requested means every pick is a borrowed structure.
+      atGrain,
+      grainAvailable: grain ? approved.filter(composition => composition.grain === grain).length : null,
+      platform: platform ?? null,
+      platformExcluded,
+    },
+  };
+}

.agents/skills/impeccable/scripts/lib/staleness-deep.mjs

@@ -117,6 +117,23 @@ export function checkDesignDrift({ designPath, projectRoot, threshold = 25 }) {
  * a section can be absent because it never applied, so this is reported as a
  * documentation gap for a human to judge, never as an error.
  */
+function hasCoverageValue(value) {
+  if (Array.isArray(value)) return value.some(hasCoverageValue);
+  if (value && typeof value === 'object') {
+    return Object.values(value).some(hasCoverageValue);
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 && !/^(?:\[\s*\]|\{\s*\})$/.test(trimmed);
+  }
+  return false;
+}
+
+const SEED_DESIGN_MARKERS = ['/', '$'].map((prefix) =>
+  '<!-- SEED: established with the user before implementation; '
+    + `re-run ${prefix}impeccable document once there's code to capture the actual tokens and components. -->`
+);
+
 export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   if (!design || typeof parseDesignMd !== 'function') return [];
   let model;
@@ -125,8 +142,12 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   } catch {
     return [];
   }
-  const missing = ['colors', 'typography', 'components']
-    .filter((section) => !model[section]);
+  const isSeed = SEED_DESIGN_MARKERS.some((marker) => design.includes(marker));
+  const requiredSections = isSeed
+    ? ['colors', 'typography']
+    : ['colors', 'typography', 'components'];
+  const missing = requiredSections
+    .filter((section) => !model[section] && !hasCoverageValue(model.frontmatter?.[section]));
   if (!missing.length) return [];
   return [finding({
     id: 'design-md-coverage',

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

@@ -27,6 +27,7 @@ import {
   inlineSvelteComponentAccept,
   removeSvelteComponentSession,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 const ACCEPT_LOCK_WAIT_MS = 1_000;
 // Mirrors VARIANT_ID_PATTERN in live/event-validation.mjs, which gates the same
@@ -946,6 +947,7 @@ function argVal(args, flag) {
 // Auto-execute when run directly
 const _running = process.argv[1];
 if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
+  enterLiveRoot();
   acceptCli();
 }
 

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

@@ -3,8 +3,12 @@
  * Canonical durable completion acknowledgement for Impeccable live sessions.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { createLiveSessionStore } from './live/session-store.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
+import { verifyAcceptedFile } from './live/accept-verify.mjs';
 
 function parseArgs(argv) {
   const out = { status: 'complete' };
@@ -15,6 +19,7 @@ function parseArgs(argv) {
     else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
     else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
     else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
+    else if (arg === '--force') out.force = true;
     else if (arg === '--help' || arg === '-h') out.help = true;
   }
   return out;
@@ -23,10 +28,36 @@ function parseArgs(argv) {
 export async function completeCli() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help || !args.id) {
-    console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
+    console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE] [--force]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.\nCompletion is refused while the session's source file still carries live-mode leftovers\n(markers, data-p-* attributes, unbaked --p-* vars); fix the file or pass --force.`);
     process.exit(args.help ? 0 : 1);
   }
 
+  // The carbonize contract used to be prose; this makes it mechanical. A
+  // "complete" while the source still carries live plumbing is how markers
+  // and dead param branches accumulated across sessions.
+  if (args.status === 'complete' && !args.force) {
+    const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
+    const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
+    const sourceFile = snapshot?.sourceFile;
+    const absSource = sourceFile ? path.resolve(process.cwd(), sourceFile) : null;
+    const relSource = absSource ? path.relative(process.cwd(), absSource) : null;
+    const insideProject = relSource !== null && relSource !== '' && !relSource.startsWith('..') && !path.isAbsolute(relSource);
+    if (insideProject && !relSource.startsWith('node_modules' + path.sep) && !relSource.startsWith('node_modules/')) {
+      const verify = verifyAcceptedFile(fs, absSource);
+      if (!verify.clean) {
+        console.log(JSON.stringify({
+          ok: false,
+          error: 'source_dirty',
+          id: args.id,
+          file: sourceFile,
+          findings: verify.findings,
+          hint: 'The accepted source still carries live-mode leftovers. Finish the carbonize cleanup (bake params, remove markers and data-p-* attributes), then run live-complete again. Use --force only if a finding is a false positive.',
+        }, null, 2));
+        process.exit(1);
+      }
+    }
+  }
+
   const serverInfo = readServerInfo();
   const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
   if (serverResult?.ok) {
@@ -71,5 +102,6 @@ async function completeThroughServer(info, args) {
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
+  enterLiveRoot();
   completeCli();
 }

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

@@ -7,6 +7,11 @@
  * every subsequent run, this script handles insert/remove deterministically
  * with zero LLM involvement.
  *
+ * Framework knowledge lives in `live/frameworks/` — detection order, adapters,
+ * the generic tag strategy, and the per-extension authoring traits live-wrap
+ * reads. This file is the CLI around it: resolve config, resolve the
+ * framework, heal orphaned artifacts, apply or remove, record the journal.
+ *
  * Usage:
  *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
  *   node live-inject.mjs --remove                     # Remove the live script tag
@@ -23,22 +28,36 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
 import {
-  applySvelteKitLiveAdapter,
-  detectSvelteKitProject,
-  removeSvelteKitLiveAdapter,
-} from './live/sveltekit-adapter.mjs';
+  describeInjectArtifacts,
+  frameworkIgnorePatterns,
+  resolveFramework,
+  resolveSourceTraits,
+} from './live/frameworks/index.mjs';
 import {
-  applyTanStackLiveAdapter,
-  detectTanStackStartProject,
-  removeTanStackLiveAdapter,
-} from './live/tanstack-adapter.mjs';
+  clearInjectJournal,
+  healInjectJournal,
+  recordInjection,
+} from './live/frameworks/journal.mjs';
+import {
+  buildTagBlock,
+  insertTag,
+  patchCspMeta,
+  removeTag,
+  revertCspMeta,
+} from './live/frameworks/tag-strategy.mjs';
+import { buildLiveScriptSrc } from './live/frameworks/script-src.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
-const MARKER_OPEN_TEXT = 'impeccable-live-start';
-const MARKER_CLOSE_TEXT = 'impeccable-live-end';
-const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
-const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
+// Resolved lazily so the enterLiveRoot() chdir in the CLI guard below takes
+// effect first; module scope runs before the guard.
+let CONFIG_PATH_CACHED = null;
+function CONFIG_PATH_GET() {
+  if (!CONFIG_PATH_CACHED) {
+    CONFIG_PATH_CACHED = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
+  }
+  return CONFIG_PATH_CACHED;
+}
 const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
 const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
 
@@ -47,6 +66,9 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
   '.impeccable/hook.pending.json',
   '.impeccable/config.local.json',
   '.impeccable/live/server.json',
+  '.impeccable/live/roots.json',
+  '.impeccable/live/app-root.json',
+  '.impeccable/live/inject-journal.json',
   '.impeccable/live/sessions/',
   '.impeccable/live/previews/',
   '.impeccable/live/annotations/',
@@ -102,60 +124,61 @@ Output (JSON):
   }
 
   if (args.includes('--check')) {
-    if (!fs.existsSync(CONFIG_PATH)) {
-      console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+    // Deliberately read-only: --check runs from status paths and must never
+    // mutate the tree. Journal reconciliation happens on the inject run.
+    if (!fs.existsSync(CONFIG_PATH_GET())) {
+      console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
       process.exit(0);
     }
     let cfg;
     try {
-      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
     } catch (err) {
-      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
       return;
     }
     try {
       validateConfig(cfg);
     } catch (err) {
-      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
       return;
     }
-    console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
+    console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH_GET() }));
     return;
   }
 
   // Load config
-  if (!fs.existsSync(CONFIG_PATH)) {
-    console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+  if (!fs.existsSync(CONFIG_PATH_GET())) {
+    console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
     process.exit(1);
   }
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
   validateConfig(config);
 
-  const resolvedFiles = resolveFiles(process.cwd(), config);
-  const svelteKit = detectSvelteKitProject(process.cwd(), config);
-  const nuxt = detectNuxtProject(process.cwd());
-  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
+  const cwd = process.cwd();
+  const resolvedFiles = resolveFiles(cwd, config);
+  const resolved = resolveFramework(cwd, config);
+  const isAdapter = resolved?.framework.inject.kind === 'adapter';
 
   if (args.includes('--remove')) {
-    if (svelteKit) {
-      const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
-      console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
-      return;
-    }
-    if (tanstack) {
-      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
-      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
-      if (adapterResult.error) process.exitCode = 1;
-      return;
-    }
-    if (nuxt) {
-      const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
-      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
-      if (adapterResult.error) process.exitCode = 1;
+    if (isAdapter) {
+      const adapterResult = resolved.framework.inject.remove({ cwd, config, project: resolved.project });
+      const ok = !(adapterResult && adapterResult.error);
+      // Anything the adapter could not reach (its detection may have shifted
+      // since the session started) is still on the journal.
+      const { healed } = healInjectJournal(cwd);
+      clearInjectJournal(cwd);
+      console.log(JSON.stringify({
+        ok,
+        adapter: resolved.framework.name,
+        results: [adapterResult],
+        healed: healed.length ? healed : undefined,
+      }));
+      if (!ok) process.exitCode = 1;
       return;
     }
     const results = resolvedFiles.map((relFile) => {
-      const absFile = path.resolve(process.cwd(), relFile);
+      const absFile = path.resolve(cwd, relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
       const content = fs.readFileSync(absFile, 'utf-8');
       const detagged = removeTag(content, config.commentSyntax);
@@ -168,7 +191,9 @@ Output (JSON):
         cspReverted: updated !== detagged,
       };
     });
-    console.log(JSON.stringify({ ok: true, results }));
+    const { healed } = healInjectJournal(cwd);
+    clearInjectJournal(cwd);
+    console.log(JSON.stringify({ ok: true, results, healed: healed.length ? healed : undefined }));
     return;
   }
 
@@ -180,50 +205,68 @@ Output (JSON):
     process.exit(1);
   }
   // Optional server token: appended to the /live.js src so the token-gated
-  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes
+  // it; a manual `--port`-only invocation reads the running helper's token
+  // from server.json instead of writing an unauthenticated URL that 401s.
   const tokenIdx = args.indexOf('--token');
-  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
-  const gitIgnore = ensureLiveGitIgnores(
-    process.cwd(),
-    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
-  );
+  let token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
+  if (!token) {
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'server.json'), 'utf-8'));
+      // A record for a DIFFERENT port is a stale or foreign helper; its token
+      // would 401 just the same, so only adopt a matching one.
+      if (info?.token && Number(info.port) === port) token = info.token;
+    } catch { /* no running helper recorded; keep legacy tokenless behavior */ }
+  }
 
-  if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
-    console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
-    return;
-  }
-  if (tanstack) {
-    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
-    console.log(JSON.stringify({
-      ok: !adapterResult.error,
+  // Reconcile before writing anything. Artifacts this run is about to own are
+  // kept (so a repeat inject stays byte-idempotent); artifacts left behind by
+  // a session that never got to stop are healed.
+  const plannedArtifacts = describeInjectArtifacts(resolved, { cwd, files: resolvedFiles });
+  const { healed } = healInjectJournal(cwd, { keep: plannedArtifacts.map((a) => a.path) });
+
+  const gitIgnore = ensureLiveGitIgnores(cwd, frameworkIgnorePatterns(resolved));
+  // In a nested-app repo the roots pointer lives at the REPO root, outside the
+  // reach of the appRoot-relative ignore block above; give that directory its
+  // own local excludes so the pointer (absolute host paths) never gets staged.
+  try {
+    const rootsManifest = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'roots.json'), 'utf-8'));
+    if (rootsManifest?.repoRoot && path.resolve(rootsManifest.repoRoot) !== path.resolve(cwd)) {
+      ensureLiveGitIgnores(rootsManifest.repoRoot);
+    }
+  } catch { /* no manifest: single-root project */ }
+
+  if (isAdapter) {
+    const adapterResult = resolved.framework.inject.apply({
+      cwd,
       port,
-      adapter: 'tanstack-start',
+      token,
+      config,
+      project: resolved.project,
+    });
+    const ok = !(adapterResult && adapterResult.error);
+    if (ok) recordInjection(cwd, { framework: resolved.framework.name, port, artifacts: plannedArtifacts });
+    console.log(JSON.stringify({
+      ok,
+      port,
+      adapter: resolved.framework.name,
       gitIgnore,
       results: [adapterResult],
+      healed: healed.length ? healed : undefined,
     }));
-    if (adapterResult.error) process.exitCode = 1;
-    return;
-  }
-  if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
-    console.log(JSON.stringify({
-      ok: !adapterResult.error,
-      port,
-      adapter: 'nuxt',
-      gitIgnore,
-      results: [adapterResult],
-    }));
-    if (adapterResult.error) process.exitCode = 1;
+    if (!ok) process.exitCode = 1;
     return;
   }
 
   const results = resolvedFiles.map((relFile) => {
-    const absFile = path.resolve(process.cwd(), relFile);
+    const absFile = path.resolve(cwd, relFile);
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile, token);
+    // Per-file, not per-project: a Vite app can hold an .astro partial, and a
+    // framework project's entry template is often plain HTML.
+    const scriptAttrs = resolveSourceTraits(relFile).injectScriptAttrs;
+    const withTag = insertTag(withoutOld, config, port, token, scriptAttrs);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -236,7 +279,19 @@ Output (JSON):
     };
   });
   const anyInserted = results.some((r) => r.inserted);
-  console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
+  const writtenFiles = new Set(results.filter((r) => r.inserted).map((r) => r.file));
+  recordInjection(cwd, {
+    framework: resolved?.framework.name,
+    port,
+    artifacts: plannedArtifacts.filter((a) => writtenFiles.has(a.path)),
+  });
+  console.log(JSON.stringify({
+    ok: anyInserted,
+    port,
+    gitIgnore,
+    results,
+    healed: healed.length ? healed : undefined,
+  }));
   if (!anyInserted) process.exit(1);
 }
 
@@ -271,115 +326,6 @@ export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Nuxt adapter
-//
-// A script element placed in app.vue is compiled as Vue-rendered DOM and is
-// not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
-// generated, dev-only, and outside user-authored source: Live creates one
-// marked .client.ts plugin on start and removes it on stop.
-// ---------------------------------------------------------------------------
-
-export function detectNuxtProject(cwd = process.cwd()) {
-  const configFile = fs.readdirSync(cwd, { withFileTypes: true })
-    .find((entry) => entry.isFile() && /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/.test(entry.name))
-    ?.name;
-  if (!configFile) return null;
-
-  const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
-  const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
-  let appDir = '';
-  if (literalSrcDir) {
-    const candidate = literalSrcDir[2]
-      .replace(/\\/g, '/')
-      .replace(/^\.\//, '')
-      .replace(/\/+$/, '');
-    const normalized = path.posix.normalize(candidate);
-    if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
-      appDir = normalized === '.' ? '' : normalized;
-    }
-  } else if (
-    fs.existsSync(path.join(cwd, 'app', 'app.vue'))
-    || fs.existsSync(path.join(cwd, 'app', 'pages'))
-  ) {
-    appDir = 'app';
-  }
-
-  const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
-  return { configFile, appDir, pluginFile };
-}
-
-export function buildNuxtPlugin(port, token) {
-  return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = '${buildLiveScriptSrc(port, token)}';
-const liveSelector = 'script[data-impeccable-live-nuxt]';
-
-export default defineNuxtPlugin(() => {
-  if (!import.meta.dev || typeof document === 'undefined') return;
-
-  const expectedSrc = new URL(liveSrc, window.location.href).href;
-  let script = document.querySelector(liveSelector);
-  if (script?.src === expectedSrc) return;
-  script?.remove();
-
-  script = document.createElement('script');
-  script.src = liveSrc;
-  script.async = true;
-  script.dataset.impeccableLiveNuxt = '';
-  document.head.appendChild(script);
-
-  import.meta.hot?.dispose(() => {
-    if (script?.isConnected) script.remove();
-  });
-});
-/* /${NUXT_PLUGIN_MARKER} */
-`;
-}
-
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
-  if (!project) return { error: 'nuxt_not_detected' };
-  const absFile = path.join(cwd, project.pluginFile);
-  const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
-  if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
-    return {
-      file: project.pluginFile,
-      error: 'nuxt_plugin_conflict',
-      hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
-    };
-  }
-
-  const content = buildNuxtPlugin(port, token);
-  fs.mkdirSync(path.dirname(absFile), { recursive: true });
-  if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
-  return {
-    file: project.pluginFile,
-    inserted: true,
-    changed: content !== existing,
-    devOnly: true,
-  };
-}
-
-export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
-  if (!project) return { error: 'nuxt_not_detected' };
-  const absFile = path.join(cwd, project.pluginFile);
-  if (!fs.existsSync(absFile)) {
-    return { file: project.pluginFile, removed: false, note: 'no adapter present' };
-  }
-  const content = fs.readFileSync(absFile, 'utf-8');
-  if (!content.includes(NUXT_PLUGIN_MARKER)) {
-    return {
-      file: project.pluginFile,
-      removed: false,
-      error: 'nuxt_plugin_conflict',
-      hint: `${project.pluginFile} is not managed by Impeccable Live`,
-    };
-  }
-  fs.unlinkSync(absFile);
-  const pluginDir = path.dirname(absFile);
-  if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
-  return { file: project.pluginFile, removed: true };
-}
-
 function resolveIgnoreTarget(cwd) {
   const gitExcludePath = resolveGitInfoExcludePath(cwd);
   if (gitExcludePath) {
@@ -527,242 +473,31 @@ function validateConfig(cfg) {
   }
 }
 
-function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
-function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
-
-/**
- * Build the /live.js src the browser loads. When a token is supplied it rides
- * as a `?token=...` query param so the server's token-gated /live.js handler
- * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
- * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
- */
-export function buildLiveScriptSrc(port, token) {
-  const base = 'http://localhost:' + port + '/live.js';
-  return token ? base + '?token=' + encodeURIComponent(token) : base;
-}
-
-function buildTagBlock(syntax, port, filePath, token) {
-  const open = commentOpen(syntax);
-  const close = commentClose(syntax);
-  // Astro processes <script> tags by default and rewrites src to its own
-  // bundled URL. is:inline opts out so the literal external src survives.
-  const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
-  const scriptAttrs = isAstro ? 'is:inline ' : '';
-  return (
-    open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
-    open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
-  );
-}
-
-function detectLineEnding(content) {
-  if (content.includes('\r\n')) return '\r\n';
-  if (content.includes('\r')) return '\r';
-  return '\n';
-}
-
-function normalizeLineEndings(content, lineEnding) {
-  return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
-}
-
-function readLineEndingAt(content, index) {
-  if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
-  if (content[index] === '\n') return '\n';
-  if (content[index] === '\r') return '\r';
-  return '';
-}
-
-function insertTag(content, config, port, filePath, token) {
-  const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
-  // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
-  // belong at the end, and the same literal can appear earlier in code blocks
-  // within rendered documentation pages.
-  if (config.insertBefore) {
-    const idx = content.lastIndexOf(config.insertBefore);
-    if (idx === -1) return content;
-    return content.slice(0, idx) + block + content.slice(idx);
-  }
-  // insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
-  // `<body>` open near the top of the document.
-  const idx = content.indexOf(config.insertAfter);
-  if (idx === -1) return content;
-  const after = idx + config.insertAfter.length;
-  // Preserve an existing trailing newline if the anchor already has one.
-  // Slice the remainder from the original anchor offset, not prefix.length:
-  // in the no-newline case prefix is one char longer than the anchor (the
-  // appended '\n'), so slicing by prefix.length would drop the first real
-  // character after the anchor (#227).
-  const existingNewline = readLineEndingAt(content, after);
-  const prefix = content.slice(0, after) + (existingNewline || lineEnding);
-  const rest = content.slice(after + existingNewline.length);
-  return prefix + block + rest;
-}
-
-/**
- * Remove the live script block. Matches either HTML or JSX comment markers
- * regardless of config (so stale tags from a wrong config can still be cleaned).
- *
- * Indent-preserving: captures any whitespace immediately preceding the opener
- * marker and re-emits it in place of the removed block. `insertTag` inserted
- * the block *after* the original line's indent and *before* the anchor (e.g.
- * `</body>`), which moved the indent onto the opener line and left the anchor
- * unindented. Replacing the whole block (plus its trailing newline) with just
- * the captured indent hands the indent back to the anchor that follows.
- */
-function removeTag(content, _syntax) {
-  const patterns = [
-    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
-    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
-  ];
-  for (const pat of patterns) {
-    let changed = false;
-    let next = content;
-    do {
-      content = next;
-      next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
-        if (/[\r\n]/.test(trailing)) return leadingIndent;
-        return leadingIndent || trailing || '';
-      });
-      if (next !== content) changed = true;
-    } while (next !== content);
-    if (changed) return next;
-  }
-  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
 // ---------------------------------------------------------------------------
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
+  enterLiveRoot();
   injectCli();
 }
 
-export { insertTag, removeTag, validateConfig, buildTagBlock };
-// patchCspMeta + revertCspMeta are exported above where they're defined.
+// Re-exported so long-standing importers (live.mjs, the adapter modules, the
+// test suites) keep their entry points while the implementations live in
+// live/frameworks/.
+export {
+  buildLiveScriptSrc,
+  buildTagBlock,
+  insertTag,
+  patchCspMeta,
+  removeTag,
+  revertCspMeta,
+  validateConfig,
+};
+export {
+  applyNuxtLiveAdapter,
+  buildNuxtPlugin,
+  detectNuxtProject,
+  removeNuxtLiveAdapter,
+} from './live/frameworks/nuxt.mjs';

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

@@ -26,6 +26,7 @@ import {
   scaffoldSvelteComponentInsertSession,
   shouldUseSvelteComponentInjection,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 const INSERT_POSITIONS = new Set(['before', 'after']);
 
@@ -286,5 +287,6 @@ Output (JSON):
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
+  enterLiveRoot();
   insertCli();
 }

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

@@ -14,6 +14,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
+import { instructionsForEvent } from './live/instructions.mjs';
 
 // Absolute path to a sibling script in this skill's scripts dir, so runtime
 // error hints print a directly-runnable command instead of a placeholder.
@@ -27,7 +29,7 @@ const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
 export const PER_REQUEST_TIMEOUT_MS = 270_000;
 export const DEFAULT_EVENT_LEASE_MS = 600_000;
 
-const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup']);
+const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'variant_mount_failed']);
 
 function readServerInfo() {
   const record = readLiveServerInfo(process.cwd());
@@ -117,8 +119,11 @@ export async function postReply(base, token, reply) {
   });
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
-    const parts = [body.error || res.statusText, body.reason, body.hint].filter(Boolean);
-    throw new Error(parts.join(': '));
+    const failureLines = Array.isArray(body.failures)
+      ? body.failures.map((f) => `  ${f.file}${f.line != null ? `:${f.line}` : ''} ${f.message}`).join('\n')
+      : null;
+    const parts = [body.error || res.statusText, body.reason, body.hint, failureLines, body._instructions].filter(Boolean);
+    throw new Error(parts.join('\n'));
   }
 }
 
@@ -261,6 +266,13 @@ export function writeCarbonizeBanner(event) {
 }
 
 export function printPollEvent(event) {
+  // Situational plumbing rides with the event itself: `_instructions` is the
+  // authoritative next step, with real ids and paths substituted, so the
+  // reference doc can stay lean and can never drift from script behavior.
+  if (event && typeof event === 'object' && !event._instructions) {
+    const instructions = instructionsForEvent(event, { scriptsPath: SELF_DIR });
+    if (instructions) event._instructions = instructions;
+  }
   console.log(JSON.stringify(event));
 }
 
@@ -412,5 +424,6 @@ export function normalizePollTypes(value) {
 // Auto-execute when run directly
 const _running = process.argv[1];
 if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
+  enterLiveRoot();
   pollCli();
 }

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

@@ -4,6 +4,7 @@
  */
 
 import { createLiveSessionStore } from './live/session-store.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
   const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
@@ -49,6 +50,28 @@ function collectManualApplyFiles(batch) {
   return [...new Set(files.filter((file) => typeof file === 'string' && file.length > 0))].sort();
 }
 
+/**
+ * The browser's render truth, folded into a small block the agent reads before
+ * it decides what to do. `arrivedVariants` only says the agent published;
+ * `renderState` says whether any of it reached a screen.
+ */
+export function renderSummary(snapshot = {}) {
+  return {
+    renderState: snapshot.renderState ?? null,
+    mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
+    mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
+  };
+}
+
+export function mountFailureAction(snapshot = {}) {
+  const failures = Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [];
+  const latest = failures[failures.length - 1];
+  if (!latest) return null;
+  const where = latest.url ? ` from ${latest.url}` : '';
+  const why = latest.error ? ` (${latest.error})` : '';
+  return `The browser failed to mount variant ${latest.variant}${where}${why}; nothing is on screen. Fix the variant files, then reply with live-poll.mjs --reply ${snapshot?.pendingEvent?.id || snapshot?.id || 'SESSION_ID'} done --file <manifest or source path> for the queued variant_mount_failed event (or republish) so the browser retries.`;
+}
+
 function parseArgs(argv) {
   const out = { id: null };
   for (let i = 0; i < argv.length; i++) {
@@ -75,20 +98,26 @@ export async function resumeCli() {
   }
 
   const pending = snapshot.pendingEvent || null;
-  const nextAction = pending
-    ? pending.type === 'manual_edit_apply'
-      ? manualApplyResumeHint(pending)
-      : `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
-    : snapshot.phase === 'carbonize_required'
-      ? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
-      : snapshot.phase === 'accept_requested'
-        ? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
-        : `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
+  const render = renderSummary(snapshot);
+  // A failed render outranks the generic pending-event hint: the agent needs to
+  // know the user is staring at an error card, not at variants. A leased manual
+  // Apply still outranks both, because abandoning that lease loses user edits.
+  const mountAction = render.renderState === 'failed' ? mountFailureAction(snapshot) : null;
+  const nextAction = pending?.type === 'manual_edit_apply'
+    ? manualApplyResumeHint(pending)
+    : mountAction || (pending
+      ? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
+      : snapshot.phase === 'carbonize_required'
+        ? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
+        : snapshot.phase === 'accept_requested'
+          ? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
+          : `Inspect ${snapshot.id}; no pending agent event is currently queued.`);
 
-  console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
+  console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, render, nextAction }, null, 2));
 }
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
+  enterLiveRoot();
   resumeCli();
 }

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

@@ -33,7 +33,10 @@ import { runGenerationPreflight } from './live/generation-preflight.mjs';
 import { validateEvent } from './live/event-validation.mjs';
 import { selectAvailablePendingEvent } from './live/poll-lanes.mjs';
 import { createManualEditRoutes } from './live/manual-edit-routes.mjs';
-import { LIVE_COMMANDS } from './live/vocabulary.mjs';
+import {
+  LIVE_COMMANDS,
+  VARIANT_PROGRESS_CHECKPOINT_REASONS as VARIANT_PROGRESS_CHECKPOINT_REASON_LIST,
+} from './live/vocabulary.mjs';
 import {
   getDesignSidecarPath,
   getLiveDir,
@@ -51,24 +54,53 @@ import {
 } from './live/manual-apply.mjs';
 import {
   applyDeferredSvelteComponentAccepts,
+  bumpSvelteComponentPreviewRevision,
+  compileCheckVariants,
   removeAllSvelteComponentSessions,
+  sweepInactiveSvelteComponentSessions,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
-// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
-// DESIGN.json fallback for existing projects.
-const PROJECT_CONTEXT = loadContext(process.cwd());
-const CONTEXT_DIR = PROJECT_CONTEXT.contextDir;
-const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
-  ? path.resolve(process.cwd(), PROJECT_CONTEXT.designPath)
-  : null;
+// Anchor the whole process on the live roots manifest before anything derives
+// a path from cwd. A server started from the wrong directory re-roots itself
+// onto the appRoot the boot decided on instead of minting a second project.
+const LIVE_ROOTS = enterLiveRoot(process.cwd());
+
+// PRODUCT.md / DESIGN.md context, resolved lazily and per request so a server
+// that outlives an `impeccable document` run (or a context file created after
+// boot) reports current truth instead of a boot-time snapshot. The roots
+// manifest wins when the ambient resolution misses (nested app inheriting
+// repo-level context files).
+function resolveProjectContext() {
+  const ctx = loadContext(process.cwd());
+  const designPath = ctx.designPath
+    ? path.resolve(process.cwd(), ctx.designPath)
+    : (LIVE_ROOTS?.designPath && fs.existsSync(LIVE_ROOTS.designPath) ? LIVE_ROOTS.designPath : null);
+  const hasProduct = ctx.hasProduct
+    || !!(LIVE_ROOTS?.productPath && fs.existsSync(LIVE_ROOTS.productPath));
+  return {
+    ...ctx,
+    hasProduct,
+    hasDesign: !!designPath,
+    resolvedDesignPath: designPath,
+    contextDir: ctx.contextDir || LIVE_ROOTS?.contextRoot || process.cwd(),
+    designContextDir: ctx.designContextDir
+      || (designPath ? path.dirname(designPath) : null),
+  };
+}
 const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
 const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
+
+// The browser events allowed to mint a NEW session journal. `generate` starts
+// a variant session at Go; `steer` mints its own request id. Every other
+// id-carrying event must land on an existing session (see the unknown_session
+// gate in the /events handler).
+const SESSION_CREATING_EVENT_TYPES = new Set(['generate', 'steer']);
 // The browser checkpoints for several unrelated reasons (see checkpointPayload
 // in live-browser.js). Only these two report that variant availability changed,
 // and only they may drive variant_progress / the *_reviewable phases.
-const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(['variants_progress', 'variants_ready']);
+const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(VARIANT_PROGRESS_CHECKPOINT_REASON_LIST);
 
 // ---------------------------------------------------------------------------
 // Port detection
@@ -150,7 +182,16 @@ function chatAgentLikelyActive() {
 const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
 
 function enqueueEvent(event) {
-  if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
+  if (!event) return;
+  // Dedupe by (session, type), except mount failures, which are per-variant:
+  // variant 2 failing must not be swallowed because variant 1's failure is
+  // still queued.
+  const duplicate = event.id && state.pendingEvents.some((entry) => (
+    entry.event?.id === event.id
+    && entry.event?.type === event.type
+    && (event.type !== 'variant_mount_failed' || entry.event?.variant === event.variant)
+  ));
+  if (duplicate) return;
   state.pendingEvents.push({ event, leaseUntil: 0, seq: state.nextEventSeq++ });
   flushPendingPolls();
 }
@@ -445,6 +486,11 @@ function summarizeActiveSessionForClient(snapshot = {}) {
     generationCompletedAt: snapshot.generationCompletedAt ?? null,
     generationCanceled: snapshot.generationCanceled === true,
     cancelReason: snapshot.cancelReason ?? null,
+    // Render truth, so a browser with no localStorage can rehydrate to the
+    // same comparison the server already knows about.
+    mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
+    mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
+    renderState: snapshot.renderState ?? null,
   };
 }
 
@@ -618,7 +664,7 @@ function hasProjectContext() {
   // PRODUCT.md carries brand voice / anti-references — that's what determines
   // whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
   // concern, surfaced by the design panel's own empty state.
-  return !!PROJECT_CONTEXT.hasProduct;
+  return !!resolveProjectContext().hasProduct;
 }
 
 function statOrNull(filePath) {
@@ -643,16 +689,24 @@ function isLoopbackOrigin(origin) {
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
-    // loopback origin, always paired with `Vary: Origin` so an intermediary
-    // cache never serves a response authorized for one origin to another. A
-    // remote page (e.g. https://evil.example probing the port from a tab open
-    // on the same machine) gets no Access-Control-Allow-Origin, so its
-    // JS-initiated fetch cannot read any response. Requests with no Origin
-    // header (script tags, curl, the agent's own fetches) are not subject to
-    // CORS and keep working; no ACAO header is needed for them.
+    // Token-or-loopback CORS. Reflect the caller's Origin when it is a
+    // loopback origin OR the request carries the valid session token, always
+    // paired with `Vary: Origin` so an intermediary cache never serves a
+    // response authorized for one origin to another. A remote page (e.g.
+    // https://evil.example probing the port from a tab open on the same
+    // machine) has no token and gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. The token branch exists for
+    // dev servers on non-localhost loopback aliases (ddev's *.ddev.site,
+    // Valet's *.test, hosts-file entries): the injected classic <script src>
+    // delivers the token to the page regardless of origin, every overlay
+    // request carries it in the query string (preflights included, since
+    // OPTIONS hits the same URL), and a token bearer is already fully
+    // authorized on every route — the token is the security boundary, not the
+    // origin. Requests with no Origin header (script tags, curl, the agent's
+    // own fetches) are not subject to CORS and keep working; no ACAO header
+    // is needed for them.
     const origin = req.headers.origin;
-    if (origin && isLoopbackOrigin(origin)) {
+    if (origin && (isLoopbackOrigin(origin) || url.searchParams.get('token') === state.token)) {
       res.setHeader('Access-Control-Allow-Origin', origin);
       res.setHeader('Vary', 'Origin');
     }
@@ -690,6 +744,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
         port: state.port,
         vocabulary: LIVE_COMMANDS,
         commandPrefix: IMPECCABLE_COMMAND_PREFIX,
+        appRoot: process.cwd(),
         parts,
       });
       res.writeHead(200, {
@@ -818,7 +873,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
     //                            { present, parsed, sidecar, hasMd, hasSidecar,
     //                              mdNewerThanJson, parseError?, sidecarError? }
     //                          - parsed: output of parseDesignMd (frontmatter
-    //                            + six canonical sections) when DESIGN.md exists.
+    //                            + the canonical sections) when DESIGN.md exists.
     //                          - sidecar: .impeccable/design.json contents when present.
     //                            Expected shape: schemaVersion 2, carrying
     //                            extensions + components + narrative.
@@ -827,8 +882,9 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const token = url.searchParams.get('token');
       if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
 
-      const mdPath = DESIGN_MD_PATH;
-      const jsonPath = resolveDesignSidecarPath(process.cwd(), PROJECT_CONTEXT.designContextDir || CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
+      const projectContext = resolveProjectContext();
+      const mdPath = projectContext.resolvedDesignPath;
+      const jsonPath = resolveDesignSidecarPath(process.cwd(), projectContext.designContextDir || projectContext.contextDir) || getDesignSidecarPath(process.cwd());
       const mdStat = statOrNull(mdPath);
       const jsonStat = statOrNull(jsonPath);
 
@@ -979,6 +1035,20 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
           res.end(JSON.stringify({ ok: true }));
           return;
         }
+        // Only the events that START a session may create its journal.
+        // Everything else (checkpoints, mount acks, accept/discard) must
+        // reference a session THIS store already knows: appendEvent creates a
+        // journal for any id it is handed, so without this gate a browser
+        // resuming another project's session from per-origin storage (two
+        // apps sharing a localhost port) materializes a ghost session here
+        // that keeps reattaching after every discard.
+        if (msg.id && state.sessionStore
+            && !SESSION_CREATING_EVENT_TYPES.has(msg.type)
+            && !state.sessionStore.has(msg.id)) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'unknown_session', id: msg.id }));
+          return;
+        }
         const missedCompletion = detectMissedGenerationCompletion(msg);
         if (state.sessionStore && msg.id) {
           try {
@@ -997,7 +1067,25 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
         if (msg.type === 'exit') {
           cleanupSvelteComponentSessionsBeforeExit();
         }
-        if (msg.type !== 'checkpoint') {
+        // An ORPHANED discard is the browser reporting that the session's
+        // wrapper no longer exists in source (edited or regenerated away).
+        // There is no cleanup for an agent to perform, and asking one to run
+        // the normal discard flow would just fail against the missing
+        // scaffolding, so the server terminalizes the session itself and the
+        // event stays out of the poll queue.
+        const orphanedDiscard = msg.type === 'discard' && msg.orphaned === true;
+        if (orphanedDiscard && state.sessionStore && msg.id) {
+          try {
+            state.sessionStore.appendEvent({ type: 'discarded', id: msg.id, orphaned: true });
+          } catch { /* the discard_requested phase already left the resumable set */ }
+        }
+        // `variant_mounted` is the happy path: it is journaled above so the
+        // snapshot carries render truth, but there is nothing for the agent to
+        // do about it, so it stays out of the poll queue and off the SSE bus.
+        // `variant_mount_failed` is the opposite: the agent published something
+        // the browser could not render, and only the agent can fix it, so it
+        // goes to the queue as a first-class event.
+        if (msg.type !== 'checkpoint' && msg.type !== 'variant_mounted' && !orphanedDiscard) {
           enqueueEvent(msg);
         }
         res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1099,7 +1187,8 @@ function sessionFileMetadataFromPollReply(file) {
   const base = { file: normalized };
   const metadataFile = normalized;
   if (!metadataFile.endsWith('/manifest.json') && metadataFile !== 'manifest.json') return base;
-  if (!metadataFile.includes('node_modules/.impeccable-live/')
+  if (!metadataFile.includes('.impeccable/live/previews/')
+      && !metadataFile.includes('node_modules/.impeccable-live/')
       && !metadataFile.includes('src/lib/impeccable/')
       && !metadataFile.includes('/.impeccable-live/')) return base;
 
@@ -1139,7 +1228,14 @@ function inferSourceEventType(msg = {}, pendingEvents = state.pendingEvents) {
   // `agent_done` can be the automatic acknowledgement for a carbonize Accept.
   // New pollers send sourceEventType explicitly; default to generate only for
   // older callers so a late worker cannot acknowledge a queued Accept.
-  if (msg.type === 'agent_done' || msg.type === 'done') return 'generate';
+  if (msg.type === 'agent_done' || msg.type === 'done') {
+    // A `done` reply to a mount failure is the republish that unblocks the
+    // browser. Without this the ack would look for a `generate` that was
+    // already retired, the mount-failure event would stay queued, and the next
+    // poll would hand the same failure back to the agent forever.
+    if (!pendingTypes.has('generate') && pendingTypes.has('variant_mount_failed')) return 'variant_mount_failed';
+    return 'generate';
+  }
   // `error` is reference/live.md's documented failure reply, and parseReplyArgs
   // never sets sourceEventType on it (the poller is a fresh process that cannot
   // know what it leased). Returning undefined here makes acknowledgePendingEvent
@@ -1264,6 +1360,30 @@ function handlePollPost(req, res) {
       return;
     }
     const replyFileMeta = sessionFileMetadataFromPollReply(msg.file);
+    // A publish (done reply carrying a component manifest) snapshots the
+    // variant files into a fresh revision dir before the browser is told:
+    // the import path changes every publish, so no transform cache can pin a
+    // stale compile of a republished module (node_modules is unwatched).
+    // Broken variants are bounced HERE, before the browser imports anything:
+    // a compile error that reaches the page is a red overlay in the user's
+    // face; bounced at publish it is a private fix with file and line.
+    if (replyFileMeta.previewMode === 'svelte-component'
+        && msg.id
+        && (msg.type === 'done' || !msg.type)) {
+      let compileCheck = { ok: true, failures: [] };
+      try { compileCheck = compileCheckVariants(msg.id, process.cwd()); } catch { /* best-effort */ }
+      if (!compileCheck.ok) {
+        res.writeHead(422, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          error: 'variant_compile_failed',
+          id: msg.id,
+          failures: compileCheck.failures,
+          _instructions: 'The publish was NOT delivered: the listed variant file(s) do not compile, so the browser never saw them. Fix each failure at the given file and line (the most common cause is a second top-level <style> element; Svelte allows exactly one, so merge all rules into the existing block), then send the same --reply done again.',
+        }));
+        return;
+      }
+      try { bumpSvelteComponentPreviewRevision(msg.id, process.cwd()); } catch { /* best-effort */ }
+    }
     if (state.sessionStore && msg.id && !skipJournalReply) {
       try {
         const eventType = msg.type === 'steer_done'
@@ -1335,6 +1455,51 @@ function cleanupSvelteComponentSessionsBeforeExit() {
   }
 }
 
+/**
+ * A previous run that died without its shutdown hook leaves preview component
+ * dirs behind. Drop the ones whose session the store no longer considers
+ * active; anything still active is mid-generation and must survive a restart.
+ */
+function sweepOrphanSvelteComponentSessionsOnStartup() {
+  try {
+    const activeIds = (state.sessionStore?.listActiveSessions() || [])
+      .map((snapshot) => snapshot?.id)
+      .filter(Boolean);
+    const result = sweepInactiveSvelteComponentSessions(activeIds, process.cwd());
+    if (result.removed.length > 0 || result.removedRoot) {
+      console.log('[impeccable] swept orphaned Svelte component sessions:', JSON.stringify(result));
+    }
+  } catch (err) {
+    console.warn('[impeccable] Svelte component session sweep failed:', err.message);
+  }
+}
+
+// Accept receipts are a short-lived idempotency record for a single accept.
+// Nothing reads one after the session that wrote it is gone, so they only need
+// to outlive a crash-and-retry window.
+const ACCEPT_RECEIPT_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+
+function sweepStaleAcceptReceiptsOnStartup() {
+  try {
+    const dir = path.join(getLiveDir(process.cwd()), 'accept-receipts');
+    if (!fs.existsSync(dir)) return;
+    const cutoff = Date.now() - ACCEPT_RECEIPT_MAX_AGE_MS;
+    let removed = 0;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
+      const file = path.join(dir, name);
+      try {
+        if (fs.statSync(file).mtimeMs >= cutoff) continue;
+        fs.rmSync(file, { force: true });
+        removed++;
+      } catch { /* non-fatal */ }
+    }
+    if (removed > 0) console.log(`[impeccable] removed ${removed} accept receipt(s) older than 14 days`);
+  } catch (err) {
+    console.warn('[impeccable] accept receipt retention sweep failed:', err.message);
+  }
+}
+
 function applyLegacyDeferredAcceptsOnStartup() {
   try {
     const result = applyDeferredSvelteComponentAccepts(process.cwd());
@@ -1474,6 +1639,8 @@ manualApply.rollbackTransaction({
   reason: 'manual_edit_server_start_recovered_abandoned_transaction',
 });
 applyLegacyDeferredAcceptsOnStartup();
+sweepOrphanSvelteComponentSessionsOnStartup();
+sweepStaleAcceptReceiptsOnStartup();
 restorePendingEventsFromStore();
 manualApply.pruneStaleEvidence();
 const portArg = args.find(a => a.startsWith('--port='));

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

@@ -5,7 +5,8 @@
 
 import { createLiveSessionStore } from './live/session-store.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
-import { manualApplyResumeHint } from './live-resume.mjs';
+import { manualApplyResumeHint, mountFailureAction, renderSummary } from './live-resume.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 function readServerInfo() {
   return readLiveServerInfo(process.cwd())?.info || null;
@@ -28,6 +29,8 @@ export async function statusCli() {
   const store = createLiveSessionStore({ cwd: process.cwd() });
   const activeSessions = store.listActiveSessions();
   const manualApply = findPendingManualApply(server, activeSessions);
+  const sessions = server?.activeSessions || activeSessions;
+  const renderFailure = sessions.find((session) => session?.renderState === 'failed') || null;
   const payload = {
     liveServer: server ? {
       status: server.status,
@@ -36,14 +39,16 @@ export async function statusCli() {
       agentPolling: server.agentPolling,
       pendingEvents: server.pendingEvents,
     } : null,
-    activeSessions: server?.activeSessions || activeSessions,
-    recoveryHint: recoveryHint({ server, manualApply }),
+    activeSessions: sessions,
+    render: sessions.map((session) => ({ id: session?.id ?? null, ...renderSummary(session) })),
+    recoveryHint: recoveryHint({ server, manualApply, renderFailure }),
   };
   console.log(JSON.stringify(payload, null, 2));
 }
 
-function recoveryHint({ server, manualApply }) {
+function recoveryHint({ server, manualApply, renderFailure }) {
   if (manualApply) return manualApplyResumeHint(manualApply);
+  if (renderFailure) return mountFailureAction(renderFailure);
   if (server) {
     return 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.';
   }
@@ -61,5 +66,6 @@ function findPendingManualApply(server, activeSessions) {
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-status.mjs') || _running?.endsWith('live-status.mjs/')) {
+  enterLiveRoot();
   statusCli();
 }

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

@@ -17,11 +17,13 @@ import { isGeneratedFile } from './lib/is-generated.mjs';
 import { resolveLiveTemplateExtensions } from './lib/template-extensions.mjs';
 import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
 import { findSourceFile } from './live/source-search.mjs';
+import { resolveSourceTraits } from './live/frameworks/index.mjs';
 import {
   buildSvelteComponentCssAuthoring,
   scaffoldSvelteComponentSession,
   shouldUseSvelteComponentInjection,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 export async function wrapCli() {
   const args = process.argv.slice(2);
@@ -293,8 +295,10 @@ The agent should insert variant HTML at insertLine.`);
     .join('\n');
   const originalIndented = reindentOriginal('    ');
   const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
-  const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
-  const useFrameworkComponent = useSvelteComponent;
+  // The registry says which files get component preview; the svelte-component
+  // module keeps the env escape hatch that turns it off.
+  const useSvelteComponent = resolveSourceTraits(targetFile).preview === 'component'
+    && shouldUseSvelteComponentInjection(targetFile);
 
   // Wrapper attributes differ by syntax. HTML allows plain string attrs;
   // JSX requires object-literal style and parses string attrs as HTML (which
@@ -343,12 +347,18 @@ The agent should insert variant HTML at insertLine.`);
   let svelteSession = null;
   let deferredWrapper = null;
 
+  let sveltePreviewFallback = null;
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
     // Keep generation source-neutral: agents write real variant components
     // under the generated componentDir, the browser mounts them into the live
     // DOM, and live-accept.mjs inlines the accepted variant back into the route.
-    svelteSession = scaffoldSvelteComponentSession({
+    //
+    // The scaffold is AST-based and refuses markup a detached preview cannot
+    // support (component tags, bind:/use:, await blocks, bound nested each).
+    // Refusal falls back to the plain source-preview wrapper below: an
+    // HMR-resetting but CORRECT preview beats a detached wrong one.
+    const scaffolded = scaffoldSvelteComponentSession({
       id,
       count,
       sourceFile: relTargetFile,
@@ -357,10 +367,18 @@ The agent should insert variant HTML at insertLine.`);
       originalLines,
       cwd: process.cwd(),
     });
-    outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
-    outputStartLine = 1;
-    outputEndLine = 1;
-    insertLine = 1;
+    if (scaffolded && scaffolded.fallback === 'source-preview') {
+      sveltePreviewFallback = scaffolded.reason || 'unsupported markup';
+    } else {
+      svelteSession = scaffolded;
+      outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
+      outputStartLine = 1;
+      outputEndLine = 1;
+      insertLine = 1;
+    }
+  }
+  if (svelteSession) {
+    // component preview: outputs already set above
   } else if (deferSourceWrite) {
     // Deferred source write: compute the scaffold text but leave source
     // untouched. The agent replaces the picked element's source range with
@@ -396,15 +414,19 @@ The agent should insert variant HTML at insertLine.`);
 
   const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
 
-  const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
+  const componentPreviewActive = !!svelteSession;
+  const svelteComponentAuthoring = componentPreviewActive ? buildSvelteComponentCssAuthoring(count) : null;
   const componentSession = svelteSession;
-  const componentPreviewMode = useSvelteComponent ? 'svelte-component' : undefined;
+  const componentPreviewMode = componentPreviewActive ? 'svelte-component' : undefined;
   const previewMode = componentPreviewMode;
 
   console.log(JSON.stringify({
     file: outputRelFile,
-    sourceFile: useFrameworkComponent ? relTargetFile : undefined,
+    sourceFile: componentPreviewActive ? relTargetFile : undefined,
     previewMode,
+    previewFallback: sveltePreviewFallback
+      ? { from: 'svelte-component', reason: sveltePreviewFallback }
+      : undefined,
     // Deferred source write: the wrapper is NOT yet in source. The agent
     // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
     // spliced at the "insert below this line" marker) in one atomic edit.
@@ -414,8 +436,9 @@ The agent should insert variant HTML at insertLine.`);
     replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
-    sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
-    sourceEndLine: useFrameworkComponent ? endLine + 1 : undefined,
+    componentStubMarkup: componentSession?.stubMarkup,
+    sourceStartLine: componentPreviewActive ? startLine + 1 : undefined,
+    sourceEndLine: componentPreviewActive ? endLine + 1 : undefined,
     startLine: outputStartLine,       // 1-indexed for the agent
     // 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
@@ -426,8 +449,8 @@ The agent should insert variant HTML at insertLine.`);
     insertLine,            // 1-indexed: where variants go
     commentSyntax: commentSyntax,
     styleMode: componentPreviewMode || styleMode.mode,
-    styleTag: useFrameworkComponent ? null : styleMode.styleTag,
-    cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
+    styleTag: componentPreviewActive ? null : styleMode.styleTag,
+    cssSelectorPrefixExamples: componentPreviewActive ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
     cssAuthoring: svelteComponentAuthoring || buildCssAuthoring(styleMode, count),
     originalLineCount: originalLines.length,
   }));
@@ -630,27 +653,22 @@ function attrEscapeDouble(str) {
     .replace(/>/g, '>');
 }
 
+/**
+ * Comment syntax, style mode, and preview strategy all come from the framework
+ * registry, keyed on the target file's extension: `.jsx`/`.tsx` author JSX
+ * comments, `.astro` needs global-prefixed preview CSS because Astro scopes
+ * component styles away from the generated wrappers, `.svelte` gets component
+ * preview. See live/frameworks/index.mjs for why extension and not project.
+ */
 function detectCommentSyntax(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.jsx' || ext === '.tsx') {
-    return { open: '{/*', close: '*/}' };
-  }
-  // HTML, Vue, Svelte, Astro all use HTML comments
-  return { open: '<!--', close: '-->' };
+  return resolveSourceTraits(filePath).commentSyntax === 'jsx'
+    ? { open: '{/*', close: '*/}' }
+    : { open: '<!--', close: '-->' };
 }
 
 function detectStyleMode(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.astro') {
-    return {
-      mode: 'astro-global-prefixed',
-      styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
-    };
-  }
-  return {
-    mode: 'scoped',
-    styleTag: '<style data-impeccable-css="SESSION_ID">',
-  };
+  const traits = resolveSourceTraits(filePath);
+  return { mode: traits.styleMode, styleTag: traits.styleTag };
 }
 
 function buildCssSelectorPrefixExamples(styleMode, count) {
@@ -890,6 +908,7 @@ function findClosingLine(lines, start) {
 // Auto-execute when run directly (node live-wrap.mjs ...)
 const _running = process.argv[1];
 if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
+  enterLiveRoot();
   wrapCli();
 }
 

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

@@ -21,10 +21,13 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadContext, resolveTargetSelection } from './context.mjs';
+import { resolveTargetSelection } from './context.mjs';
 import { resolveFiles } from './live-inject.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
 import { resolveLiveTarget } from './live-target.mjs';
+import { bootInstructions } from './live/instructions.mjs';
+import { resolveRoots, writeRootsManifest } from './live/roots.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -60,6 +63,8 @@ The agent should then:
     process.exit(0);
   }
 
+  // Legacy workspace-monorepo selection first: it carries richer candidate
+  // metadata (context inheritance status) than the roots scan.
   const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
   if (targetSelection) {
     console.log(JSON.stringify({
@@ -71,11 +76,31 @@ The agent should then:
     process.exit(0);
   }
 
-  const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
-  const activeCwd = ctx.projectRoot;
+  const rootsResult = resolveRoots({
+    cwd: liveTarget.originalCwd,
+    targetPath: liveTarget.absoluteTargetPath,
+  });
+  if (rootsResult.selection) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'target_selection_required',
+      targetCandidates: rootsResult.selection.candidates,
+      hint: 'Several apps with a dev-server config exist. Ask the user which one to use, then rerun with --target <path into that app>.',
+    }, null, 2));
+    process.exit(0);
+  }
+  const roots = rootsResult.manifest;
+  const activeCwd = roots.appRoot;
   const outputTargetPath = liveTarget.targetPath || null;
 
-  const missingContext = missingLiveContext(ctx);
+  // Gate on readable CONTENT, not path existence, so an empty or unreadable
+  // PRODUCT.md routes to init instead of passing the gate and then reporting
+  // hasProduct: false in the same payload.
+  const product = safeRead(roots.productPath);
+  const design = safeRead(roots.designPath);
+  const missingContext = [];
+  if (!product) missingContext.push('PRODUCT.md');
+  if (!design) missingContext.push('DESIGN.md');
   if (missingContext.length > 0) {
     console.log(JSON.stringify({
       ok: false,
@@ -83,14 +108,18 @@ The agent should then:
       missing: missingContext,
       nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
       targetPath: outputTargetPath,
-      projectRoot: ctx.projectRoot,
-      repoRoot: ctx.repoRoot,
-      productPath: ctx.productPath,
-      designPath: ctx.designPath,
+      projectRoot: roots.appRoot,
+      repoRoot: roots.repoRoot,
+      productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
+      designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
     }, null, 2));
     process.exit(0);
   }
 
+  // Persist the decision before anything else spawns, so every helper the
+  // agent runs later (from any cwd inside the repo) lands on the same roots.
+  writeRootsManifest(roots);
+
   // 1. Check config (fail fast if missing — no point starting anything else)
   const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
   const checkResult = safeParse(checkOut);
@@ -98,8 +127,8 @@ The agent should then:
     console.log(JSON.stringify({
       ...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
       targetPath: outputTargetPath,
-      projectRoot: ctx.projectRoot,
-      repoRoot: ctx.repoRoot,
+      projectRoot: roots.appRoot,
+      repoRoot: roots.repoRoot,
     }));
     process.exit(0);
   }
@@ -134,7 +163,28 @@ The agent should then:
   const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
   const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
 
-  // 5. Emit everything the agent needs
+  // 5. Emit everything the agent needs. The surface brief rides along so the
+  //    agent does not spend three more tool calls (and a --help miss) on
+  //    surface-brief.mjs before the first poll.
+  let surfaceBrief = null;
+  let surfaceBriefPath = null;
+  try {
+    // Briefs live under .impeccable/surfaces, which in a nested-app repo sits
+    // at the CONTEXT or repo root, not the app root; context.mjs already finds
+    // them there, and live must not report "no brief" for the same project.
+    const briefRoots = [roots.appRoot, roots.contextRoot, roots.repoRoot]
+      .filter(Boolean)
+      .filter((dir, i, arr) => arr.findIndex((other) => path.resolve(other) === path.resolve(dir)) === i);
+    for (const briefRoot of briefRoots) {
+      const resolvedBrief = resolveSurfaceBrief(briefRoot, liveTarget.absoluteTargetPath || null);
+      if (!resolvedBrief?.brief) continue;
+      surfaceBrief = resolvedBrief.brief.text ?? safeRead(resolvedBrief.brief.path);
+      surfaceBriefPath = resolvedBrief.brief.path
+        ? path.relative(liveTarget.originalCwd, resolvedBrief.brief.path)
+        : null;
+      break;
+    }
+  } catch { /* briefs are optional context */ }
   console.log(JSON.stringify({
     ok: true,
     serverPort: serverInfo.port,
@@ -143,22 +193,29 @@ The agent should then:
     liveConfigPath: checkResult.path,
     configDrift: drift,
     targetPath: outputTargetPath,
-    projectRoot: ctx.projectRoot,
-    repoRoot: ctx.repoRoot,
-    hasProduct: ctx.hasProduct,
-    product: ctx.product,
-    productPath: ctx.productPath,
-    hasDesign: ctx.hasDesign,
-    design: ctx.design,
-    designPath: ctx.designPath,
+    projectRoot: roots.appRoot,
+    repoRoot: roots.repoRoot,
+    roots,
+    hasProduct: !!product,
+    product,
+    productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
+    hasDesign: !!design,
+    design,
+    designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
+    hasSurfaceBrief: !!surfaceBrief,
+    surfaceBrief,
+    surfaceBriefPath,
+    _instructions: bootInstructions({ scriptsPath: __dirname }),
   }, null, 2));
 }
 
-function missingLiveContext(ctx) {
-  const missing = [];
-  if (!ctx.hasProduct) missing.push('PRODUCT.md');
-  if (!ctx.hasDesign) missing.push('DESIGN.md');
-  return missing;
+function safeRead(p) {
+  if (!p) return null;
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+function relOrNull(base, p) {
+  return p ? path.relative(base, p) : null;
 }
 
 /**

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

@@ -0,0 +1,617 @@
+/**
+ * Accept-time CSS reconciliation for live mode.
+ *
+ * The old accept path appended the chosen variant's whole <style> body in
+ * front of the component's existing rules, which preserved every superseded
+ * declaration (the "old divider borders survive the accept" bug) and left
+ * dead parameter branches in source. This module makes acceptance a merge:
+ *
+ *   reconcileCss      replace rules whose selectors match, append new ones
+ *   bakeParamValues   collapse --p-* vars and [data-p-*] branches to the
+ *                     user's chosen values, driven by the declared param
+ *                     kinds from params.json (not regex sniffing)
+ *   pruneUnusedSelectors  use the framework compiler's own unused-selector
+ *                     warnings to delete rules the accepted markup no longer
+ *                     references
+ *
+ * The parser is hand-rolled on purpose: skill scripts run standalone inside
+ * user projects and cannot rely on this repo's node_modules. It is a small
+ * recursive block parser (comment- and string-aware), not a spec-complete
+ * CSS parser; everything it emits round-trips byte-for-byte through raw
+ * slices except the rules deliberately changed.
+ */
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a stylesheet into a flat tree.
+ * Node shapes:
+ *   { type: 'rule', prelude, body, start, end, preludeStart }
+ *   { type: 'at', name, prelude, children|body, start, end }  (children when
+ *     the block contains rules: media/supports/layer/container/scope)
+ *   { type: 'comment', text, start, end }
+ */
+export function parseStylesheet(css, offset = 0) {
+  const text = String(css || '');
+  const nodes = [];
+  let i = 0;
+
+  const skipWs = () => { while (i < text.length && /\s/.test(text[i])) i++; };
+
+  while (i < text.length) {
+    skipWs();
+    if (i >= text.length) break;
+
+    if (text[i] === '/' && text[i + 1] === '*') {
+      const start = i;
+      const close = text.indexOf('*/', i + 2);
+      i = close === -1 ? text.length : close + 2;
+      nodes.push({ type: 'comment', text: text.slice(start, i), start: offset + start, end: offset + i });
+      continue;
+    }
+
+    const preludeStart = i;
+    const boundary = scanToBlockOrStatementEnd(text, i);
+    if (boundary.kind === 'none') break; // trailing garbage / declarations at top level
+    if (boundary.kind === 'statement') {
+      // Block-less at-statement (@import, @charset, @layer names;). Emitted
+      // as its own node so the FOLLOWING rule still indexes for
+      // reconciliation instead of being folded into this prelude.
+      const raw = text.slice(preludeStart, boundary.index + 1).trim();
+      if (raw) {
+        nodes.push({
+          type: 'at',
+          name: (raw.match(/^@([A-Za-z-]+)/) || [])[1] || '',
+          prelude: raw.replace(/;$/, ''),
+          statement: true,
+          start: offset + preludeStart,
+          end: offset + boundary.index + 1,
+        });
+      }
+      i = boundary.index + 1;
+      continue;
+    }
+    const braceIdx = boundary.index;
+    const prelude = text.slice(preludeStart, braceIdx).trim();
+    const bodyStart = braceIdx + 1;
+    const bodyEnd = scanBlockEnd(text, bodyStart);
+    const body = text.slice(bodyStart, bodyEnd);
+    const nodeEnd = Math.min(text.length, bodyEnd + 1);
+
+    if (prelude.startsWith('@')) {
+      const name = (prelude.match(/^@([A-Za-z-]+)/) || [])[1] || '';
+      if (['media', 'supports', 'layer', 'container', 'scope'].includes(name)) {
+        nodes.push({
+          type: 'at',
+          name,
+          prelude,
+          children: parseStylesheet(body, offset + bodyStart),
+          start: offset + preludeStart,
+          end: offset + nodeEnd,
+        });
+      } else {
+        nodes.push({
+          type: 'at',
+          name,
+          prelude,
+          body,
+          start: offset + preludeStart,
+          end: offset + nodeEnd,
+        });
+      }
+    } else if (prelude) {
+      nodes.push({
+        type: 'rule',
+        prelude,
+        body,
+        start: offset + preludeStart,
+        end: offset + nodeEnd,
+        preludeStart: offset + preludeStart,
+      });
+    }
+    i = nodeEnd;
+  }
+  return nodes;
+}
+
+/**
+ * Scan for the next structural boundary: the `{` opening a block, or the `;`
+ * ending a block-less at-statement, whichever comes first (string- and
+ * comment-aware). Returns { kind: 'block' | 'statement' | 'none', index }.
+ */
+function scanToBlockOrStatementEnd(text, from) {
+  let i = from;
+  let quote = null;
+  while (i < text.length) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      i = close === -1 ? text.length : close + 1;
+    } else if (ch === '{') {
+      return { kind: 'block', index: i };
+    } else if (ch === ';') {
+      return { kind: 'statement', index: i };
+    }
+    i++;
+  }
+  return { kind: 'none', index: -1 };
+}
+
+function scanBlockEnd(text, from) {
+  let i = from;
+  let depth = 1;
+  let quote = null;
+  while (i < text.length) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      i = close === -1 ? text.length : close + 1;
+    } else if (ch === '{') {
+      depth++;
+    } else if (ch === '}') {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return text.length;
+}
+
+export function serializeNodes(nodes, indent = '') {
+  const out = [];
+  for (const node of nodes) {
+    if (node.type === 'comment') {
+      out.push(indent + node.text);
+    } else if (node.type === 'rule') {
+      out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
+    } else if (node.type === 'at' && node.children) {
+      out.push(`${indent}${node.prelude} {`);
+      out.push(serializeNodes(node.children, indent + '  '));
+      out.push(`${indent}}`);
+    } else if (node.type === 'at' && node.statement) {
+      out.push(`${indent}${node.prelude};`);
+    } else if (node.type === 'at') {
+      out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
+    }
+  }
+  return out.join('\n');
+}
+
+function formatBody(body, indent) {
+  const trimmed = String(body || '').trim();
+  if (!trimmed) return ' ';
+  const lines = trimmed.split('\n').map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 1 && lines[0].length < 60) return ` ${lines[0]} `;
+  return '\n' + lines.map((l) => `${indent}  ${l}`).join('\n') + `\n${indent}`;
+}
+
+export function normalizeSelector(prelude) {
+  return String(prelude || '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([>+~,])\s*/g, '$1')
+    .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Reconciliation
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge variant CSS into existing CSS. Rules whose (at-context, normalized
+ * selector) match an existing rule REPLACE that rule's body in place; new
+ * rules append at the end under their at-context. Returns { css, replaced,
+ * appended }.
+ */
+export function reconcileCss(existingCss, variantCss) {
+  const existing = parseStylesheet(existingCss);
+  const incoming = parseStylesheet(variantCss);
+  let replaced = 0;
+  let appended = 0;
+
+  const mergeLevel = (existingNodes, incomingNodes) => {
+    const index = new Map();
+    for (const node of existingNodes) {
+      if (node.type === 'rule') index.set(normalizeSelector(node.prelude), node);
+    }
+    const atIndex = new Map();
+    for (const node of existingNodes) {
+      if (node.type === 'at' && node.children) atIndex.set(normalizeSelector(node.prelude), node);
+    }
+    // Baking can leave several incoming rules with the same selector (e.g. a
+    // base rule plus a stripped param branch). The first one REPLACES the
+    // existing body; later same-selector rules extend it, never clobber it.
+    const touched = new Set();
+    for (const node of incomingNodes) {
+      if (node.type === 'comment') continue;
+      if (node.type === 'rule') {
+        const key = normalizeSelector(node.prelude);
+        const match = index.get(key);
+        if (match) {
+          if (touched.has(key)) {
+            match.body = `${match.body.trim()}\n${node.body.trim()}`;
+          } else if (match.body.trim() !== node.body.trim()) {
+            match.body = node.body;
+            replaced++;
+          }
+          touched.add(key);
+        } else {
+          // New base rules go BEFORE the existing top-level media blocks:
+          // appended after them, an equal-specificity base rule wins the
+          // cascade over the stylesheet's earlier responsive overrides and
+          // silently weakens the mobile styles for any still-shared class.
+          const appendedNode = { ...node };
+          const firstAt = existingNodes.findIndex((n) => n.type === 'at' && n.children);
+          if (firstAt === -1) existingNodes.push(appendedNode);
+          else existingNodes.splice(firstAt, 0, appendedNode);
+          index.set(key, appendedNode);
+          touched.add(key);
+          appended++;
+        }
+      } else if (node.type === 'at' && node.children) {
+        const key = normalizeSelector(node.prelude);
+        const match = atIndex.get(key);
+        if (match) {
+          mergeLevel(match.children, node.children);
+        } else {
+          existingNodes.push({ ...node });
+          atIndex.set(key, existingNodes[existingNodes.length - 1]);
+          appended++;
+        }
+      } else {
+        existingNodes.push({ ...node });
+        appended++;
+      }
+    }
+  };
+
+  mergeLevel(existing, incoming);
+  return { css: serializeNodes(existing), replaced, appended };
+}
+
+// ---------------------------------------------------------------------------
+// Parameter baking
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace every `var(--p-<id>, fallback)` / `var(--p-<id>)` occurrence with a
+ * literal value. Paren-aware: fallbacks containing calc()/nested vars are
+ * handled, unlike the old `[^)]+` regex.
+ */
+export function substituteParamVar(css, id, value) {
+  const text = String(css || '');
+  const needle = `var(--p-${id}`;
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const idx = text.indexOf(needle, i);
+    if (idx === -1) { out += text.slice(i); break; }
+    const after = idx + needle.length;
+    // Must be end of the var name: `)` or `,`.
+    if (after < text.length && text[after] !== ')' && text[after] !== ',') {
+      out += text.slice(i, after);
+      i = after;
+      continue;
+    }
+    let j = after;
+    let depth = 1; // we are inside var(
+    while (j < text.length && depth > 0) {
+      if (text[j] === '(') depth++;
+      else if (text[j] === ')') depth--;
+      j++;
+    }
+    out += text.slice(i, idx) + String(value);
+    i = j;
+  }
+  return out;
+}
+
+function normalizeToggleForVar(value) {
+  return value === true || value === 'true' || value === 1 || value === '1' || value === 'on' ? '1' : '0';
+}
+
+function isToggleOn(value) {
+  return normalizeToggleForVar(value) === '1';
+}
+
+/**
+ * Strip `[data-p-<id>="value"]` / `[data-p-<id>]` attribute selectors from a
+ * selector, deciding survival by the chosen value:
+ *   returns null when the selector targets a non-chosen branch (drop it),
+ *   otherwise the selector with the attribute test removed and any emptied
+ *   :global() wrappers cleaned up.
+ */
+export function stripParamSelector(selector, id, kind, chosenValue) {
+  const attrRe = new RegExp(`\\[data-p-${escapeRegExp(id)}(?:=(["'])(.*?)\\1)?\\]`, 'g');
+  let drop = false;
+  let out = String(selector).replace(attrRe, (_m, _q, expected) => {
+    if (kind === 'steps') {
+      if (expected == null || String(expected) === String(chosenValue)) return '';
+      drop = true;
+      return '';
+    }
+    // toggle: the runtime sets data-p-<id>="on" when on and removes the
+    // attribute when off. A branch survives baking only if it actually
+    // matched at preview time with the chosen state: the presence form and
+    // the literal "on" form match while on; every other valued form
+    // (["false"], ["0"], ...) never matched and is dead regardless of state.
+    if (expected != null && expected !== 'on') {
+      drop = true;
+      return '';
+    }
+    if (!isToggleOn(chosenValue)) {
+      drop = true;
+      return '';
+    }
+    return '';
+  });
+  if (drop) return null;
+  out = out
+    .replace(/:global\(\s*\)/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/^\s*[>+~]\s*/, '')
+    .trim();
+  return out || null;
+}
+
+/**
+ * Bake chosen parameter values into CSS. `params` is the declared parameter
+ * list for the accepted variant (from params.json); `values` maps id ->
+ * chosen value (falling back to each param's declared default).
+ */
+export function bakeParamValues(css, params = [], values = {}) {
+  let nodes = parseStylesheet(css);
+
+  const chosen = new Map();
+  for (const param of params || []) {
+    if (!param || !param.id) continue;
+    const has = values && Object.prototype.hasOwnProperty.call(values, param.id);
+    chosen.set(param.id, { kind: param.kind, value: has ? values[param.id] : param.default });
+  }
+  // Values sent for params that were never declared still bake as ranges,
+  // so an out-of-sync manifest degrades to the old behavior, not to silence.
+  for (const [id, value] of Object.entries(values || {})) {
+    if (!chosen.has(id)) chosen.set(id, { kind: 'range', value });
+  }
+
+  const bakeBody = (body) => {
+    let out = String(body || '');
+    for (const [id, { kind, value }] of chosen) {
+      const literal = kind === 'toggle' ? normalizeToggleForVar(value) : String(value);
+      out = substituteParamVar(out, id, literal);
+    }
+    // Strip the readiness sentinel as a DECLARATION, not a line: a one-line
+    // rule carrying the sentinel plus real declarations must keep the rest.
+    return out
+      .replace(/(^|;)\s*--impeccable-variant-ready\s*:[^;{}]*/g, '$1')
+      .replace(/;\s*;/g, ';')
+      .replace(/^\s*;\s*/, '');
+  };
+
+  const transform = (list) => {
+    const result = [];
+    for (const node of list) {
+      if (node.type === 'at' && node.children) {
+        const children = transform(node.children);
+        if (children.length > 0) result.push({ ...node, children });
+        continue;
+      }
+      if (node.type !== 'rule') {
+        if (node.type === 'at') result.push({ ...node, body: bakeBody(node.body) });
+        else result.push(node);
+        continue;
+      }
+      const selectors = splitSelectorList(node.prelude);
+      const kept = [];
+      for (let selector of selectors) {
+        let alive = true;
+        for (const [id, { kind, value }] of chosen) {
+          if (kind !== 'steps' && kind !== 'toggle') continue;
+          if (!selector.includes(`data-p-${id}`)) continue;
+          const next = stripParamSelector(selector, id, kind, value);
+          if (next == null) { alive = false; break; }
+          selector = next;
+        }
+        if (alive && selector.trim()) kept.push(selector.trim());
+      }
+      if (kept.length === 0) continue;
+      const body = bakeBody(node.body);
+      if (!body.trim()) continue;
+      result.push({ ...node, prelude: kept.join(', '), body });
+    }
+    return result;
+  };
+
+  nodes = transform(nodes);
+  return serializeNodes(nodes);
+}
+
+export function splitSelectorList(prelude) {
+  const selectors = [];
+  let start = 0;
+  let bracket = 0;
+  let paren = 0;
+  let quote = null;
+  const text = String(prelude || '');
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if (ch === '[') bracket++;
+    else if (ch === ']') bracket = Math.max(0, bracket - 1);
+    else if (ch === '(') paren++;
+    else if (ch === ')') paren = Math.max(0, paren - 1);
+    else if (ch === ',' && bracket === 0 && paren === 0) {
+      selectors.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  selectors.push(text.slice(start));
+  return selectors.map((s) => s.trim()).filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Compiler-driven pruning
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove selectors the framework compiler reports as unused from a full
+ * component source. `compileFn` is the app's svelte compile; warnings with
+ * code `css_unused_selector` carry character offsets into the source.
+ * `skipSelectors` protects selectors that were already unused before the
+ * accept: pre-existing dead rules are the user's code, not live-mode debris.
+ * Returns { source, removed } where removed lists the pruned selector texts.
+ */
+export function collectUnusedSelectors(componentSource, compileFn) {
+  try {
+    const { warnings } = compileFn(String(componentSource || ''), { generate: false });
+    return new Set((warnings || [])
+      .filter((w) => w.code === 'css_unused_selector'
+        && Number.isInteger(w.start?.character)
+        && Number.isInteger(w.end?.character))
+      .map((w) => String(componentSource).slice(w.start.character, w.end.character).trim()));
+  } catch {
+    return new Set();
+  }
+}
+
+export function pruneUnusedSelectors(componentSource, compileFn, { skipSelectors } = {}) {
+  let source = String(componentSource || '');
+  const removed = [];
+  const skip = skipSelectors instanceof Set ? skipSelectors : new Set(skipSelectors || []);
+  for (let pass = 0; pass < 3; pass++) {
+    let warnings;
+    try {
+      ({ warnings } = compileFn(source, { generate: false }));
+    } catch {
+      return { source, removed }; // never let pruning break an accept
+    }
+    const unused = (warnings || [])
+      .filter((w) => w.code === 'css_unused_selector'
+        && Number.isInteger(w.start?.character)
+        && Number.isInteger(w.end?.character))
+      .filter((w) => !skip.has(source.slice(w.start.character, w.end.character).trim()))
+      .sort((a, b) => b.start.character - a.start.character);
+    if (unused.length === 0) break;
+
+    let next = source;
+    for (const warning of unused) {
+      const result = removeSelectorAt(next, warning.start.character, warning.end.character);
+      if (result.changed) {
+        removed.push(result.selector);
+        next = result.source;
+      }
+    }
+    if (next === source) break;
+    source = next;
+  }
+  return { source, removed };
+}
+
+/**
+ * Remove the selector at [start, end) from its rule. When it is the rule's
+ * only selector, remove the whole rule (prelude through closing brace).
+ */
+function removeSelectorAt(source, start, end) {
+  const selector = source.slice(start, end);
+
+  // Find the rule boundaries around the selector.
+  const braceIdx = source.indexOf('{', end);
+  if (braceIdx === -1) return { changed: false, selector, source };
+  const bodyEnd = scanBlockEnd(source, braceIdx + 1);
+
+  // Prelude spans backward from the brace to the previous } ; { or the end
+  // of the <style> open tag. A bare `>` is NOT a boundary: it is the child
+  // combinator, and cutting there truncates a selector list like
+  // `.a > .b, .c` mid-prelude. Only a `>` that closes a `<style ...>` tag
+  // bounds the walk.
+  let preludeStart = start;
+  for (let i = start - 1; i >= 0; i--) {
+    const ch = source[i];
+    if (ch === '}' || ch === '{' || ch === ';') { preludeStart = i + 1; break; }
+    if (ch === '>') {
+      const styleOpen = source.lastIndexOf('<style', i);
+      if (styleOpen !== -1 && source.indexOf('>', styleOpen) === i) { preludeStart = i + 1; break; }
+      continue; // child combinator inside the prelude
+    }
+    if (i === 0) preludeStart = 0;
+  }
+  const prelude = source.slice(preludeStart, braceIdx);
+  const selectors = splitSelectorList(prelude);
+  const target = selector.trim();
+  const kept = selectors.filter((s) => s !== target);
+
+  if (kept.length === selectors.length) {
+    // Offsets did not line up with a full selector in the list; be safe.
+    return { changed: false, selector, source };
+  }
+
+  if (kept.length === 0) {
+    // Remove the entire rule including trailing newline.
+    let ruleEnd = Math.min(source.length, bodyEnd + 1);
+    while (ruleEnd < source.length && source[ruleEnd] === '\n') ruleEnd++;
+    let ruleStart = preludeStart;
+    while (ruleStart > 0 && (source[ruleStart - 1] === ' ' || source[ruleStart - 1] === '\t')) ruleStart--;
+    return { changed: true, selector: target, source: source.slice(0, ruleStart) + source.slice(ruleEnd) };
+  }
+
+  const indent = (prelude.match(/^\s*/) || [''])[0];
+  return {
+    changed: true,
+    selector: target,
+    source: source.slice(0, preludeStart) + indent + kept.join(', ') + ' ' + source.slice(braceIdx, source.length),
+  };
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Collect every normalized selector in a CSS text, including inside nested
+ * at-blocks. Used by the accept postcondition: a selector present before the
+ * accept may only disappear if the compiler reported it unused; anything
+ * else means the parser or reconciler damaged the user's file, and the write
+ * must be refused rather than silently committed.
+ */
+export function collectAllSelectors(css, out = new Set()) {
+  for (const node of parseStylesheet(css)) {
+    if (node.type === 'rule') {
+      for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
+    } else if (node.type === 'at' && node.children) {
+      for (const child of node.children) {
+        if (child.type === 'rule') {
+          for (const selector of splitSelectorList(child.prelude)) out.add(normalizeSelector(selector));
+        } else if (child.type === 'at' && child.children) {
+          collectSelectorsFromNodes(child.children, out);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function collectSelectorsFromNodes(nodes, out) {
+  for (const node of nodes) {
+    if (node.type === 'rule') {
+      for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
+    } else if (node.type === 'at' && node.children) {
+      collectSelectorsFromNodes(node.children, out);
+    }
+  }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Postcondition scanner for accepted/carbonized source. The carbonize
+ * contract used to exist only as prose in reference/live.md; nothing checked
+ * that an accept actually left the file clean, so dead param branches,
+ * preview attributes, and marker comments accumulated across sessions. This
+ * scanner is the mechanical form of that contract. live-complete refuses to
+ * mark a carbonize session complete while the file is dirty, and the
+ * mechanical Svelte accept runs it on its own output as a self-check.
+ */
+
+// Param patterns are anchored to the exact shapes live mode writes
+// (attribute-with-value / selector forms, var() references), not bare
+// substrings, so user tokens that merely share the prefix cannot trip the
+// completion gate.
+const FORBIDDEN = [
+  { marker: 'impeccable-variants-start', why: 'variant wrapper comment left in source' },
+  { marker: 'impeccable-variants-end', why: 'variant wrapper comment left in source' },
+  { marker: 'impeccable-carbonize-start', why: 'carbonize block not rewritten into permanent form' },
+  { marker: 'impeccable-carbonize-end', why: 'carbonize block not rewritten into permanent form' },
+  { marker: 'impeccable-param-values', why: 'param-values comment not baked and removed' },
+  { marker: 'data-impeccable-', why: 'live-mode plumbing attribute left on markup' },
+  { marker: /\bdata-p-[A-Za-z0-9_-]+\s*(?:=|\])/, label: 'data-p-*', why: 'preview parameter attribute left on markup' },
+  { marker: /var\(\s*--p-[A-Za-z0-9_-]+\s*[,)]/, label: 'var(--p-*)', why: 'preview parameter variable not baked to a literal' },
+  { marker: '--impeccable-variant-ready', why: 'preview readiness sentinel left in CSS' },
+];
+
+/**
+ * Scan file text for live-mode leftovers. Returns { clean, findings } where
+ * each finding is { marker, line, excerpt, why }.
+ */
+export function verifyAcceptedSource(text) {
+  const findings = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { marker, label, why } of FORBIDDEN) {
+      const hit = marker instanceof RegExp ? marker.test(line) : line.includes(marker);
+      if (hit) {
+        findings.push({
+          marker: label || String(marker),
+          line: i + 1,
+          excerpt: line.trim().slice(0, 120),
+          why,
+        });
+      }
+    }
+  }
+  return { clean: findings.length === 0, findings };
+}
+
+/** Convenience wrapper for CLI callers: read + scan, tolerating a missing file. */
+export function verifyAcceptedFile(fs, filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return { clean: true, findings: [], missing: true };
+  }
+  return { ...verifyAcceptedSource(text), missing: false };
+}

.agents/skills/impeccable/scripts/live/browser-script-parts.mjs

@@ -32,10 +32,15 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
   }));
 }
 
-export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
+export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', appRoot = null, parts }) {
   const prelude =
     `window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
     `window.__IMPECCABLE_PORT__ = ${port};\n` +
+    // Project identity for browser-side session storage. localStorage is
+    // keyed by ORIGIN, and two projects routinely share a localhost port
+    // across time; saved sessions carry this value so a resume can tell a
+    // foreign project's leftovers from its own.
+    `window.__IMPECCABLE_APP_ROOT__ = ${JSON.stringify(appRoot)};\n` +
     `window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
     // Canonical command vocabulary (values + labels + icons). live-browser.js
     // builds its action picker from this instead of an inline copy.

.agents/skills/impeccable/scripts/live/event-validation.mjs

@@ -5,17 +5,26 @@
 
 import { canCreateInsert } from './insert-ui.mjs';
 
-// The accepted visual action values come from the canonical vocabulary so the
-// validator, the picker UI, and the marketing demo never drift. Imported (not
-// just re-exported) so it is also in scope for the validators below.
-import { VISUAL_ACTIONS } from './vocabulary.mjs';
-export { VISUAL_ACTIONS };
+// The accepted protocol values come from the canonical vocabulary so the
+// validator, the store, the server, and the picker UI never drift. Imported
+// (not just re-exported) so they are also in scope for the validators below.
+import { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS } from './vocabulary.mjs';
+export { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS };
+
+const AGENT_PHASE_SET = new Set(AGENT_PHASES);
 
 const ID_PATTERN = /^[0-9a-f]{8}$/;
 const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
 const INSERT_POSITIONS = new Set(['before', 'after']);
 const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
 
+// Mount acknowledgements carry a module URL and a raw exception message from
+// the page. Both are attacker-adjacent (any script on the page can POST them
+// with the token it can already read), so they are length-capped before they
+// reach the journal.
+export const MOUNT_URL_MAX_LENGTH = 2000;
+export const MOUNT_ERROR_MAX_LENGTH = 1000;
+
 function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
 function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
 
@@ -92,6 +101,36 @@ function validateManualEditEvent(msg, label) {
   return null;
 }
 
+function isValidMountVariant(value) {
+  return Number.isInteger(value) && value >= 1 && value <= 999;
+}
+
+/**
+ * Mount acknowledgements are the browser's answer to "did the thing you
+ * published actually render". They are validated strictly because the render
+ * truth in the session snapshot is built from them: a malformed ack that slid
+ * through would report a variant as mounted that never was.
+ */
+function validateMountAck(msg) {
+  if (!isValidId(msg.id)) return 'variant_mounted: missing or malformed id';
+  if (!isValidMountVariant(msg.variant)) return 'variant_mounted: variant must be an integer 1-999';
+  if (msg.url !== undefined) {
+    if (typeof msg.url !== 'string') return 'variant_mounted: url must be string';
+    if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mounted: url too long';
+  }
+  return null;
+}
+
+function validateMountFailure(msg) {
+  if (!isValidId(msg.id)) return 'variant_mount_failed: missing or malformed id';
+  if (!isValidMountVariant(msg.variant)) return 'variant_mount_failed: variant must be an integer 1-999';
+  if (typeof msg.url !== 'string' || !msg.url.trim()) return 'variant_mount_failed: url required';
+  if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mount_failed: url too long';
+  if (typeof msg.error !== 'string' || !msg.error.trim()) return 'variant_mount_failed: error required';
+  if (msg.error.length > MOUNT_ERROR_MAX_LENGTH) return 'variant_mount_failed: error too long';
+  return null;
+}
+
 export function validateEvent(msg) {
   if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
   switch (msg.type) {
@@ -120,13 +159,21 @@ export function validateEvent(msg) {
       return null;
     case 'agent_phase':
       if (!isValidId(msg.id)) return 'agent_phase: missing or malformed id';
-      if (typeof msg.phase !== 'string' || !/^[a-z][a-z0-9_]{1,63}$/.test(msg.phase)) {
-        return 'agent_phase: missing or malformed phase';
+      if (typeof msg.phase !== 'string' || !msg.phase) return 'agent_phase: missing phase';
+      // The enum, not a shape pattern. A phase the browser cannot rank is a
+      // phase the progress bar cannot show, so accepting an arbitrary
+      // lowercase word only defers the failure to the UI.
+      if (!AGENT_PHASE_SET.has(msg.phase)) {
+        return 'agent_phase: unknown phase ' + msg.phase + ' (expected one of ' + AGENT_PHASES.join(', ') + ')';
       }
       if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
         return 'agent_phase: durationMs must be a non-negative number';
       }
       return null;
+    case 'variant_mounted':
+      return validateMountAck(msg);
+    case 'variant_mount_failed':
+      return validateMountFailure(msg);
     case 'exit':
       return null;
     case 'prefetch':

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

@@ -0,0 +1,47 @@
+/**
+ * Astro registry entry.
+ *
+ * Astro takes the generic tag strategy, with two Astro-specific values that
+ * used to sit as inline `endsWith('.astro')` branches in live-inject.mjs and
+ * live-wrap.mjs:
+ *
+ *   injectScriptAttrs  Astro processes <script> tags by default and rewrites
+ *                      src to its own bundled URL; is:inline opts out.
+ *   styleMode          Astro scopes component styles, which strips preview CSS
+ *                      off the generated variant wrappers, so preview rules are
+ *                      authored global and prefixed instead of @scope'd.
+ */
+
+import { findConfigFile, hasAnyDependency, literalConfigFiles } from './detect-utils.mjs';
+
+const ASTRO_CONFIG_RE = /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+export function detectAstroProject(cwd = process.cwd(), config = null) {
+  const configFile = findConfigFile(cwd, ASTRO_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['astro'])) return { configFile: null, via: 'package' };
+  // A tree of .astro entry templates with no astro.config still belongs to
+  // Astro; the configured injection target names it.
+  const entry = literalConfigFiles(cwd, config).find((rel) => rel.endsWith('.astro'));
+  if (entry) return { configFile: null, via: 'config-files', entry };
+  return null;
+}
+
+export const astro = {
+  name: 'astro',
+
+  detect(cwd, config) {
+    return detectAstroProject(cwd, config);
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.astro'],
+    preview: 'source',
+    styleMode: 'astro-global-prefixed',
+    styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
+    commentSyntax: 'html',
+    injectScriptAttrs: 'is:inline ',
+  },
+};

.agents/skills/impeccable/scripts/live/frameworks/detect-utils.mjs

@@ -0,0 +1,73 @@
+/**
+ * Small read-only probes the framework entries share.
+ *
+ * Every helper here is cheap and failure-tolerant: detection runs on every
+ * inject, against project trees that may be half-installed, so a missing or
+ * malformed file means "not this framework", never a throw.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Merged dependency names from package.json, or an empty object. */
+export function readPackageDeps(cwd) {
+  const file = path.join(cwd, 'package.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+      ...(pkg.peerDependencies || {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function hasAnyDependency(cwd, names) {
+  const deps = readPackageDeps(cwd);
+  return names.some((name) => Boolean(deps[name]));
+}
+
+/** First top-level file name matching `re`, or null. */
+export function findConfigFile(cwd, re) {
+  try {
+    return fs.readdirSync(cwd, { withFileTypes: true })
+      .find((entry) => entry.isFile() && re.test(entry.name))
+      ?.name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function fileExists(cwd, rel) {
+  try {
+    return fs.existsSync(path.join(cwd, rel));
+  } catch {
+    return false;
+  }
+}
+
+export function firstExistingFile(cwd, candidates) {
+  for (const rel of candidates) {
+    if (fileExists(cwd, rel)) return rel;
+  }
+  return null;
+}
+
+/**
+ * Literal (non-glob) entries of `config.files` that exist on disk. Several
+ * detectors read the configured injection target as a signal, which is how the
+ * bare fixtures — a tree of `.astro` files with no astro.config — still resolve
+ * to the framework that authored them.
+ */
+export function literalConfigFiles(cwd, config) {
+  const files = Array.isArray(config?.files) ? config.files : [];
+  const out = [];
+  for (const rel of files) {
+    if (typeof rel !== 'string' || rel.includes('*') || rel.includes('?')) continue;
+    const normalized = rel.split(path.sep).join('/');
+    if (fileExists(cwd, normalized)) out.push(normalized);
+  }
+  return out;
+}

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

@@ -0,0 +1,143 @@
+/**
+ * The live-mode framework registry.
+ *
+ * Before this existed, framework knowledge was smeared across live-inject.mjs
+ * (detection order, the Nuxt adapter, the Astro `is:inline` branch), the two
+ * adapter modules, and live-wrap.mjs (which extension gets component preview,
+ * which gets Astro's global-prefixed CSS, which gets JSX comments). Adding or
+ * fixing a framework meant reading all of them.
+ *
+ * One entry per framework now declares everything the live scripts need:
+ *
+ *   name        stable identifier; also the `adapter` value in inject JSON.
+ *   detect      (cwd, config) → falsy when this is not the project, otherwise
+ *               a truthy project descriptor that apply/remove/artifacts read.
+ *               Order in FRAMEWORKS is priority order; first truthy wins.
+ *   inject      { kind: 'adapter', apply, remove, ignorePatterns, artifacts,
+ *               unpatch } for frameworks that server-render their document
+ *               shell, or { kind: 'tag' } for the generic marker-wrapped
+ *               <script src> block.
+ *   source      how live-wrap treats files this framework authors:
+ *               extensions, preview ('source' | 'component'), styleMode,
+ *               styleTag, commentSyntax, injectScriptAttrs. Anything omitted
+ *               falls back to SOURCE_TRAIT_DEFAULTS.
+ *
+ * Two rules hold the thing together:
+ *
+ * 1. **Detection order is injection priority.** SvelteKit → Nuxt → TanStack
+ *    Start → Astro → Next → Vite → static HTML, exactly the order
+ *    live-inject.mjs used to hard-code. static-html always matches, so
+ *    resolveFramework never returns null.
+ * 2. **Source traits resolve by file extension, not by project.** A SvelteKit
+ *    project's injection target is `src/app.html`; a Vite app can contain
+ *    `.astro` partials. live-wrap has always keyed these off the target file,
+ *    and resolveSourceTraits keeps it that way. Several entries may claim the
+ *    same extension (`.tsx` belongs to three); when they do, the values must
+ *    agree, which tests/live-frameworks.test.mjs asserts.
+ */
+
+import path from 'node:path';
+
+import { sveltekit } from './sveltekit.mjs';
+import { nuxt } from './nuxt.mjs';
+import { tanstackStart } from './tanstack-start.mjs';
+import { astro } from './astro.mjs';
+import { nextjs } from './nextjs.mjs';
+import { viteGeneric } from './vite-generic.mjs';
+import { staticHtml } from './static-html.mjs';
+import { TAG_PATCH_MARKERS, unpatchTagFile } from './tag-strategy.mjs';
+
+/** Priority order. Do not reorder without re-reading rule 1 above. */
+export const FRAMEWORKS = Object.freeze([
+  sveltekit,
+  nuxt,
+  tanstackStart,
+  astro,
+  nextjs,
+  viteGeneric,
+  staticHtml,
+]);
+
+export const PREVIEW_MODES = Object.freeze(['source', 'component']);
+export const STYLE_MODES = Object.freeze(['scoped', 'astro-global-prefixed']);
+export const COMMENT_SYNTAXES = Object.freeze(['html', 'jsx']);
+export const INJECT_KINDS = Object.freeze(['adapter', 'tag']);
+
+export const SOURCE_TRAIT_DEFAULTS = Object.freeze({
+  preview: 'source',
+  styleMode: 'scoped',
+  styleTag: '<style data-impeccable-css="SESSION_ID">',
+  commentSyntax: 'html',
+  injectScriptAttrs: '',
+});
+
+/** The patch kind the generic tag strategy records in the journal. */
+export const TAG_PATCH_KIND = 'live-tag';
+
+/**
+ * Undo functions keyed by the `patch` value an artifact carries. Built from
+ * the entries so a new adapter registers its own undo alongside its apply.
+ */
+export const PATCH_UNDOERS = Object.freeze(Object.assign(
+  { [TAG_PATCH_KIND]: unpatchTagFile },
+  ...FRAMEWORKS.map((framework) => framework.inject.unpatch || {}),
+));
+
+/**
+ * First entry whose detect() matches. Returns { framework, project } where
+ * project is the detector's descriptor (adapters read it; tag frameworks
+ * mostly ignore it).
+ */
+export function resolveFramework(cwd = process.cwd(), config = null) {
+  for (const framework of FRAMEWORKS) {
+    const project = framework.detect(cwd, config);
+    if (project) return { framework, project };
+  }
+  // Unreachable while static-html stays terminal, but a caller that reorders
+  // the array should get a diagnosable null rather than a silent tag inject.
+  return null;
+}
+
+/**
+ * Source-authoring traits for one file, merged over SOURCE_TRAIT_DEFAULTS.
+ * `framework` names the entry that claimed the extension, or null.
+ */
+export function resolveSourceTraits(filePath) {
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  for (const framework of FRAMEWORKS) {
+    const source = framework.source;
+    if (!source || !source.extensions.includes(ext)) continue;
+    const { extensions, ...traits } = source;
+    return { framework: framework.name, ...SOURCE_TRAIT_DEFAULTS, ...traits };
+  }
+  return { framework: null, ...SOURCE_TRAIT_DEFAULTS };
+}
+
+/**
+ * Extra gitignore patterns the resolved framework needs beyond the static
+ * LIVE_IGNORE_PATTERNS list (paths that depend on a detected srcDir or file
+ * extension and so cannot be written down ahead of time).
+ */
+export function frameworkIgnorePatterns(resolved) {
+  const fn = resolved?.framework?.inject?.ignorePatterns;
+  return typeof fn === 'function' ? (fn(resolved.project) || []) : [];
+}
+
+/**
+ * The files this injection will create or patch, in journal-artifact form.
+ * Adapters declare their own; the tag strategy patches exactly the resolved
+ * config files.
+ */
+export function describeInjectArtifacts(resolved, { cwd = process.cwd(), files = [] } = {}) {
+  if (!resolved) return [];
+  const { framework, project } = resolved;
+  if (framework.inject.kind === 'adapter') {
+    return (framework.inject.artifacts?.({ cwd, project }) || []).filter((a) => a && a.path);
+  }
+  return files.map((file) => ({
+    kind: 'patched',
+    path: file,
+    patch: TAG_PATCH_KIND,
+    markers: [...TAG_PATCH_MARKERS],
+  }));
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Crash-safe injection journal.
+ *
+ * Injection writes into the user's source tree: generated components, a Nuxt
+ * client plugin, marker blocks inside a layout, a patched CSP meta tag. The
+ * clean path removes all of it on stop. The unclean paths do not:
+ *
+ *   - the dev server is SIGKILLed, so `--remove` never runs;
+ *   - the project changes shape between start and stop (a nuxt.config appears,
+ *     a package.json is edited), so detection resolves a different framework
+ *     and the old framework's artifacts are nobody's business;
+ *   - stop runs from a different directory than start did.
+ *
+ * So every inject records what it wrote to `.impeccable/live/inject-journal.json`
+ * before the next one runs, and both inject and `--remove` reconcile that
+ * record against the tree.
+ *
+ * **The journal is a claim of ownership, not a to-do list.** Healing an
+ * artifact only ever removes what still carries our marker; a generated file
+ * the user has since replaced, or a layout they have since un-patched by hand,
+ * is dropped from the journal untouched.
+ *
+ * **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
+ * roots manifest (`enterLiveRoot`) before doing anything, so a journal written
+ * by a session started in the app root is found by a stop issued from any
+ * directory inside the repo.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { PATCH_UNDOERS } from './index.mjs';
+
+export const INJECT_JOURNAL_VERSION = 1;
+export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
+
+export function injectJournalPath(cwd = process.cwd()) {
+  return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
+}
+
+export function readInjectJournal(cwd = process.cwd()) {
+  const file = injectJournalPath(cwd);
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
+  return raw;
+}
+
+export function clearInjectJournal(cwd = process.cwd()) {
+  try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
+}
+
+function writeInjectJournal(cwd, journal) {
+  const file = injectJournalPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
+  return file;
+}
+
+/**
+ * Record the artifacts an injection just wrote. Replaces any previous record:
+ * callers heal first (see healInjectJournal), so nothing survivable is lost.
+ */
+export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
+  if (!artifacts.length) {
+    clearInjectJournal(cwd);
+    return null;
+  }
+  return writeInjectJournal(cwd, {
+    version: INJECT_JOURNAL_VERSION,
+    appRoot: path.resolve(cwd),
+    framework: framework || null,
+    port: Number.isFinite(Number(port)) ? Number(port) : null,
+    pid: process.pid,
+    recordedAt: new Date().toISOString(),
+    artifacts,
+  });
+}
+
+function normalizeRel(cwd, rel) {
+  return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
+}
+
+function readIfPresent(abs) {
+  try {
+    return fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function pruneEmptyDirs(dir, stopDir) {
+  let current = path.resolve(dir);
+  const stop = path.resolve(stopDir);
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      if (fs.readdirSync(current).length > 0) return;
+      fs.rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = path.dirname(current);
+  }
+}
+
+function insideProject(cwd, abs) {
+  const rel = path.relative(path.resolve(cwd), path.resolve(abs));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function healArtifact(cwd, artifact, undoers) {
+  const abs = path.resolve(cwd, artifact.path);
+  // The journal is a project-local file, i.e. attacker-writable input in a
+  // cloned repo. Never touch anything outside the project tree, whatever the
+  // journal claims to own.
+  if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
+  const content = readIfPresent(abs);
+  if (content === null) return { path: artifact.path, action: 'absent' };
+
+  if (artifact.kind === 'created') {
+    // Only reclaim a generated file that still carries our marker; a created
+    // artifact with no marker at all is unverifiable and stays untouched.
+    if (!artifact.marker || !content.includes(artifact.marker)) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    try { fs.rmSync(abs, { force: true }); } catch { return null; }
+    if (artifact.pruneTo !== undefined) {
+      const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
+      if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
+        pruneEmptyDirs(path.dirname(abs), pruneRoot);
+      }
+    }
+    return { path: artifact.path, action: 'removed' };
+  }
+
+  if (artifact.kind === 'patched') {
+    const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
+    // No marker left means the patch is already gone; never run an undo over
+    // a file we no longer recognize (the undoers normalize whitespace).
+    if (markers.length && !markers.some((marker) => content.includes(marker))) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    const undo = undoers[artifact.patch];
+    if (typeof undo !== 'function') return null;
+    const next = undo(content);
+    if (next === content) return { path: artifact.path, action: 'disowned' };
+    try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
+    return { path: artifact.path, action: 'unpatched' };
+  }
+
+  return null;
+}
+
+/**
+ * Reconcile the journal against the tree.
+ *
+ * `keep` is the set of paths the current operation legitimately owns — the
+ * artifacts an inject is about to (re)write. Everything else in the journal is
+ * an orphan of a session that is gone, and gets healed. This keeps a repeat
+ * inject byte-idempotent: the artifacts it is about to rewrite are kept, not
+ * torn down and rebuilt.
+ *
+ * Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
+ * actually changed or removed, so callers can stay silent when nothing was
+ * orphaned. Idempotent: a second call finds an empty journal.
+ */
+export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
+  const journal = readInjectJournal(cwd);
+  if (!journal) return { healed: [], kept: [] };
+
+  const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
+  const healed = [];
+  const kept = [];
+
+  for (const artifact of journal.artifacts) {
+    if (!artifact || typeof artifact.path !== 'string') continue;
+    if (keepSet.has(normalizeRel(cwd, artifact.path))) {
+      kept.push(artifact);
+      continue;
+    }
+    const outcome = healArtifact(cwd, artifact, undoers);
+    if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
+      healed.push(outcome);
+    }
+  }
+
+  if (kept.length) {
+    writeInjectJournal(cwd, { ...journal, artifacts: kept });
+  } else {
+    clearInjectJournal(cwd);
+  }
+
+  return { healed, kept };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Next.js registry entry.
+ *
+ * Next takes the generic tag strategy: the App Router's root layout renders
+ * `<html>…<body>` in JSX, so the marker-wrapped script block goes in there
+ * verbatim. Nothing about injection differs from a plain Vite app, which is
+ * why live-inject.mjs never had a Next branch. The entry exists so the
+ * registry can name what it is looking at.
+ */
+
+import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
+
+const NEXT_CONFIG_RE = /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+const ROUTER_ENTRY_CANDIDATES = [
+  'app/layout.tsx', 'app/layout.jsx', 'app/layout.ts', 'app/layout.js',
+  'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.ts', 'src/app/layout.js',
+  'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.ts', 'pages/_app.js',
+  'pages/_document.tsx', 'pages/_document.jsx',
+  'src/pages/_app.tsx', 'src/pages/_app.jsx',
+];
+
+export function detectNextProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, NEXT_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['next'])) return { configFile: null, via: 'package' };
+  // Next's file conventions are distinctive enough to stand alone: a root
+  // `app/layout.*` or `pages/_app.*` is not a shape other bundlers produce.
+  const entry = ROUTER_ENTRY_CANDIDATES.find((rel) => fileExists(cwd, rel));
+  if (entry) return { configFile: null, via: 'router-entry', entry };
+  return null;
+}
+
+export const nextjs = {
+  name: 'nextjs',
+
+  detect(cwd) {
+    return detectNextProject(cwd);
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

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

@@ -0,0 +1,161 @@
+/**
+ * Nuxt registry entry, and the Nuxt adapter itself.
+ *
+ * A script element placed in app.vue is compiled as Vue-rendered DOM and is
+ * not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
+ * generated, dev-only, and outside user-authored source: Live creates one
+ * marked .client.ts plugin on start and removes it on stop.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from './script-src.mjs';
+import { findConfigFile } from './detect-utils.mjs';
+
+export const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
+export const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
+
+const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+export function detectNuxtProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, NUXT_CONFIG_RE);
+  if (!configFile) return null;
+
+  const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
+  const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
+  let appDir = '';
+  if (literalSrcDir) {
+    const candidate = literalSrcDir[2]
+      .replace(/\\/g, '/')
+      .replace(/^\.\//, '')
+      .replace(/\/+$/, '');
+    const normalized = path.posix.normalize(candidate);
+    if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
+      appDir = normalized === '.' ? '' : normalized;
+    }
+  } else if (
+    fs.existsSync(path.join(cwd, 'app', 'app.vue'))
+    || fs.existsSync(path.join(cwd, 'app', 'pages'))
+  ) {
+    appDir = 'app';
+  }
+
+  const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
+  return { configFile, appDir, pluginFile };
+}
+
+export function buildNuxtPlugin(port, token) {
+  return `/* ${NUXT_PLUGIN_MARKER} */
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
+const liveSelector = 'script[data-impeccable-live-nuxt]';
+
+export default defineNuxtPlugin(() => {
+  if (!import.meta.dev || typeof document === 'undefined') return;
+
+  const expectedSrc = new URL(liveSrc, window.location.href).href;
+  let script = document.querySelector(liveSelector);
+  if (script?.src === expectedSrc) return;
+  script?.remove();
+
+  script = document.createElement('script');
+  script.src = liveSrc;
+  script.async = true;
+  script.dataset.impeccableLiveNuxt = '';
+  document.head.appendChild(script);
+
+  import.meta.hot?.dispose(() => {
+    if (script?.isConnected) script.remove();
+  });
+});
+/* /${NUXT_PLUGIN_MARKER} */
+`;
+}
+
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
+  if (!project) return { error: 'nuxt_not_detected' };
+  const absFile = path.join(cwd, project.pluginFile);
+  const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
+  if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
+    return {
+      file: project.pluginFile,
+      error: 'nuxt_plugin_conflict',
+      hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+
+  const content = buildNuxtPlugin(port, token);
+  fs.mkdirSync(path.dirname(absFile), { recursive: true });
+  if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
+  return {
+    file: project.pluginFile,
+    inserted: true,
+    changed: content !== existing,
+    devOnly: true,
+  };
+}
+
+export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
+  if (!project) return { error: 'nuxt_not_detected' };
+  const absFile = path.join(cwd, project.pluginFile);
+  if (!fs.existsSync(absFile)) {
+    return { file: project.pluginFile, removed: false, note: 'no adapter present' };
+  }
+  const content = fs.readFileSync(absFile, 'utf-8');
+  if (!content.includes(NUXT_PLUGIN_MARKER)) {
+    return {
+      file: project.pluginFile,
+      removed: false,
+      error: 'nuxt_plugin_conflict',
+      hint: `${project.pluginFile} is not managed by Impeccable Live`,
+    };
+  }
+  fs.unlinkSync(absFile);
+  const pluginDir = path.dirname(absFile);
+  if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
+  return { file: project.pluginFile, removed: true };
+}
+
+export const nuxt = {
+  name: 'nuxt',
+
+  detect(cwd) {
+    return detectNuxtProject(cwd);
+  },
+
+  inject: {
+    kind: 'adapter',
+
+    apply({ cwd, port, token, project }) {
+      return applyNuxtLiveAdapter({ cwd, port, token, project });
+    },
+
+    remove({ cwd, project }) {
+      return removeNuxtLiveAdapter({ cwd, project });
+    },
+
+    // The plugin path depends on the resolved srcDir, so it cannot live in the
+    // static ignore list the way the SvelteKit paths do.
+    ignorePatterns(project) {
+      return project?.pluginFile ? [project.pluginFile] : [];
+    },
+
+    artifacts({ project }) {
+      if (!project?.pluginFile) return [];
+      return [{
+        kind: 'created',
+        path: project.pluginFile,
+        marker: NUXT_PLUGIN_MARKER,
+        // Mirrors removeNuxtLiveAdapter: the generated `plugins/` directory
+        // goes when it empties, its parent stays.
+        pruneTo: path.posix.dirname(path.posix.dirname(project.pluginFile)),
+      }];
+    },
+  },
+
+  source: {
+    extensions: ['.vue'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'html',
+  },
+};

.agents/skills/impeccable/scripts/live/frameworks/script-src.mjs

@@ -0,0 +1,17 @@
+/**
+ * The one place that builds the `/live.js` URL the browser loads.
+ *
+ * Every injection path needs it (the generic script tag, the Nuxt client
+ * plugin, the SvelteKit root component, the TanStack mount component), and a
+ * separate module keeps that shared leaf free of import cycles: the framework
+ * entries import it, and nothing here imports a framework entry.
+ */
+
+/**
+ * When a token is supplied it rides as a `?token=...` query param so the
+ * server's token-gated /live.js handler authorizes the fetch.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}

.agents/skills/impeccable/scripts/live/frameworks/static-html.mjs

@@ -0,0 +1,26 @@
+/**
+ * Static HTML registry entry: the terminal fallback.
+ *
+ * Hand-written pages, a multi-page site emitted by a generator, anything with
+ * no bundler config at the app root. `detect` always matches, so this entry
+ * must stay last in FRAMEWORKS. Its behavior is the plain tag strategy, which
+ * is what live-inject.mjs did for every unrecognized project before the
+ * registry existed.
+ */
+
+export const staticHtml = {
+  name: 'static-html',
+
+  detect() {
+    return { via: 'fallback' };
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.html', '.htm'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'html',
+  },
+};

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

@@ -0,0 +1,71 @@
+/**
+ * SvelteKit registry entry.
+ *
+ * Detection and the apply/remove pair are the existing adapter's
+ * (`../sveltekit-adapter.mjs`); this file only declares them to the registry
+ * and names the artifacts the journal has to be able to heal.
+ */
+
+import {
+  SVELTE_LAYOUT_MARKER_OPEN,
+  SVELTE_LIVE_ROOT_COMPONENT,
+  applySvelteKitLiveAdapter,
+  detectSvelteKitProject,
+  removeSvelteKitLiveAdapter,
+  unpatchSvelteLayout,
+} from '../sveltekit-adapter.mjs';
+
+export const sveltekit = {
+  name: 'sveltekit',
+
+  detect(cwd, config) {
+    return detectSvelteKitProject(cwd, config);
+  },
+
+  inject: {
+    kind: 'adapter',
+
+    apply({ cwd, port, token, config }) {
+      return applySvelteKitLiveAdapter({ cwd, port, token, config });
+    },
+
+    remove({ cwd, config }) {
+      return removeSvelteKitLiveAdapter({ cwd, config });
+    },
+
+    // The generated root component and the `src/lib/impeccable/` runtime paths
+    // are already in the static LIVE_IGNORE_PATTERNS list, so nothing extra.
+    ignorePatterns() {
+      return [];
+    },
+
+    artifacts({ project }) {
+      return [
+        {
+          kind: 'created',
+          path: SVELTE_LIVE_ROOT_COMPONENT,
+          marker: 'impeccable-live-root',
+          pruneTo: 'src',
+        },
+        {
+          kind: 'patched',
+          path: project?.layoutFile || 'src/routes/+layout.svelte',
+          patch: 'sveltekit-layout',
+          markers: [SVELTE_LAYOUT_MARKER_OPEN],
+        },
+      ];
+    },
+
+    unpatch: {
+      'sveltekit-layout': unpatchSvelteLayout,
+    },
+  },
+
+  source: {
+    extensions: ['.svelte'],
+    // Svelte resets component-local state on markup HMR updates, so variants
+    // are mounted from generated components rather than written into the route.
+    preview: 'component',
+    commentSyntax: 'html',
+  },
+};

.agents/skills/impeccable/scripts/live/frameworks/tag-strategy.mjs

@@ -0,0 +1,247 @@
+/**
+ * The generic `tag` injection strategy.
+ *
+ * Frameworks without a dedicated adapter get a literal marker-wrapped
+ * `<script src>` block written into the entry template named by
+ * `.impeccable/live/config.json`. This module owns that block: building it,
+ * inserting it at the configured anchor, removing it again, and the
+ * Content-Security-Policy meta patch that keeps the cross-origin load allowed.
+ *
+ * It is deliberately framework-agnostic. Per-framework knowledge (Astro's
+ * `is:inline`, for instance) arrives as the `scriptAttrs` argument, resolved
+ * from the registry by the caller, so nothing here has to branch on a file
+ * extension or a project shape.
+ */
+
+import { buildLiveScriptSrc } from './script-src.mjs';
+
+export const MARKER_OPEN_TEXT = 'impeccable-live-start';
+export const MARKER_CLOSE_TEXT = 'impeccable-live-end';
+
+/** Markers that identify a file as still carrying our tag-strategy patch. */
+export const TAG_PATCH_MARKERS = Object.freeze([MARKER_OPEN_TEXT, 'data-impeccable-csp-original']);
+
+function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
+function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
+
+/**
+ * `scriptAttrs` is a pre-rendered attribute string (trailing space included)
+ * that the registry supplies for the target file. Astro is the only framework
+ * that uses it today: Astro processes `<script>` tags by default and rewrites
+ * src to its own bundled URL, so `is:inline ` opts out and the literal external
+ * src survives.
+ */
+export function buildTagBlock(syntax, port, token, scriptAttrs = '') {
+  const open = commentOpen(syntax);
+  const close = commentClose(syntax);
+  return (
+    open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
+    open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
+  );
+}
+
+function detectLineEnding(content) {
+  if (content.includes('\r\n')) return '\r\n';
+  if (content.includes('\r')) return '\r';
+  return '\n';
+}
+
+function normalizeLineEndings(content, lineEnding) {
+  return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
+}
+
+function readLineEndingAt(content, index) {
+  if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
+  if (content[index] === '\n') return '\n';
+  if (content[index] === '\r') return '\r';
+  return '';
+}
+
+export function insertTag(content, config, port, token, scriptAttrs = '') {
+  const lineEnding = detectLineEnding(content);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, token, scriptAttrs), lineEnding);
+  // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
+  // belong at the end, and the same literal can appear earlier in code blocks
+  // within rendered documentation pages.
+  if (config.insertBefore) {
+    const idx = content.lastIndexOf(config.insertBefore);
+    if (idx === -1) return content;
+    return content.slice(0, idx) + block + content.slice(idx);
+  }
+  // insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
+  // `<body>` open near the top of the document.
+  const idx = content.indexOf(config.insertAfter);
+  if (idx === -1) return content;
+  const after = idx + config.insertAfter.length;
+  // Preserve an existing trailing newline if the anchor already has one.
+  // Slice the remainder from the original anchor offset, not prefix.length:
+  // in the no-newline case prefix is one char longer than the anchor (the
+  // appended '\n'), so slicing by prefix.length would drop the first real
+  // character after the anchor (#227).
+  const existingNewline = readLineEndingAt(content, after);
+  const prefix = content.slice(0, after) + (existingNewline || lineEnding);
+  const rest = content.slice(after + existingNewline.length);
+  return prefix + block + rest;
+}
+
+/**
+ * Remove the live script block. Matches either HTML or JSX comment markers
+ * regardless of config (so stale tags from a wrong config can still be cleaned).
+ *
+ * Indent-preserving: captures any whitespace immediately preceding the opener
+ * marker and re-emits it in place of the removed block. `insertTag` inserted
+ * the block *after* the original line's indent and *before* the anchor (e.g.
+ * `</body>`), which moved the indent onto the opener line and left the anchor
+ * unindented. Replacing the whole block (plus its trailing newline) with just
+ * the captured indent hands the indent back to the anchor that follows.
+ */
+export function removeTag(content, _syntax) {
+  const patterns = [
+    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
+    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
+  ];
+  for (const pat of patterns) {
+    let changed = false;
+    let next = content;
+    do {
+      content = next;
+      next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
+        if (/[\r\n]/.test(trailing)) return leadingIndent;
+        return leadingIndent || trailing || '';
+      });
+      if (next !== content) changed = true;
+    } while (next !== content);
+    if (changed) return next;
+  }
+  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;
+}
+
+/** The journal's undo for a tag-strategy patch: drop the block, restore CSP. */
+export function unpatchTagFile(content) {
+  return revertCspMeta(removeTag(content));
+}

.agents/skills/impeccable/scripts/live/frameworks/tanstack-start.mjs

@@ -0,0 +1,70 @@
+/**
+ * TanStack Start registry entry.
+ *
+ * Detection and the apply/remove pair are the existing adapter's
+ * (`../tanstack-adapter.mjs`); this file only declares them to the registry
+ * and names the artifacts the journal has to be able to heal.
+ */
+
+import {
+  TANSTACK_MARKER_OPEN,
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+  unpatchTanStackRoot,
+} from '../tanstack-adapter.mjs';
+
+export const tanstackStart = {
+  name: 'tanstack-start',
+
+  detect(cwd) {
+    return detectTanStackStartProject(cwd);
+  },
+
+  inject: {
+    kind: 'adapter',
+
+    apply({ cwd, port, token, project }) {
+      return applyTanStackLiveAdapter({ cwd, port, token, project });
+    },
+
+    remove({ cwd, project }) {
+      return removeTanStackLiveAdapter({ cwd, project });
+    },
+
+    // The mount component's extension follows the root route's, so the path
+    // cannot live in the static ignore list.
+    ignorePatterns(project) {
+      return project?.componentFile ? [project.componentFile] : [];
+    },
+
+    artifacts({ project }) {
+      if (!project) return [];
+      return [
+        {
+          kind: 'created',
+          path: project.componentFile,
+          marker: 'impeccable-live-tanstack',
+          pruneTo: 'src',
+        },
+        {
+          kind: 'patched',
+          path: project.rootRoute,
+          patch: 'tanstack-root',
+          markers: [TANSTACK_MARKER_OPEN],
+        },
+      ];
+    },
+
+    unpatch: {
+      'tanstack-root': unpatchTanStackRoot,
+    },
+  },
+
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

.agents/skills/impeccable/scripts/live/frameworks/vite-generic.mjs

@@ -0,0 +1,42 @@
+/**
+ * Generic Vite registry entry: a bundled app with a real `index.html` entry
+ * and no framework-specific document ownership. React, Vue, Solid, Preact and
+ * a plain TanStack Router SPA all land here — the marker-wrapped script block
+ * goes straight into the HTML entry.
+ *
+ * This is the entry that catches everything with a bundler config; only
+ * static-html sits below it.
+ */
+
+import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
+
+const VITE_CONFIG_RE = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+export function detectViteProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, VITE_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['vite'])) return { configFile: null, via: 'package' };
+  // A zero-config Vite app is index.html + package.json, the same pair
+  // roots.mjs treats as an app root.
+  if (fileExists(cwd, 'index.html') && fileExists(cwd, 'package.json')) {
+    return { configFile: null, via: 'zero-config' };
+  }
+  return null;
+}
+
+export const viteGeneric = {
+  name: 'vite-generic',
+
+  detect(cwd) {
+    return detectViteProject(cwd);
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

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

@@ -0,0 +1,142 @@
+/**
+ * Just-in-time agent instructions for live mode.
+ *
+ * The live scripts, not the reference doc, own situational plumbing: every
+ * event printed by live-poll carries an `_instructions` string describing
+ * exactly what to do NEXT, with real ids, paths, and line numbers already
+ * substituted and only the active path's rules included (a svelte-component
+ * session never sees JSX guidance, and vice versa). live.md stays lean: the
+ * session contract, harness policy, and design-quality guidance that is not
+ * situational (identity lock, variation axes, parameter budgets).
+ *
+ * Keep these strings imperative, concrete, and short. They are read by an
+ * agent mid-session; every sentence must earn its tokens. Instructions are
+ * versioned with the scripts, so they cannot drift from behavior the way a
+ * hand-maintained doc can.
+ */
+
+const PLAN_POINTER = 'Plan per live.md section 4: extract the identity lock, pick default vs departure mode, commit each variant to a DIFFERENT primary axis, squint-test the trio. Size parameter knobs per section 7 budgets.';
+
+function pollCmd(scriptsPath) {
+  return `node ${scriptsPath}/live-poll.mjs`;
+}
+
+function replyCmd(scriptsPath, id, rest) {
+  return `${pollCmd(scriptsPath)} --reply ${id} ${rest}`;
+}
+
+export function instructionsForEvent(event, { scriptsPath = '{{scripts_path}}' } = {}) {
+  if (!event || typeof event !== 'object') return undefined;
+  switch (event.type) {
+    case 'generate':
+      return generateInstructions(event, scriptsPath);
+    case 'steer':
+      return `Do what the message asks (page edits, navigation help, or a short answer). Then reply exactly once: ${replyCmd(scriptsPath, event.id, 'steer_done ["optional short toast"]')} (on failure: --reply ${event.id} error "Short reason"). No pickup ack; poll again immediately after.`;
+    case 'prefetch':
+      return `Speculative pre-read, no reply owed: resolve ${JSON.stringify(event.pageUrl || '/')} to its source file (root "/" is usually the boot's pageFile; multi-page sites map /foo to public/foo/index.html; SPAs map all routes to one entry), read it into context, then poll again. Skip if you cannot resolve it confidently.`;
+    case 'variant_mount_failed':
+      return `The browser could NOT render variant ${event.variant}${event.url ? ` (module: ${event.url})` : ''}${event.error ? `: ${String(event.error).slice(0, 200)}` : ''}. The user sees a persistent error card, not variants. Fix the variant source files, then reply ${replyCmd(scriptsPath, event.id, 'done --file <manifest or source path>')}; the browser retries on its own. Poll again after the reply.`;
+    case 'accept':
+      return acceptInstructions(event, scriptsPath);
+    case 'discard':
+      return event?._completionAck?.ok === true
+        ? 'Original restored and durable completion acknowledged; nothing to do. Poll again.'
+        : `Completion was not acknowledged: run node ${scriptsPath}/live-complete.mjs --id ${event.id} --discarded, then poll again.`;
+    case 'manual_edit_apply':
+      return `The user already clicked Apply; never ask, discard, or redirect. Delegate the source edits to the impeccable_manual_edit_applier subagent when available (pass cwd, scripts path, event id, page URL, chunk/deadline, batch, evidencePath); it must not poll or reply. ${event.repair ? 'A `repair` payload is present: the previous Apply changed source but validation failed; fix the CURRENT source, never roll back yourself. ' : ''}Reply exactly once: ${replyCmd(scriptsPath, event.id, `done --data '{"status":"done","appliedEntryIds":[...],"failed":[],"files":[...],"notes":[]}'`)} (status "partial"/"error" with failed[] when not every entry applied). Then poll again.`;
+    case 'timeout':
+      return 'No event arrived; poll again immediately.';
+    case 'exit':
+      return `Session over: kill any background poll, then node ${scriptsPath}/live-server.mjs stop (removes the injected script tag). Sweep leftover impeccable-variants-start / impeccable-carbonize-start markers from source.`;
+    default:
+      return undefined;
+  }
+}
+
+function generateInstructions(event, scriptsPath) {
+  const id = event.id;
+  const scaffold = event.scaffold;
+  const steps = [];
+
+  if (event.screenshotPath) {
+    steps.push(`Read the annotated screenshot first: ${event.screenshotPath}. Comment {x,y} positions bind text to the child under that point; strokes read by shape (loop = emphasis on this thing, arrow = direction, cross = delete).`);
+  } else {
+    steps.push('No screenshot was sent (the user did not annotate); do not ask for one and do not screenshot the page. Work from element.outerHTML, the computed styles, and the prompt.');
+  }
+
+  if (event.mode === 'insert') {
+    steps.push(insertScaffoldInstructions(event, scriptsPath));
+  } else if (scaffold?.previewMode === 'svelte-component') {
+    steps.push(svelteComponentInstructions(event, scaffold, scriptsPath));
+  } else if (scaffold && scaffold.sourceWritten === false) {
+    steps.push(deferredWrapperInstructions(event, scaffold, scriptsPath));
+  } else if (scaffold) {
+    steps.push(`The wrapper is already written into ${scaffold.file}. Splice preview CSS plus all ${event.count} variants at line ${scaffold.insertLine} in ONE edit, following the returned cssAuthoring contract (styleTag, selector strategy, forbidden patterns). Each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none.`);
+  } else {
+    steps.push(`Preflight could not scaffold${event.scaffoldError ? ` (${event.scaffoldError})` : ''}. Run node ${scriptsPath}/live-wrap.mjs --id ${id} --count ${event.count} --element-id "${event.element?.id || ''}" --classes "${(event.element?.classes || []).join(',')}" --tag "${event.element?.tagName || ''}" --text "<first ~80 chars of the picked element's textContent>". Keep the flags separate; --text disambiguates repeated siblings. On a fallback error, follow live.md's Handle fallback.`);
+  }
+
+  steps.push(event.action && event.action !== 'impeccable'
+    ? `Action is "${event.action}": read reference/${event.action}.md before planning; its MUST params are non-negotiable. ${PLAN_POINTER}`
+    : `Freeform action: work from SKILL.md rules plus craft-floor.md; no sub-command file. ${PLAN_POINTER}`);
+
+  steps.push(`When all ${event.count} variants are delivered: ${replyCmd(scriptsPath, id, 'done --file <project-root-relative path you wrote>')}. Then poll again. If generation fails after the browser flipped to GENERATING, reply --reply ${id} error "Short reason" so the bar resets (never live-accept --discard for this).`);
+
+  return steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+}
+
+function svelteComponentInstructions(event, scaffold, scriptsPath) {
+  const dir = scaffold.componentDir;
+  const count = event.count;
+  return `Svelte component preview. EDIT the existing stubs ${dir}/v1.svelte ... v${count}.svelte in place; never delete or recreate them; do not read them back (the prop-substituted markup is in scaffold.componentStubMarkup). Keep the stub's control flow ({#each}, {#if}) and propContract prop names exactly; never flatten a loop into literal items. The stub <style> is seeded with the source rules that style the selection; restyle or delete freely, and know that any seeded rule you do not re-declare is REMOVED from source on accept (the preview never applied it). ALL your CSS goes inside that ONE existing <style> block: Svelte forbids a second top-level style element, and a publish with a non-compiling variant is bounced back to you with file and line. Semantic class selectors only: no @scope, no data-impeccable-* attributes. Params go in ${dir}/params.json keyed by variant number (never an attribute); author knob CSS against var(--p-<id>, default) and :global([data-p-<id>="..."]). Reply with --file ${scaffold.file}. Accept later merges everything into ${scaffold.sourceFile} mechanically; you have no post-accept cleanup.`;
+}
+
+function deferredWrapperInstructions(event, scaffold, scriptsPath) {
+  const insertNote = Number(scaffold.replaceEndLine) < Number(scaffold.replaceStartLine)
+    ? ` (replaceEndLine < replaceStartLine: this is an INSERTION at line ${scaffold.replaceStartLine}; remove nothing)`
+    : '';
+  return `The wrapper is NOT in source yet. In ONE edit to ${scaffold.file}: splice preview CSS plus all ${event.count} variants into scaffold.wrapperBlock at the "Variants: insert below this line" marker, then replace lines ${scaffold.replaceStartLine}-${scaffold.replaceEndLine}${insertNote} with the result. Two separate writes reload the framework mid-publish and strand the browser at 0/N. Author CSS per the returned cssAuthoring contract; each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none. On JSX/TSX wrap the <style> content in a template literal and use className / style={{...}}.`;
+}
+
+function insertScaffoldInstructions(event, scriptsPath) {
+  const scaffold = event.scaffold;
+  const base = `Insert mode: net-new content sized around ${event.placeholder?.width || '?'}x${event.placeholder?.height || '?'} at the chosen anchor; load craft-floor.md before writing net-new markup.`;
+  if (scaffold?.previewMode === 'svelte-component') {
+    return `${base} Write each inserted variant as a single-root Svelte component under ${scaffold.componentDir} (no data-impeccable-* attributes, CSS in each component's <style>). Never edit the route during generation; reply with --file ${scaffold.file}.`;
+  }
+  if (scaffold && scaffold.sourceWritten === false) {
+    return `${base} Splice your variants into scaffold.wrapperBlock at the marker and insert the result at line ${scaffold.replaceStartLine} of ${scaffold.file} in ONE edit.`;
+  }
+  return `${base} If no scaffold payload is present, run node ${scriptsPath}/live-insert.mjs --id ${event.id} --count ${event.count} --position ${event.insert?.position || 'after'} with the anchor flags from event.insert.anchor, then splice variants at the returned insertLine.`;
+}
+
+function acceptInstructions(event, scriptsPath) {
+  const result = event._acceptResult || {};
+  const ackOk = event._completionAck?.ok === true;
+  const prefix = ackOk ? '' : `Completion was NOT acknowledged: run node ${scriptsPath}/live-status.mjs, finish any cleanup, then node ${scriptsPath}/live-complete.mjs --id ${event.id}. `;
+
+  if (result.handled === true && result.carbonize === true) {
+    return `${prefix}Carbonize cleanup is REQUIRED now, before the next poll, in ${result.file}: (1) locate the impeccable-carbonize-start/end block and read the impeccable-param-values comment; (2) move the CSS rules into the stylesheet that owns this area; (3) bake params while rewriting selectors (@scope wrappers to semantic classes, keep only the chosen data-p branch, substitute range literals); (4) unwrap the accepted content and drop every data-impeccable-* / data-p-* attribute; (5) delete the inline <style>, the param-values comment, and both markers plus dead @scope rules. Then run node ${scriptsPath}/live-complete.mjs --id ${event.id} and verify phase "completed"; it refuses with source_dirty while leftovers remain. Poll again only after that.`;
+  }
+  if (result.handled === true) {
+    return `${prefix}Accept was merged into source mechanically; nothing to clean up. Poll again.`;
+  }
+  if (result.mode === 'fallback') {
+    return `${prefix}The session lived in a generated file, so accept refused to persist there. Write the accepted variant into the true source you identified during Handle fallback, remove the temporary wrapper from the served file, then poll again.`;
+  }
+  if (result.mode === 'error') {
+    if (result.error === 'source_locked') {
+      return `${prefix}The source file is briefly locked by a publisher. Re-run the exact same live-accept.mjs command (idempotent); do NOT hand-edit the file, and do not poll past this.`;
+    }
+    if (result.error === 'accept_receipt_conflict') {
+      return `${prefix}This session already resolved as ${result.priorOperation || 'a prior operation'}; do not edit anything. Run node ${scriptsPath}/live-status.mjs and tell the user what the session resolved to.`;
+    }
+    return `${prefix}Accept failed: ${result.error || 'unknown error'}. Source was not touched; do not hand-edit. Run node ${scriptsPath}/live-status.mjs before continuing.`;
+  }
+  return `${prefix}No mechanical accept result; read ${result.file || 'the session source file'}, find the impeccable markers, and finish the merge by hand. Poll again after.`;
+}
+
+/** Boot instructions attached to live.mjs's success payload. */
+export function bootInstructions({ scriptsPath = '{{scripts_path}}' } = {}) {
+  return `Open the app URL that serves a pageFiles entry (never serverPort; that is the helper). Then start the poll loop per your harness policy in live.md and re-run ${pollCmd(scriptsPath)} immediately after every event or reply. Every event carries _instructions: follow them; they are the authoritative next step with real ids and paths filled in. A poll that is running is a poll you are SERVICING: never announce you are waiting and idle your turn; stay on the exec session until it returns an event, and never end a turn while a poll is outstanding.`;
+}

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

@@ -0,0 +1,508 @@
+/**
+ * Live root resolution: the single place that decides which directories a live
+ * session operates on. Every live entry script resolves this once at startup
+ * (see enterLiveRoot) instead of trusting its ambient cwd, which is how a
+ * `cd` used to silently fork the whole system into a second, empty project.
+ *
+ * Four distinct roots travel together as one manifest:
+ *
+ *   appRoot     what the dev server serves; where live session state,
+ *               injected adapters, and preview modules live.
+ *   repoRoot    the git boundary (falls back to appRoot outside git).
+ *   contextRoot the nearest directory from appRoot up to repoRoot carrying
+ *               PRODUCT.md / DESIGN.md (canonical spot or a fallback dir).
+ *   sessionRoot <appRoot>/.impeccable/live — durable live state.
+ *
+ * appRoot detection keys on dev-server config presence (vite/svelte/next/
+ * astro/nuxt/... config files), not on monorepo brand markers. A nested
+ * website/ with vite.config.js wins over a repo root that merely has a
+ * package.json. Workspace declarations are one input, not the gatekeeper.
+ *
+ * The resolved manifest is persisted at <appRoot>/.impeccable/live/roots.json
+ * plus a pointer at <repoRoot>/.impeccable/live/app-root.json when the two
+ * differ, so a helper invoked from anywhere inside the repo finds the same
+ * roots the boot decided on. When several apps in one repo run live, the
+ * pointer follows the most recent boot; per-app roots.json files stay put.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { resolveProjectRoot } from '../context.mjs';
+
+const ROOTS_MANIFEST_VERSION = 1;
+const ROOTS_FILE = 'roots.json';
+const POINTER_FILE = 'app-root.json';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const CONTEXT_FALLBACK_DIRS = ['.agents/context', 'docs'];
+
+// Presence of any of these marks a directory as a dev-served app root.
+const DEV_CONFIG_MARKERS = [
+  'vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs',
+  'svelte.config.js', 'svelte.config.mjs', 'svelte.config.ts',
+  'next.config.js', 'next.config.mjs', 'next.config.ts',
+  'astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs',
+  'nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs',
+  'remix.config.js', 'react-router.config.ts',
+  'angular.json',
+  'webpack.config.js', 'webpack.config.ts',
+];
+
+const CANDIDATE_SCAN_IGNORED = new Set([
+  'node_modules', '.git', 'dist', 'build', 'coverage', 'vendor', 'vendors',
+  '.next', '.nuxt', '.svelte-kit', '.astro', '.turbo', '.cache', '.vercel',
+]);
+const CANDIDATE_SCAN_DEPTH = 2;
+
+function exists(p) {
+  try { fs.statSync(p); return true; } catch { return false; }
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function firstExisting(dir, names) {
+  for (const name of names) {
+    const abs = path.join(dir, name);
+    if (exists(abs)) return abs;
+  }
+  return null;
+}
+
+function hasDevConfig(dir) {
+  if (DEV_CONFIG_MARKERS.some((name) => exists(path.join(dir, name)))) return true;
+  // A plain Vite app can run with zero config: index.html + package.json.
+  return exists(path.join(dir, 'index.html')) && exists(path.join(dir, 'package.json'));
+}
+
+function isAppRoot(dir) {
+  // A directory already configured for live IS an app root, dev config or not
+  // (plain static multi-page projects have no bundler config).
+  return hasDevConfig(dir) || exists(path.join(dir, '.impeccable', 'live', 'config.json'));
+}
+
+function findContextFile(dir, names) {
+  const direct = firstExisting(dir, names);
+  if (direct) return direct;
+  for (const rel of CONTEXT_FALLBACK_DIRS) {
+    const nested = firstExisting(path.join(dir, rel), names);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+export function findGitRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const home = path.resolve(os.homedir());
+  while (true) {
+    if (dir === home) return null;
+    if (exists(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function walkUp(startDir, upperBound, visit) {
+  let dir = path.resolve(startDir);
+  const stop = path.resolve(upperBound);
+  const home = path.resolve(os.homedir());
+  while (true) {
+    if (dir === home) return null;
+    const hit = visit(dir);
+    if (hit) return hit;
+    if (dir === stop) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function insideOrEqual(candidate, root) {
+  const rel = path.relative(path.resolve(root), path.resolve(candidate));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Scan downward (bounded depth) for directories carrying a dev-server config.
+ * Used when live boots from a directory that is not itself an app root and no
+ * --target narrows the choice: one candidate is auto-picked, several become a
+ * selection prompt.
+ */
+export function discoverAppCandidates(rootDir, depth = CANDIDATE_SCAN_DEPTH) {
+  const found = [];
+  const scan = (dir, remaining) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || CANDIDATE_SCAN_IGNORED.has(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      // Same criterion as the upward walk (isAppRoot): a live-configured
+      // plain-static site with no bundler markers is still an app, and
+      // missing it here would silently fall back to the wrong root.
+      if (isAppRoot(abs)) {
+        found.push(abs);
+        continue; // nested apps below an app root are that app's business
+      }
+      if (remaining > 1) scan(abs, remaining - 1);
+    }
+  };
+  scan(path.resolve(rootDir), depth);
+  return found.sort();
+}
+
+/**
+ * Fresh root resolution. Never reads a persisted manifest.
+ *
+ * Returns { manifest } on success or { selection } when several candidate
+ * apps exist and nothing disambiguates.
+ */
+export function resolveRoots({ cwd = process.cwd(), targetPath = null } = {}) {
+  const absCwd = path.resolve(cwd);
+  const absTarget = targetPath
+    ? (path.isAbsolute(targetPath) ? targetPath : path.resolve(absCwd, targetPath))
+    : null;
+  const targetDir = absTarget
+    ? (isDir(absTarget) ? absTarget : path.dirname(absTarget))
+    : absCwd;
+
+  // The walk bound must be an ancestor of the target: a git root found from
+  // the CWD is only usable when the target actually lives inside it,
+  // otherwise the walk would climb out of both trees.
+  const targetGitRoot = findGitRoot(targetDir);
+  const cwdGitRoot = targetGitRoot ? null : findGitRoot(absCwd);
+  const repoRoot = targetGitRoot
+    || (cwdGitRoot && insideOrEqual(targetDir, cwdGitRoot) ? cwdGitRoot : null);
+  // Without a git boundary, never ascend above the starting directory: the
+  // filesystem above an unversioned project is not ours to interpret.
+  const upperBound = repoRoot || targetDir;
+
+  // The workspace-aware legacy resolution (context.mjs) still decides two
+  // things: the fallback when no app marker exists, and how far the marker
+  // walk may ascend when an explicit target selected a workspace child. A
+  // root-level live config must never shadow a child the target picked.
+  const legacyRoot = resolveProjectRoot(absCwd, absTarget ? { targetPath: absTarget } : {});
+  const markerBound = absTarget && insideOrEqual(targetDir, legacyRoot) && insideOrEqual(legacyRoot, upperBound)
+    ? legacyRoot
+    : upperBound;
+
+  let appRoot = walkUp(targetDir, markerBound, (dir) => (isAppRoot(dir) ? dir : null));
+  let resolvedFrom = appRoot
+    ? (absTarget ? `target:${path.relative(absCwd, absTarget) || '.'}` : 'cwd')
+    : null;
+
+  if (!appRoot && !absTarget) {
+    const candidates = discoverAppCandidates(absCwd);
+    if (candidates.length === 1) {
+      appRoot = candidates[0];
+      resolvedFrom = `candidate:${path.relative(absCwd, appRoot)}`;
+    } else if (candidates.length > 1) {
+      return {
+        selection: {
+          candidates: candidates.map((abs) => ({
+            name: path.basename(abs),
+            path: path.relative(absCwd, abs).split(path.sep).join('/'),
+          })),
+        },
+      };
+    }
+  }
+
+  if (!appRoot) {
+    // No app marker anywhere: defer to the workspace-aware legacy resolution
+    // (workspace child for a targeted monorepo path, cwd otherwise). Never
+    // adopt an arbitrary ancestor just because it has a package.json, and
+    // never adopt a root that does not even contain the target.
+    appRoot = insideOrEqual(targetDir, legacyRoot) ? legacyRoot : targetDir;
+    resolvedFrom = 'fallback';
+  }
+
+  const effectiveRepoRoot = repoRoot && insideOrEqual(appRoot, repoRoot) ? repoRoot : appRoot;
+
+  // Each context file resolves independently: a child app may carry its own
+  // PRODUCT.md while inheriting DESIGN.md from the repo root (or vice versa).
+  const productPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, PRODUCT_NAMES));
+  const designPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, DESIGN_NAMES));
+  const contextRoot = productPath
+    ? path.dirname(productPath)
+    : designPath
+      ? path.dirname(designPath)
+      : null;
+
+  return {
+    manifest: {
+      version: ROOTS_MANIFEST_VERSION,
+      appRoot,
+      repoRoot: effectiveRepoRoot,
+      contextRoot,
+      sessionRoot: path.join(appRoot, '.impeccable', 'live'),
+      productPath,
+      designPath,
+      resolvedFrom,
+    },
+  };
+}
+
+function rootsFilePath(appRoot) {
+  return path.join(appRoot, '.impeccable', 'live', ROOTS_FILE);
+}
+
+function pointerFilePath(repoRoot) {
+  return path.join(repoRoot, '.impeccable', 'live', POINTER_FILE);
+}
+
+export function writeRootsManifest(manifest) {
+  const file = rootsFilePath(manifest.appRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
+  if (path.resolve(manifest.repoRoot) !== path.resolve(manifest.appRoot)) {
+    const pointer = pointerFilePath(manifest.repoRoot);
+    fs.mkdirSync(path.dirname(pointer), { recursive: true });
+    // The pointer records EVERY app that has booted live in this repo, most
+    // recent first. A single last-boot-wins value made a helper run from the
+    // repo root silently target whichever app booted last, even while an
+    // earlier app's session was the one still live.
+    const entries = readPointerEntries(manifest.repoRoot)
+      .filter((entry) => path.resolve(entry.appRoot) !== path.resolve(manifest.appRoot));
+    entries.unshift({ appRoot: manifest.appRoot, bootedAt: new Date().toISOString() });
+    fs.writeFileSync(pointer, JSON.stringify({ version: 2, appRoots: entries }));
+  }
+  return file;
+}
+
+function readPointerEntries(repoRoot) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(pointerFilePath(repoRoot), 'utf-8'));
+    if (Array.isArray(raw?.appRoots)) {
+      return raw.appRoots.filter((entry) => entry && typeof entry.appRoot === 'string');
+    }
+    // v1 shape: a single { appRoot } value.
+    if (raw && typeof raw.appRoot === 'string') return [{ appRoot: raw.appRoot }];
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * True when the app's live helper server is recorded and its pid is alive.
+ * A liveness signal alone misclassifies a REUSED pid (helper died without
+ * removing server.json, the OS handed the pid to something else), so the
+ * process's command line must also look like a node process; that removes
+ * reuse by arbitrary processes. A pid reused by another node process remains
+ * a residual false positive, which the multi-app warning and --target
+ * escape hatch cover.
+ */
+function hasLiveServer(appRoot) {
+  let pid;
+  let port;
+  let token;
+  try {
+    const info = JSON.parse(fs.readFileSync(path.join(appRoot, '.impeccable', 'live', 'server.json'), 'utf-8'));
+    if (!info || typeof info.pid !== 'number') return false;
+    pid = info.pid;
+    port = Number(info.port);
+    token = typeof info.token === 'string' ? info.token : null;
+    process.kill(pid, 0);
+  } catch (err) {
+    // EPERM: the process exists but is not signalable by this user.
+    if (err?.code !== 'EPERM') return false;
+  }
+  // Liveness alone misclassifies a REUSED pid, and a bare TCP connect
+  // misclassifies a coincidental listener on a reused port. The decisive
+  // signal is IDENTITY: the helper answers its authenticated /status
+  // endpoint with the token server.json records; nothing else on that port
+  // can. The probe is a spawned node one-liner so it works identically on
+  // every platform.
+  if (Number.isInteger(port) && port > 0 && token) {
+    try {
+      execFileSync(process.execPath, ['-e', [
+        "const req = require('node:http').get({ host: '127.0.0.1', port: Number(process.argv[1]), path: '/status?token=' + encodeURIComponent(process.argv[2]), timeout: 1200 }, (res) => { res.resume(); process.exit(res.statusCode === 200 ? 0 : 1); });",
+        "req.on('timeout', () => { req.destroy(); process.exit(1); });",
+        "req.on('error', () => process.exit(1));",
+      ].join(''), String(port), token], { timeout: 4000, stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  // Every server.json this codebase has ever written records port + token
+  // (see writeLiveServerInfo). A record without them is malformed or foreign
+  // and cannot be authenticated, so it does not count as a live helper;
+  // resolution falls to the durable-session tier, which is the correct
+  // recovery path for a stopped or crashed helper anyway.
+  return false;
+}
+
+const TERMINAL_SESSION_PHASES = new Set(['completed', 'discarded']);
+
+/**
+ * True when the app's durable session store holds a session that is not
+ * terminal. With every helper server stopped, this is what distinguishes
+ * "the app whose interrupted session the user is trying to recover" from an
+ * app that merely booted more recently.
+ */
+function hasActiveDurableSession(appRoot) {
+  const dir = path.join(appRoot, '.impeccable', 'live', 'sessions');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return false;
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.snapshot.json')) continue;
+    try {
+      const snapshot = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+      if (snapshot?.phase && !TERMINAL_SESSION_PHASES.has(snapshot.phase)) return true;
+    } catch { /* skip unreadable snapshots */ }
+  }
+  return false;
+}
+
+function readManifestAt(appRoot) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(rootsFilePath(appRoot), 'utf-8'));
+    if (!raw || typeof raw.appRoot !== 'string') return null;
+    // A manifest is only trusted where it claims to live; anything else is a
+    // copied or stale file.
+    if (path.resolve(raw.appRoot) !== path.resolve(appRoot)) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the roots for the live session governing `cwd`, preferring a
+ * persisted manifest (written by the boot) over fresh detection:
+ *
+ *   1. Walk up from cwd looking for .impeccable/live/roots.json.
+ *   2. At the git root, follow .impeccable/live/app-root.json to the app.
+ *   3. Fresh resolveRoots().
+ *
+ * Fresh results are NOT persisted here; only the boot (live.mjs / server
+ * startup) writes manifests, so ad-hoc helper invocations cannot mint
+ * conflicting truth.
+ */
+export function resolveLiveRoots(cwd = process.cwd(), { targetPath = null } = {}) {
+  const absCwd = path.resolve(cwd);
+
+  if (!targetPath) {
+    const persisted = walkUp(absCwd, findGitRoot(absCwd) || absCwd, (dir) => readManifestAt(dir));
+    if (persisted) return { manifest: persisted, source: 'persisted' };
+
+    const gitRoot = findGitRoot(absCwd);
+    if (gitRoot) {
+      // Several apps in one repo may have booted live. Preference order:
+      // a running helper server, then an app whose durable store still holds
+      // a non-terminal session (the stopped session the user is recovering),
+      // then the most recent boot. A stale pointer entry must never redirect
+      // status/poll/accept onto the wrong app's session store.
+      const candidates = readPointerEntries(gitRoot)
+        .map((entry) => readManifestAt(entry.appRoot))
+        .filter(Boolean);
+      if (candidates.length > 0) {
+        const liveApps = candidates.filter((manifest) => hasLiveServer(manifest.appRoot));
+        const recoveringApps = liveApps.length > 0
+          ? liveApps
+          : candidates.filter((manifest) => hasActiveDurableSession(manifest.appRoot));
+        const tier = recoveringApps.length > 0 ? recoveringApps : candidates;
+        // Multiple apps qualifying at the same tier is inherent ambiguity:
+        // intent is unknowable from the repo root. The choice stays
+        // deterministic (most recent boot first), but it must be LOUD, not
+        // silent, so the agent can re-anchor when it meant the other app.
+        if (tier.length > 1) {
+          const chosen = tier[0].appRoot;
+          const others = tier.slice(1).map((manifest) => manifest.appRoot).join(', ');
+          process.stderr.write(
+            `[impeccable live] Multiple apps in this repo have live state; using ${chosen}. `
+            + `Other candidate(s): ${others}. Run from the app directory (or pass --target) to address a specific app.\n`,
+          );
+        }
+        return { manifest: tier[0], source: 'pointer' };
+      }
+    }
+  }
+
+  const fresh = resolveRoots({ cwd: absCwd, targetPath });
+  if (fresh.selection) return { selection: fresh.selection, source: 'fresh' };
+  return { manifest: fresh.manifest, source: 'fresh' };
+}
+
+/**
+ * Consume a `--target <path>` / `--target=<path>` pair from an argv array,
+ * returning the value and removing the tokens so downstream flag parsers
+ * (which do not know the option) never see them.
+ */
+export function consumeTargetArg(argv = process.argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--target') {
+      const value = argv[i + 1];
+      // A --target with no usable value must not degrade into implicit root
+      // selection: these helpers mutate session state, and "the most recent
+      // app" is exactly what the caller was trying NOT to get.
+      if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
+        throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
+      }
+      argv.splice(i, 2);
+      return value;
+    }
+    if (typeof arg === 'string' && arg.startsWith('--target=')) {
+      const value = arg.slice('--target='.length);
+      if (value === '') {
+        throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
+      }
+      argv.splice(i, 1);
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Entry-point guard for live CLI scripts: resolve the governing roots and
+ * make appRoot the process cwd so every downstream path derivation agrees
+ * with the boot. An explicit `--target <path>` on the helper's command line
+ * overrides pointer resolution, which is what disambiguates a repo with
+ * several live apps (the multi-app warning names this escape hatch, so it
+ * has to actually work on every helper). Returns the manifest. On selection
+ * ambiguity it stays in the current directory (the boot flow handles
+ * prompting); a malformed --target exits with an error instead of silently
+ * falling back to implicit selection, which could mutate the wrong app.
+ */
+export function enterLiveRoot(cwd = process.cwd()) {
+  let targetPath;
+  try {
+    targetPath = consumeTargetArg(process.argv);
+  } catch (err) {
+    console.error(`[impeccable live] ${err.message}`);
+    process.exit(1);
+  }
+  const resolved = resolveLiveRoots(cwd, targetPath ? { targetPath } : {});
+  if (!resolved.manifest) return null;
+  const appRoot = resolved.manifest.appRoot;
+  if (path.resolve(cwd) !== path.resolve(appRoot)) {
+    // Failing to land on the resolved appRoot must be fatal: a helper that
+    // silently keeps its ambient cwd derives server, session, and source
+    // paths from a different project and mutates the wrong state. A manifest
+    // pointing at a deleted directory is stale ambient truth, not a reason
+    // to guess.
+    if (!isDir(appRoot)) {
+      console.error(`[impeccable live] resolved app root does not exist: ${appRoot} (stale roots manifest? re-run the live boot, or pass --target <path>)`);
+      process.exit(1);
+    }
+    try {
+      process.chdir(appRoot);
+    } catch (err) {
+      console.error(`[impeccable live] could not enter app root ${appRoot}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+  return resolved.manifest;
+}

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

@@ -1,26 +1,40 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getLegacyLiveSessionsDir, getLiveSessionsDir, safeSessionId } from '../lib/impeccable-paths.mjs';
+import { COMPLETED_SESSION_PHASES, GENERATION_FENCED_SESSION_PHASES } from './vocabulary.mjs';
 
-const COMPLETED_PHASES = new Set(['completed', 'discarded']);
-export const GENERATION_FENCED_PHASES = new Set([
-  'accept_requested',
-  'discard_requested',
-  'carbonize_required',
-  'completed',
-  'discarded',
-]);
+const COMPLETED_PHASES = new Set(COMPLETED_SESSION_PHASES);
+export const GENERATION_FENCED_PHASES = new Set(GENERATION_FENCED_SESSION_PHASES);
+
+// The snapshot file carries two bookkeeping fields the snapshot itself does not
+// own: how large the journal was when the snapshot was written, and the next
+// sequence number. Both are stripped before a snapshot is handed to a caller.
+// The byte count is what makes a cached snapshot verifiable — the journal is
+// append-only, so a matching size means no event has landed since.
+const META_JOURNAL_BYTES = '__journalBytes';
+const META_NEXT_SEQ = '__nextSeq';
+
+// TODO(revision-unification): `checkpointRevision`, `browserCheckpointRevision`,
+// and `publicationCheckpointRevision` are three counters for two domains.
+// `checkpointRevision` is a compatibility mirror of the browser counter kept for
+// older readers. Collapsing them means changing what a resumed browser compares
+// its local revision against, so it belongs in a pass that owns resume ordering,
+// not in a caching change.
 
 export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
   const rootDir = getLiveSessionsDir(cwd);
   const legacyRootDir = getLegacyLiveSessionsDir(cwd);
   fs.mkdirSync(rootDir, { recursive: true });
 
-  // No snapshot cache on purpose: appendEvent and getSnapshot both rebuild from
-  // the journal so sequence numbers and phase fences never come from a stale
-  // in-memory copy when the publisher/complete helpers append from another
-  // process. A cache written but never read would grow per session for the
-  // lifetime of the server without ever saving a rebuild.
+  // Derived state per session, keyed by what the journal looked like when it was
+  // derived. Publisher/complete helpers append from other processes, so the key
+  // is the journal's own (path, size, mtime) rather than a trusted local write
+  // count: an append this process did not make invalidates the entry and the
+  // next read replays. Without the cache every append and every read replayed
+  // the whole journal, which made a long session quadratic in its own length.
+  /** @type {Map<string, { snapshot: object, nextSeq: number, journalPath: string, size: number, mtimeMs: number }>} */
+  const derived = new Map();
+
   function getReadableJournalPath(id) {
     const primary = getJournalPath(rootDir, id);
     if (fs.existsSync(primary)) return primary;
@@ -29,42 +43,116 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
     return primary;
   }
 
+  /**
+   * The current derived state for a session, from the in-memory cache when the
+   * journal has not moved, from the snapshot file when that file is provably
+   * current, and from a full replay otherwise.
+   */
+  function readState(id, { allowSnapshotFile = true } = {}) {
+    const journalPath = getReadableJournalPath(id);
+    const stat = statOrNull(journalPath);
+    const size = stat ? stat.size : -1;
+    const mtimeMs = stat ? stat.mtimeMs : -1;
+
+    const cached = derived.get(id);
+    if (cached && cached.journalPath === journalPath && cached.size === size && cached.mtimeMs === mtimeMs) {
+      return cached;
+    }
+
+    if (allowSnapshotFile && stat) {
+      const hydrated = readSnapshotFile(getSnapshotPath(rootDir, id), id, size);
+      if (hydrated) {
+        const entry = { ...hydrated, journalPath, size, mtimeMs };
+        derived.set(id, entry);
+        return entry;
+      }
+    }
+
+    const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
+    const entry = { snapshot: rebuilt.snapshot, nextSeq: rebuilt.nextSeq, journalPath, size, mtimeMs };
+    derived.set(id, entry);
+    return entry;
+  }
+
+  function persist(id, snapshot, nextSeq) {
+    const snapshotPath = getSnapshotPath(rootDir, id);
+    const journalPath = getReadableJournalPath(id);
+    const stat = statOrNull(journalPath);
+    writeSnapshot(snapshotPath, snapshot, { journalBytes: stat ? stat.size : -1, nextSeq });
+    derived.set(id, {
+      snapshot,
+      nextSeq,
+      journalPath,
+      size: stat ? stat.size : -1,
+      mtimeMs: stat ? stat.mtimeMs : -1,
+    });
+  }
+
   return {
     rootDir,
     legacyRootDir,
     appendEvent(event) {
       const normalized = normalizeEvent(event, sessionId);
       const journalPath = getJournalPath(rootDir, normalized.id);
-      const snapshotPath = getSnapshotPath(rootDir, normalized.id);
       const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
       if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
         fs.copyFileSync(legacyJournalPath, journalPath);
+        // The readable path just moved from legacy to primary; anything derived
+        // against the old path describes a file this session no longer reads.
+        derived.delete(normalized.id);
       }
-      // Publisher/complete helpers can append from a separate process while
-      // the server is alive. Rebuild here so sequence numbers and phase
-      // fences never come from a stale in-memory cache.
-      const prior = rebuildSnapshotFromJournal(getReadableJournalPath(normalized.id), normalized.id);
-      const seq = prior.nextSeq;
+      // Reuse the derived state when the journal has not changed under us, and
+      // apply the new event on top of it. Correctness still comes from the
+      // journal: any append from another process invalidates the entry above
+      // and this replays before writing, so sequence numbers and phase fences
+      // are never taken from a stale copy.
+      const prior = readState(normalized.id);
       const entry = {
-        seq,
+        seq: prior.nextSeq,
         id: normalized.id,
         type: normalized.type,
         ts: new Date().toISOString(),
         event: normalized,
       };
       fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
-      const next = applyEvent(prior.snapshot, entry, prior.diagnostics);
-      writeSnapshot(snapshotPath, next);
+      const next = applyEvent(prior.snapshot, entry);
+      persist(normalized.id, next, prior.nextSeq + 1);
       return next;
     },
+    /**
+     * True when a journal exists for the id in either root. appendEvent
+     * CREATES a journal for any id it is handed, so callers that should only
+     * ever touch existing sessions (browser checkpoints, mount acks) check
+     * here first — otherwise a stale id from another project's browser
+     * storage materializes a ghost session in this store.
+     */
+    has(id) {
+      if (!id || typeof id !== 'string') return false;
+      return fs.existsSync(getJournalPath(rootDir, id))
+        || fs.existsSync(getJournalPath(legacyRootDir, id));
+    },
+    /**
+     * Read-only. `live-status` and `live-resume` call this against a session a
+     * running server owns; writing the snapshot file here made every read a
+     * write and let a reader's replay of a half-written journal land on disk.
+     * Snapshot files are written by appendEvent and by flush().
+     */
     getSnapshot(id = sessionId, opts = {}) {
       if (!id) throw new Error('session id required');
-      const journalPath = getReadableJournalPath(id);
-      const snapshotPath = getSnapshotPath(rootDir, id);
-      const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
-      writeSnapshot(snapshotPath, rebuilt.snapshot);
-      if (!opts.includeCompleted && COMPLETED_PHASES.has(rebuilt.snapshot.phase)) return null;
-      return rebuilt.snapshot;
+      const { snapshot } = readState(id);
+      if (!opts.includeCompleted && COMPLETED_PHASES.has(snapshot.phase)) return null;
+      return snapshot;
+    },
+    /**
+     * Write the snapshot file for a session without appending an event. The
+     * durable truth is the journal, so this only refreshes the read cache other
+     * processes use; callers that need the state itself should use getSnapshot.
+     */
+    flush(id = sessionId) {
+      if (!id) throw new Error('session id required');
+      const state = readState(id, { allowSnapshotFile: false });
+      persist(id, state.snapshot, state.nextSeq);
+      return state.snapshot;
     },
     listActiveSessions() {
       const ids = new Set();
@@ -74,6 +162,9 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
           if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
         }
       }
+      // Each id goes through readState, so a session whose journal has not moved
+      // since it was last derived costs a stat and nothing more. The server calls
+      // this on every /status and on every SSE connect.
       return [...ids]
         .sort()
         .map((id) => this.getSnapshot(id))
@@ -82,6 +173,39 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
   };
 }
 
+function statOrNull(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hydrate derived state from a snapshot file, but only when it provably
+ * describes the journal as it stands right now. Anything short of an exact byte
+ * match on an append-only file means events landed after the snapshot was
+ * written, and the caller replays instead.
+ */
+function readSnapshotFile(snapshotPath, id, journalBytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  if (parsed[META_JOURNAL_BYTES] !== journalBytes) return null;
+  if (!Number.isInteger(parsed[META_NEXT_SEQ])) return null;
+  const nextSeq = parsed[META_NEXT_SEQ];
+  delete parsed[META_JOURNAL_BYTES];
+  delete parsed[META_NEXT_SEQ];
+  // The journal owns identity; a snapshot file copied between session ids is
+  // not a reason to answer with the wrong id.
+  if (parsed.id !== id) return null;
+  return { snapshot: { ...baseSnapshot(id), ...parsed }, nextSeq };
+}
+
 function normalizeEvent(event, fallbackId) {
   if (!event || typeof event !== 'object') throw new Error('event object required');
   const id = event.id || fallbackId;
@@ -127,11 +251,37 @@ function baseSnapshot(id) {
     generationCanceledAt: null,
     cancelReason: null,
     annotationArtifacts: [],
+    // Render truth. `arrivedVariants` says what the agent published; these say
+    // what the browser actually got on screen. They are kept alongside the
+    // published counters rather than replacing them so older readers keep
+    // working, but they are the only fields that answer "did the user ever see
+    // a variant".
+    mountedVariants: [],
+    mountFailures: [],
+    renderState: null,
     diagnostics: [],
     updatedAt: null,
   };
 }
 
+// How many mount failures a session keeps. The card in the browser shows the
+// newest one; the agent needs enough history to spot a variant that fails
+// every republish, not the whole retry storm.
+const MOUNT_FAILURE_HISTORY = 5;
+
+/**
+ * `pending` = the agent published and nothing has acked yet, `mounted` = at
+ * least one variant reached the DOM, `failed` = the browser reported failures
+ * and nothing ever mounted. A single success outranks any number of failures:
+ * the user is looking at something.
+ */
+function deriveRenderState(snapshot) {
+  if (snapshot.mountedVariants.length > 0) return 'mounted';
+  if (snapshot.mountFailures.length > 0) return 'failed';
+  if (snapshot.generationCompletedAt) return 'pending';
+  return null;
+}
+
 function rebuildSnapshotFromJournal(journalPath, id) {
   let snapshot = baseSnapshot(id);
   const diagnostics = [];
@@ -159,7 +309,7 @@ function rebuildSnapshotFromJournal(journalPath, id) {
   return { snapshot, diagnostics, nextSeq };
 }
 
-function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
+function applyEvent(snapshot, entry) {
   const event = entry.event || entry;
   const next = {
     ...snapshot,
@@ -168,14 +318,13 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
     generationTimings: { ...(snapshot.generationTimings || {}) },
     variantPlan: snapshot.variantPlan || null,
     annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
+    mountedVariants: [...(snapshot.mountedVariants || [])],
+    mountFailures: [...(snapshot.mountFailures || [])],
+    renderState: snapshot.renderState ?? null,
     diagnostics: [...(snapshot.diagnostics || [])],
     updatedAt: entry.ts || new Date().toISOString(),
   };
 
-  if (inheritedDiagnostics.length && next.diagnostics.length === 0) {
-    next.diagnostics = [...inheritedDiagnostics];
-  }
-
   switch (event.type) {
     case 'generate':
       next.phase = 'generate_requested';
@@ -184,6 +333,11 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
       next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
       next.pendingEvent = toPendingEvent(event);
       next.variantPlan = null;
+      // A new cycle publishes new files: everything the browser told us about
+      // the previous batch is now about modules that no longer exist.
+      next.mountedVariants = [];
+      next.mountFailures = [];
+      next.renderState = null;
       if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
       break;
     case 'variant_plan':
@@ -238,7 +392,45 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
           message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
         });
       }
+      next.renderState = deriveRenderState(next);
       break;
+    case 'variant_mounted': {
+      const variant = Number(event.variant);
+      if (!Number.isInteger(variant) || variant < 1) {
+        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
+        break;
+      }
+      if (!next.mountedVariants.includes(variant)) {
+        next.mountedVariants = [...next.mountedVariants, variant].sort((a, b) => a - b);
+      }
+      next.renderState = deriveRenderState(next);
+      break;
+    }
+    case 'variant_mount_failed': {
+      const variant = Number(event.variant);
+      if (!Number.isInteger(variant) || variant < 1) {
+        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
+        break;
+      }
+      next.mountFailures = [
+        ...next.mountFailures,
+        {
+          variant,
+          url: typeof event.url === 'string' ? event.url : null,
+          error: typeof event.error === 'string' ? event.error : null,
+          at: event.at ?? (Date.parse(entry.ts || '') || Date.now()),
+        },
+      ].slice(-MOUNT_FAILURE_HISTORY);
+      next.renderState = deriveRenderState(next);
+      // The failure needs an agent reply, so it must survive a helper
+      // restart the same way a generate does. Never clobber a still-pending
+      // generate: a progressive publish can fail an early mount while the
+      // generate event itself is still leased.
+      if (!next.pendingEvent) {
+        next.pendingEvent = toPendingEvent(event);
+      }
+      break;
+    }
     case 'checkpoint':
       if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
         next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
@@ -361,6 +553,11 @@ function upsertArtifact(artifacts, artifact) {
   }
 }
 
-function writeSnapshot(snapshotPath, snapshot) {
-  fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2) + '\n');
+function writeSnapshot(snapshotPath, snapshot, meta) {
+  const payload = {
+    ...snapshot,
+    [META_JOURNAL_BYTES]: meta?.journalBytes ?? -1,
+    [META_NEXT_SEQ]: meta?.nextSeq ?? 1,
+  };
+  fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2) + '\n');
 }

.agents/skills/impeccable/scripts/live/svelte-ast.mjs

@@ -0,0 +1,961 @@
+/**
+ * AST-based Svelte scaffolding for live component previews.
+ *
+ * The scaffolder turns the selected block of a route's markup into a detached
+ * preview component whose dynamic values arrive as props. The old
+ * implementation matched `{...}` with a regex, which flattened control-flow
+ * blocks ({#each}, {#if}) into scalar text props and shipped structurally
+ * wrong previews. This module uses the app's own svelte compiler
+ * (parse with modern: true) and replaces only expressions that are FREE,
+ * i.e. reference identifiers not bound by an enclosing template scope:
+ *
+ *   {#each stages as stage, i}     stages  -> collection prop (array)
+ *     <span>{stage.label}</span>   bound   -> left verbatim
+ *   {/each}
+ *   <p>{footerNote}</p>            free    -> text prop (string)
+ *
+ * Constructs that cannot work in a detached component (component tags whose
+ * imports live in the route file, bind:/use: directives, await blocks,
+ * render tags) mark the analysis unsupported; the caller falls back to
+ * source-preview mode, which keeps the markup inside the route file where
+ * those references still resolve. A wrong preview is worse than a plain one.
+ *
+ * The compiler is resolved from the APP's node_modules, never bundled: the
+ * preview must be parsed by the same svelte version that will compile it.
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const HANDLER_ATTR_RE = /^on[a-z]/;
+
+/**
+ * Resolve the app's svelte compiler synchronously (svelte 5 ships a CJS
+ * compiler build, so createRequire works and the accept/scaffold pipeline
+ * stays synchronous). Returns { parse, compile, VERSION } or null.
+ */
+export function loadSvelteCompiler(appRoot) {
+  try {
+    const req = createRequire(path.join(appRoot, 'package.json'));
+    const mod = req('svelte/compiler');
+    if (typeof mod.parse !== 'function') return null;
+    const major = parseInt(String(mod.VERSION || '0'), 10);
+    if (major < 5) return null; // detached mount() previews are svelte 5 only
+    return { parse: mod.parse, compile: mod.compile, VERSION: mod.VERSION };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ESTree helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect the root identifiers an ESTree expression reads. Walks generically;
+ * skips non-computed member properties and non-computed/non-shorthand object
+ * keys, which are names, not references.
+ */
+export function collectRootIdentifiers(node, out = new Set()) {
+  if (!node || typeof node !== 'object') return out;
+  if (Array.isArray(node)) {
+    for (const item of node) collectRootIdentifiers(item, out);
+    return out;
+  }
+  switch (node.type) {
+    case 'Identifier':
+      out.add(node.name);
+      return out;
+    case 'MemberExpression':
+      collectRootIdentifiers(node.object, out);
+      if (node.computed) collectRootIdentifiers(node.property, out);
+      return out;
+    case 'Property':
+      if (node.computed) collectRootIdentifiers(node.key, out);
+      collectRootIdentifiers(node.value, out);
+      return out;
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression': {
+      // Params shadow outer names inside the body.
+      const bound = new Set();
+      for (const param of node.params || []) collectPatternNames(param, bound);
+      const inner = collectRootIdentifiers(node.body, new Set());
+      for (const name of inner) if (!bound.has(name)) out.add(name);
+      return out;
+    }
+    default: {
+      for (const key of Object.keys(node)) {
+        if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
+        collectRootIdentifiers(node[key], out);
+      }
+      return out;
+    }
+  }
+}
+
+/** Collect names bound by a destructuring pattern (each contexts, const tags). */
+export function collectPatternNames(pattern, out = new Set()) {
+  if (!pattern || typeof pattern !== 'object') return out;
+  switch (pattern.type) {
+    case 'Identifier':
+      out.add(pattern.name);
+      return out;
+    case 'ObjectPattern':
+      for (const prop of pattern.properties || []) {
+        if (prop.type === 'RestElement') collectPatternNames(prop.argument, out);
+        else collectPatternNames(prop.value, out);
+      }
+      return out;
+    case 'ArrayPattern':
+      for (const el of pattern.elements || []) if (el) collectPatternNames(el, out);
+      return out;
+    case 'AssignmentPattern':
+      collectPatternNames(pattern.left, out);
+      return out;
+    case 'RestElement':
+      collectPatternNames(pattern.argument, out);
+      return out;
+    default:
+      return out;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Template analysis
+// ---------------------------------------------------------------------------
+
+class Analysis {
+  constructor(source) {
+    this.source = source;
+    this.replacements = []; // { start, end, prop } source ranges to swap
+    this.contract = [];     // [{ prop, expr, kind, ... }]
+    this.byExpr = new Map(); // expr text -> contract entry
+    this.usedNames = new Set();
+    this.unsupported = null;
+  }
+
+  fail(reason) {
+    if (!this.unsupported) this.unsupported = reason;
+  }
+
+  propFor(exprText, kind, extra = {}) {
+    const existing = this.byExpr.get(exprText);
+    if (existing) return existing;
+    const base = derivePropName(exprText);
+    let name = base;
+    let n = 2;
+    while (this.usedNames.has(name)) name = `${base}${n++}`;
+    this.usedNames.add(name);
+    const entry = { prop: name, expr: exprText, kind, ...extra };
+    this.byExpr.set(exprText, entry);
+    this.contract.push(entry);
+    return entry;
+  }
+}
+
+// A derived prop name lands in `let { <name> } = $props()`; a reserved word
+// there is a syntax error the session only hits at import time.
+const RESERVED_PROP_NAMES = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+  'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+  'finally', 'for', 'function', 'if', 'implements', 'import', 'in',
+  'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private',
+  'protected', 'public', 'return', 'static', 'super', 'switch', 'this',
+  'throw', 'true', 'try', 'typeof', 'undefined', 'var', 'void', 'while',
+  'with', 'yield',
+]);
+
+export function derivePropName(expr) {
+  const tail = String(expr).match(/(?:\.|\[["']?)([A-Za-z_$][\w$]*)["']?\]?\s*$/);
+  const candidate = (tail && tail[1])
+    || (String(expr).match(/^([A-Za-z_$][\w$]*)$/) || [])[1]
+    || 'value';
+  return RESERVED_PROP_NAMES.has(candidate) ? `${candidate}Value` : candidate;
+}
+
+function exprText(source, node) {
+  return source.slice(node.start, node.end);
+}
+
+// Identifiers that resolve in ANY module scope. They are neither hydratable
+// props nor evidence of route coupling, so they count as neither free nor
+// bound: `{Math.round(x)}` must not mint a prop named `round`, and
+// `{fmt(stage.label)}` must not pass as global-only.
+const GLOBAL_IDENTIFIERS = new Set([
+  'Math', 'JSON', 'Date', 'Intl', 'Number', 'String', 'Boolean', 'Array',
+  'Object', 'Map', 'Set', 'Promise', 'RegExp', 'NaN', 'Infinity', 'undefined',
+  'isNaN', 'isFinite', 'parseInt', 'parseFloat', 'encodeURIComponent',
+  'decodeURIComponent', 'console', 'window', 'document', 'navigator',
+  'location', 'structuredClone', 'crypto',
+]);
+
+function classifyRoots(node, scopes) {
+  const roots = collectRootIdentifiers(node);
+  let bound = 0;
+  let free = 0;
+  for (const name of roots) {
+    if (GLOBAL_IDENTIFIERS.has(name)) continue;
+    if (scopes.some((scope) => scope.has(name))) bound++;
+    else free++;
+  }
+  return { bound, free };
+}
+
+function isFree(node, scopes) {
+  const { bound, free } = classifyRoots(node, scopes);
+  return free > 0 && bound === 0;
+}
+
+/**
+ * An expression mixing loop-bound and outer free identifiers (e.g.
+ * `{fmt(stage.label)}` where `fmt` lives in the route script) can neither
+ * become a prop (the bound part varies per item) nor survive detachment
+ * verbatim (the free name is undeclared in the preview and throws at mount,
+ * past the compile gate, because globals make it legal to the compiler).
+ * Source-preview mode is the only correct home for it.
+ */
+function failOnMixedExpression(node, scopes, analysis, source) {
+  const { bound, free } = classifyRoots(node, scopes);
+  if (bound > 0 && free > 0) {
+    analysis.fail(`expression mixing loop and outer identifiers ({${exprText(source, node).slice(0, 60)}}) requires source-preview mode`);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Analyze a parsed template fragment. `scopes` is a stack of Sets of bound
+ * names; the outermost call passes an empty stack.
+ */
+function analyzeFragment(fragment, analysis, scopes) {
+  if (!fragment || !Array.isArray(fragment.nodes)) return;
+  // ConstTag declarations bind for the whole fragment.
+  const fragmentScope = new Set();
+  const nextScopes = [...scopes, fragmentScope];
+  for (const node of fragment.nodes) {
+    if (node.type === 'ConstTag' && node.declaration) {
+      for (const decl of node.declaration.declarations || []) {
+        collectPatternNames(decl.id, fragmentScope);
+      }
+    }
+  }
+  for (const node of fragment.nodes) analyzeNode(node, analysis, nextScopes);
+}
+
+function analyzeNode(node, analysis, scopes) {
+  if (!node || analysis.unsupported) return;
+  switch (node.type) {
+    case 'Text':
+    case 'Comment':
+      return;
+    case 'ExpressionTag': {
+      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
+      if (isFree(node.expression, scopes)) {
+        const text = exprText(analysis.source, node.expression);
+        const entry = analysis.propFor(text, 'text');
+        // node.start/end include the braces; keep them, swap the inside.
+        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
+      }
+      return;
+    }
+    case 'HtmlTag': {
+      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
+      if (isFree(node.expression, scopes)) {
+        const text = exprText(analysis.source, node.expression);
+        const entry = analysis.propFor(text, 'raw');
+        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
+      }
+      return;
+    }
+    case 'ConstTag': {
+      // Its expression may read free names; leave them: the declaration
+      // travels with the markup and stays valid only if its inputs do.
+      if (node.declaration) {
+        for (const decl of node.declaration.declarations || []) {
+          if (decl.init && failOnMixedExpression(decl.init, scopes, analysis, analysis.source)) return;
+          if (decl.init && isFree(decl.init, scopes)) {
+            const text = exprText(analysis.source, decl.init);
+            const entry = analysis.propFor(text, 'text');
+            analysis.replacements.push({ start: decl.init.start, end: decl.init.end, prop: entry.prop });
+          }
+        }
+      }
+      return;
+    }
+    case 'EachBlock': {
+      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
+      if (isFree(node.expression, scopes)) {
+        const text = exprText(analysis.source, node.expression);
+        const item = describeEachItem(node, analysis.source);
+        // Keyed each: the key must evaluate to a distinct value per hydrated
+        // item or Svelte throws each_key_duplicate at mount. A key that is a
+        // plain member of the item (the common `(item.id)` shape) gets a
+        // synthetic per-index value injected by the browser (keyField).
+        // Anything else cannot be hydrated safely; source-preview mode keeps
+        // it correct.
+        if (node.key) {
+          const keyInfo = classifyEachKey(node);
+          if (keyInfo.unsupported) {
+            analysis.fail(keyInfo.unsupported);
+            return;
+          }
+          if (keyInfo.keyField) {
+            if (item.textSlots.some((slot) => slot.key === keyInfo.keyField)) {
+              // The key doubles as a displayed slot; a synthetic value would
+              // change visible text, and the displayed text may not be
+              // unique. Not previewable in a detached component.
+              analysis.fail('each key that is also a displayed field requires source-preview mode');
+              return;
+            }
+            item.keyField = keyInfo.keyField;
+          }
+        }
+        const entry = analysis.propFor(text, 'collection', { item });
+        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
+      }
+      const bound = new Set();
+      if (node.context) collectPatternNames(node.context, bound);
+      if (node.index) bound.add(node.index);
+      analyzeFragment(node.body, analysis, [...scopes, bound]);
+      if (node.fallback) analyzeFragment(node.fallback, analysis, scopes);
+      return;
+    }
+    case 'IfBlock': {
+      if (failOnMixedExpression(node.test, scopes, analysis, analysis.source)) return;
+      if (isFree(node.test, scopes)) {
+        const text = exprText(analysis.source, node.test);
+        // The browser hydrates a free condition from what the live page
+        // currently shows: when the consequent's root element is present
+        // under the picked element, the condition is on.
+        const entry = analysis.propFor(text, 'condition', {
+          probe: describeElementProbe(node.consequent),
+        });
+        analysis.replacements.push({ start: node.test.start, end: node.test.end, prop: entry.prop });
+      }
+      analyzeFragment(node.consequent, analysis, scopes);
+      if (node.alternate) analyzeFragment(node.alternate, analysis, scopes);
+      return;
+    }
+    case 'KeyBlock': {
+      if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
+      if (isFree(node.expression, scopes)) {
+        const text = exprText(analysis.source, node.expression);
+        const entry = analysis.propFor(text, 'text');
+        analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
+      }
+      analyzeFragment(node.fragment, analysis, scopes);
+      return;
+    }
+    case 'SnippetBlock': {
+      const bound = new Set();
+      for (const param of node.parameters || []) collectPatternNames(param, bound);
+      // The snippet's own name becomes available to render tags in this file.
+      analyzeFragment(node.body, analysis, [...scopes, bound]);
+      return;
+    }
+    case 'RegularElement':
+    case 'SlotElement':
+    case 'TitleElement': {
+      if (node.name === 'script') {
+        // An inline script inside the selected block carries route-scoped
+        // code; running it a second time from a detached preview is wrong.
+        analysis.fail('inline script element requires source-preview mode');
+        return;
+      }
+      analyzeAttributes(node, analysis, scopes);
+      if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
+      return;
+    }
+    case 'SvelteElement':
+    case 'SvelteFragment':
+    case 'SvelteBoundary': {
+      analyzeAttributes(node, analysis, scopes);
+      if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
+      return;
+    }
+    case 'Component':
+    case 'SvelteComponent':
+    case 'SvelteSelf':
+      // The component's import lives in the route file; a detached preview
+      // cannot resolve it. Source-preview mode keeps it working.
+      analysis.fail(`component tag <${node.name || 'Component'}> requires source-preview mode`);
+      return;
+    case 'RenderTag':
+      analysis.fail('render tag requires source-preview mode');
+      return;
+    case 'AwaitBlock':
+      analysis.fail('await block requires source-preview mode');
+      return;
+    case 'SvelteHead':
+    case 'SvelteWindow':
+    case 'SvelteDocument':
+    case 'SvelteBody':
+      analysis.fail(`${node.type} requires source-preview mode`);
+      return;
+    default: {
+      if (node.fragment) analyzeFragment(node.fragment, analysis, scopes);
+      return;
+    }
+  }
+}
+
+function analyzeAttributes(node, analysis, scopes) {
+  for (const attr of node.attributes || []) {
+    switch (attr.type) {
+      case 'Attribute': {
+        if (attr.value === true) break;
+        const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
+        for (const part of parts) {
+          if (!part || part.type !== 'ExpressionTag') continue;
+          if (failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) return;
+          if (!isFree(part.expression, scopes)) continue;
+          const text = exprText(analysis.source, part.expression);
+          const kind = HANDLER_ATTR_RE.test(attr.name) ? 'handler' : 'text';
+          const entry = analysis.propFor(text, kind);
+          analysis.replacements.push({ start: part.expression.start, end: part.expression.end, prop: entry.prop });
+        }
+        break;
+      }
+      case 'ClassDirective': {
+        const expr = attr.expression;
+        if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
+        if (expr && isFree(expr, scopes)) {
+          const text = exprText(analysis.source, expr);
+          // The directive's class name is literal, so the live DOM answers
+          // the condition directly: the class is either present or not.
+          const entry = analysis.propFor(text, 'condition', {
+            probe: { className: attr.name },
+          });
+          analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
+        }
+        break;
+      }
+      case 'StyleDirective': {
+        // Unlike ClassDirective, a style directive stores its value in
+        // attribute shape: `true` for the shorthand, else an array of parts.
+        const parts = attr.value === true ? [] : (Array.isArray(attr.value) ? attr.value : [attr.value]);
+        for (const part of parts) {
+          if (part?.type === 'ExpressionTag'
+              && failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) {
+            return;
+          }
+        }
+        const dynamic = parts.some((part) => part?.type === 'ExpressionTag' && isFree(part.expression, scopes));
+        const shorthandFree = attr.value === true && isFree({ type: 'Identifier', name: attr.name }, scopes);
+        if (dynamic || shorthandFree) {
+          // style:opacity={x} carries a css VALUE, not a boolean, and the
+          // computed value on the live element is not reliably recoverable in
+          // the shape the expression produced. A falsified style is worse
+          // than an HMR-resetting preview.
+          analysis.fail(`style:${attr.name} with a dynamic value requires source-preview mode`);
+        }
+        break;
+      }
+      case 'BindDirective':
+        analysis.fail(`bind:${attr.name} requires source-preview mode`);
+        return;
+      case 'UseDirective':
+        analysis.fail(`use:${attr.name} requires source-preview mode`);
+        return;
+      case 'AnimateDirective':
+      case 'TransitionDirective':
+        // Motion directives reference route-scoped or svelte/transition
+        // imports; a detached preview cannot resolve them.
+        analysis.fail(`${attr.type} requires source-preview mode`);
+        return;
+      case 'OnDirective': {
+        // Legacy on:click syntax; treat like handler attributes.
+        const expr = attr.expression;
+        if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
+        if (expr && isFree(expr, scopes)) {
+          const text = exprText(analysis.source, expr);
+          const entry = analysis.propFor(text, 'handler');
+          analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
+        }
+        break;
+      }
+      case 'SpreadAttribute':
+        analysis.fail('spread attribute requires source-preview mode');
+        return;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Describe the repeating item of an each block for browser-side hydration:
+ * the item's root element (tag + static classes, used to count live
+ * iterations) and the ordered text slots that reference loop bindings.
+ */
+function describeEachItem(node, source) {
+  const body = node.body;
+  const rootEl = (body?.nodes || []).find((n) => n.type === 'RegularElement');
+
+  const textSlots = [];
+  const staticTexts = [];
+  let nestedUnsupported = false;
+  const collectStatics = (fragment) => {
+    for (const child of fragment?.nodes || []) {
+      if (child.type === 'Text') {
+        const trimmed = String(child.data || '').trim();
+        if (trimmed) staticTexts.push(trimmed);
+      } else if (child.type === 'IfBlock') {
+        collectStatics(child.consequent);
+        if (child.alternate) collectStatics(child.alternate);
+      } else if (child.type === 'EachBlock') {
+        collectStatics(child.body);
+      } else if (child.fragment) {
+        collectStatics(child.fragment);
+      }
+    }
+  };
+  collectStatics(body);
+  const attrSlots = [];
+  // The hydration item is a SHALLOW object whose string fields are the exact
+  // property names the markup accesses, filled from the rendered page. That
+  // model supports one item access per slot, optionally wrapped in a global
+  // transform ({Math.round(r.score)} hydrates `score`). Shapes it cannot
+  // represent split two ways: CRASHY ones would throw at mount time against a
+  // shallow item (deep paths like r.meta.label, method calls like r.format())
+  // and force the source-preview fallback; LOSSY ones render wrong but safe
+  // (bare {r}, multi-access expressions that would double their text) and
+  // also fall back in text position, where the damage is visible.
+  const boundAs = (name, scopeInfos) => {
+    for (let i = scopeInfos.length - 1; i >= 0; i--) {
+      const info = scopeInfos[i];
+      if (info.indexName === name) return 'index';
+      if (info.itemName === name) return 'item';
+      if (info.names.has(name)) return 'field';
+    }
+    return null;
+  };
+  const slotKeysOf = (expression, scopeInfos) => {
+    const keys = new Set();
+    let crashy = false;
+    let lossy = false;
+    let touches = false;
+    const visit = (node, ctx) => {
+      if (!node || typeof node !== 'object' || crashy) return;
+      if (Array.isArray(node)) {
+        for (const item of node) visit(item, {});
+        return;
+      }
+      switch (node.type) {
+        case 'Identifier': {
+          const kind = boundAs(node.name, scopeInfos);
+          if (!kind) return;
+          touches = true;
+          if (kind === 'index') return; // the runtime each provides it
+          if (kind === 'item') { lossy = true; return; } // bare item reference
+          if (ctx.callee) { crashy = true; return; } // field() on a hydrated string
+          keys.add(node.name); // destructured context field
+          return;
+        }
+        case 'MemberExpression': {
+          if (
+            !node.computed
+            && node.object?.type === 'Identifier'
+            && boundAs(node.object.name, scopeInfos) === 'item'
+            && node.property?.type === 'Identifier'
+          ) {
+            touches = true;
+            // item.a.b or item.method(): a shallow string field throws here.
+            if (ctx.memberObject || ctx.callee) { crashy = true; return; }
+            keys.add(node.property.name);
+            return;
+          }
+          visit(node.object, { memberObject: true });
+          if (node.computed) visit(node.property, {});
+          return;
+        }
+        case 'CallExpression':
+          visit(node.callee, { callee: true });
+          for (const arg of node.arguments || []) visit(arg, {});
+          return;
+        case 'ArrowFunctionExpression':
+        case 'FunctionExpression': {
+          // Closures cannot hydrate; only lossy when they capture the item.
+          const roots = collectRootIdentifiers(node);
+          if ([...roots].some((name) => boundAs(name, scopeInfos))) { touches = true; lossy = true; }
+          return;
+        }
+        case 'Property':
+          if (node.computed) visit(node.key, {});
+          visit(node.value, {});
+          return;
+        default: {
+          for (const key of Object.keys(node)) {
+            if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
+            visit(node[key], {});
+          }
+        }
+      }
+    };
+    visit(expression, {});
+    if (crashy) return { crashy: true };
+    if (lossy || keys.size > 1) return { lossy: true };
+    if (!touches || keys.size === 0) return { skip: true };
+    return { key: [...keys][0] };
+  };
+  const staticClassesOf = (el) => {
+    const classes = [];
+    for (const attr of el?.attributes || []) {
+      if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
+        for (const part of attr.value) {
+          if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
+        }
+      }
+    }
+    return classes;
+  };
+  const scopeInfoOf = (eachNode) => {
+    const names = new Set();
+    if (eachNode.context) collectPatternNames(eachNode.context, names);
+    return {
+      names,
+      itemName: eachNode.context?.type === 'Identifier' ? eachNode.context.name : null,
+      indexName: eachNode.index || null,
+    };
+  };
+  const walkForSlots = (fragment, scopeInfos) => {
+    for (const child of fragment?.nodes || []) {
+      if (child.type === 'ExpressionTag') {
+        const slot = slotKeysOf(child.expression, scopeInfos);
+        if (slot.crashy || slot.lossy) { nestedUnsupported = true; continue; }
+        if (slot.skip) continue;
+        textSlots.push({ key: slot.key, expr: exprText(source, child.expression) });
+      } else if (child.type === 'RegularElement' || child.type === 'SvelteElement') {
+        // Bound values in ATTRIBUTES (href={link.href}, src={item.img}) are
+        // part of the item too: the browser reads the rendered attribute off
+        // the live element, so the preview does not mount with empty links.
+        // Only a single-expression attribute hydrates exactly; a mixed value
+        // ("card {r.status}") stays unhydrated because the rendered attribute
+        // is not separable into its parts, which was the prior behavior.
+        for (const attr of child.attributes || []) {
+          if (attr.type !== 'Attribute' || attr.value === true) continue;
+          if (HANDLER_ATTR_RE.test(attr.name)) continue; // functions cannot hydrate
+          const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
+          const exprParts = parts.filter((part) => part?.type === 'ExpressionTag');
+          for (const part of exprParts) {
+            const slot = slotKeysOf(part.expression, scopeInfos);
+            if (slot.crashy) { nestedUnsupported = true; continue; }
+            if (slot.skip || slot.lossy) continue;
+            if (parts.length !== 1) continue; // mixed static+dynamic value
+            attrSlots.push({
+              key: slot.key,
+              expr: exprText(source, part.expression),
+              attr: attr.name,
+              tag: child.name || null,
+              classes: staticClassesOf(child),
+            });
+          }
+        }
+        walkForSlots(child.fragment, scopeInfos);
+        continue;
+      } else if (child.type === 'EachBlock') {
+        const roots = collectRootIdentifiers(child.expression);
+        const boundNested = [...roots].some((name) => boundAs(name, scopeInfos));
+        if (boundNested) nestedUnsupported = true; // nested per-item arrays: no hydration plan yet
+        walkForSlots(child.body, [...scopeInfos, scopeInfoOf(child)]);
+      } else if (child.type === 'IfBlock') {
+        walkForSlots(child.consequent, scopeInfos);
+        if (child.alternate) walkForSlots(child.alternate, scopeInfos);
+      } else if (child.fragment) {
+        walkForSlots(child.fragment, scopeInfos);
+      }
+    }
+  };
+  walkForSlots(body, [scopeInfoOf(node)]);
+
+  const staticClasses = [];
+  for (const attr of rootEl?.attributes || []) {
+    if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
+      for (const part of attr.value) {
+        if (part.type === 'Text') staticClasses.push(...part.data.split(/\s+/).filter(Boolean));
+      }
+    }
+  }
+
+  return {
+    rootTag: rootEl?.name || null,
+    rootClasses: staticClasses,
+    textSlots,
+    attrSlots,
+    staticTexts,
+    nestedUnsupported,
+  };
+}
+
+/**
+ * Classify a keyed each block's key expression:
+ *   { keyField }        member of the loop item (e.g. `(expense.id)` when the
+ *                       context binds `expense`): browser injects a unique
+ *                       per-index value under that field.
+ *   {}                  key is the whole loop item or the index: already
+ *                       distinct per iteration, nothing to inject.
+ *   { unsupported }     free or complex keys: cannot hydrate distinct values.
+ */
+function classifyEachKey(node) {
+  const bound = new Set();
+  if (node.context) collectPatternNames(node.context, bound);
+  if (node.index) bound.add(node.index);
+  const key = node.key;
+  const roots = collectRootIdentifiers(key);
+  const usesLoopBinding = [...roots].some((name) => bound.has(name));
+  if (!usesLoopBinding) {
+    // A key that ignores the loop item is constant across iterations:
+    // guaranteed duplicate keys at mount.
+    return { unsupported: 'each key not derived from the loop item requires source-preview mode' };
+  }
+  if (key.type === 'Identifier' && bound.has(key.name)) return {};
+  if (
+    key.type === 'MemberExpression'
+    && !key.computed
+    && key.object?.type === 'Identifier'
+    && bound.has(key.object.name)
+    && key.property?.type === 'Identifier'
+  ) {
+    return { keyField: key.property.name };
+  }
+  return { unsupported: 'complex each key requires source-preview mode' };
+}
+
+/**
+ * Describe a fragment's root element for browser presence probing:
+ * { tag, classes } of the first RegularElement, or null for text-only
+ * fragments (which cannot be probed reliably).
+ */
+function describeElementProbe(fragment) {
+  const rootEl = (fragment?.nodes || []).find((n) => n.type === 'RegularElement');
+  if (!rootEl) return null;
+  const classes = [];
+  for (const attr of rootEl.attributes || []) {
+    if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
+      for (const part of attr.value) {
+        if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
+      }
+    }
+  }
+  return { tag: rootEl.name, classes };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze a markup block and produce the prop-substituted scaffold markup and
+ * the v2 prop contract. Returns { ok: false, reason } when the block needs
+ * source-preview mode (parse failure or unsupported construct).
+ */
+export function analyzeSvelteMarkup(markup, parse) {
+  const source = String(markup || '');
+  let ast;
+  try {
+    ast = parse(source, { modern: true });
+  } catch (err) {
+    return { ok: false, reason: `svelte parse failed: ${err.message}` };
+  }
+  if (ast.instance || ast.module) {
+    return { ok: false, reason: 'selected block contains a script tag' };
+  }
+  const analysis = new Analysis(source);
+  analyzeFragment(ast.fragment, analysis, []);
+  if (analysis.unsupported) {
+    return { ok: false, reason: analysis.unsupported };
+  }
+  for (const entry of analysis.contract) {
+    if (entry.kind === 'collection' && entry.item?.nestedUnsupported) {
+      return { ok: false, reason: 'per-item content (nested blocks or expressions) this preview cannot hydrate requires source-preview mode' };
+    }
+  }
+
+  const markupWithProps = applyReplacements(source, analysis.replacements);
+  return {
+    ok: true,
+    markupWithProps,
+    contract: analysis.contract.map((entry) => ({
+      prop: entry.prop,
+      expr: entry.expr,
+      kind: entry.kind,
+      // Kept for backward compatibility with v1 consumers (fake e2e agent,
+      // text-only restore paths).
+      placeholder: `{${entry.expr}}`,
+      ...(entry.item ? { item: entry.item } : {}),
+      ...(entry.probe ? { probe: entry.probe } : {}),
+    })),
+  };
+}
+
+function applyReplacements(source, replacements) {
+  const sorted = [...replacements].sort((a, b) => b.start - a.start);
+  let out = source;
+  for (const { start, end, prop } of sorted) {
+    out = out.slice(0, start) + prop + out.slice(end);
+  }
+  return out;
+}
+
+/**
+ * Restore a variant's markup back to route-source form: every free
+ * identifier that matches a contract prop is replaced by its original
+ * expression. AST-based so `{#each stages as stage}` restores to
+ * `{#each data.stages as stage}` even though the prop appears without braces.
+ */
+export function restoreSvelteMarkup(markup, contract, parse) {
+  const source = String(markup || '');
+  const byProp = new Map();
+  for (const entry of contract || []) byProp.set(entry.prop, entry.expr);
+  if (byProp.size === 0) return { ok: true, markup: source };
+
+  let ast;
+  try {
+    ast = parse(source, { modern: true });
+  } catch (err) {
+    return { ok: false, reason: `variant parse failed: ${err.message}` };
+  }
+
+  const replacements = [];
+  const visitExpr = (expression, scopes) => {
+    if (!expression) return;
+    collectFreeIdentifierRanges(expression, scopes, (name, start, end) => {
+      const original = byProp.get(name);
+      if (original != null && original !== name) replacements.push({ start, end, prop: original });
+    });
+  };
+
+  const walk = (fragment, scopes) => {
+    const fragmentScope = new Set();
+    const nextScopes = [...scopes, fragmentScope];
+    for (const node of fragment?.nodes || []) {
+      if (node.type === 'ConstTag' && node.declaration) {
+        for (const decl of node.declaration.declarations || []) collectPatternNames(decl.id, fragmentScope);
+      }
+    }
+    for (const node of fragment?.nodes || []) {
+      switch (node?.type) {
+        case 'ExpressionTag':
+        case 'HtmlTag':
+          visitExpr(node.expression, nextScopes);
+          break;
+        case 'ConstTag':
+          for (const decl of node.declaration?.declarations || []) visitExpr(decl.init, nextScopes);
+          break;
+        case 'EachBlock': {
+          visitExpr(node.expression, nextScopes);
+          const bound = new Set();
+          if (node.context) collectPatternNames(node.context, bound);
+          if (node.index) bound.add(node.index);
+          // The key evaluates per item, so the loop context and index are in
+          // scope there. Visiting it with outer scopes only let a contract
+          // prop that shares a loop binding's name rewrite the key.
+          if (node.key) visitExpr(node.key, [...nextScopes, bound]);
+          walk(node.body, [...nextScopes, bound]);
+          if (node.fallback) walk(node.fallback, nextScopes);
+          break;
+        }
+        case 'IfBlock':
+          visitExpr(node.test, nextScopes);
+          walk(node.consequent, nextScopes);
+          if (node.alternate) walk(node.alternate, nextScopes);
+          break;
+        case 'KeyBlock':
+          visitExpr(node.expression, nextScopes);
+          walk(node.fragment, nextScopes);
+          break;
+        case 'SnippetBlock': {
+          const bound = new Set();
+          for (const param of node.parameters || []) collectPatternNames(param, bound);
+          walk(node.body, [...nextScopes, bound]);
+          break;
+        }
+        default: {
+          for (const attr of node?.attributes || []) {
+            if (attr.type === 'Attribute' && Array.isArray(attr.value)) {
+              for (const part of attr.value) {
+                if (part?.type === 'ExpressionTag') visitExpr(part.expression, nextScopes);
+              }
+            } else if (attr.expression) {
+              visitExpr(attr.expression, nextScopes);
+            }
+          }
+          if (node?.fragment) walk(node.fragment, nextScopes);
+        }
+      }
+    }
+  };
+  walk(ast.fragment, []);
+
+  return { ok: true, markup: applyReplacements(source, replacements) };
+}
+
+/**
+ * Report [name, start, end] for every free root identifier READ in an
+ * expression (skips member properties, object keys, shadowed names).
+ */
+function collectFreeIdentifierRanges(node, scopes, emit) {
+  const visit = (n, localBound) => {
+    if (!n || typeof n !== 'object') return;
+    if (Array.isArray(n)) { for (const item of n) visit(item, localBound); return; }
+    switch (n.type) {
+      case 'Identifier': {
+        const bound = localBound.has(n.name) || scopes.some((s) => s.has(n.name));
+        if (!bound) emit(n.name, n.start, n.end);
+        return;
+      }
+      case 'MemberExpression':
+        visit(n.object, localBound);
+        if (n.computed) visit(n.property, localBound);
+        return;
+      case 'Property':
+        if (n.computed) visit(n.key, localBound);
+        visit(n.value, localBound);
+        return;
+      case 'ArrowFunctionExpression':
+      case 'FunctionExpression': {
+        const inner = new Set(localBound);
+        for (const param of n.params || []) collectPatternNames(param, inner);
+        visit(n.body, inner);
+        return;
+      }
+      default:
+        for (const key of Object.keys(n)) {
+          if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
+          visit(n[key], localBound);
+        }
+    }
+  };
+  visit(node, new Set());
+}
+
+/**
+ * Build the preview component's script block from a v2 contract, with
+ * defaults that keep an unhydrated mount rendering instead of crashing.
+ */
+export function buildPropsScriptV2(contract) {
+  if (!contract || contract.length === 0) {
+    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+  }
+  const defaults = {
+    text: "''",
+    raw: "''",
+    condition: 'false',
+    collection: '[]',
+    handler: '() => {}',
+  };
+  const types = {
+    text: 'string',
+    raw: 'string',
+    condition: 'boolean',
+    collection: 'Array<Record<string, unknown>>',
+    handler: '() => void',
+  };
+  const names = contract
+    .map((c) => `${c.prop} = ${defaults[c.kind] ?? "''"}`)
+    .join(', ');
+  const typeFields = contract
+    .map((c) => `    ${c.prop}?: ${types[c.kind] ?? 'string'};`)
+    .join('\n');
+  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+}

.agents/skills/impeccable/scripts/live/svelte-component.mjs

@@ -10,9 +10,38 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
+import {
+  analyzeSvelteMarkup,
+  buildPropsScriptV2,
+  loadSvelteCompiler,
+  restoreSvelteMarkup,
+} from './svelte-ast.mjs';
+import {
+  bakeParamValues,
+  collectAllSelectors,
+  collectUnusedSelectors,
+  normalizeSelector,
+  parseStylesheet,
+  pruneUnusedSelectors,
+  reconcileCss,
+  serializeNodes,
+  splitSelectorList,
+} from './accept-css.mjs';
+import { verifyAcceptedSource } from './accept-verify.mjs';
 
+// Preview modules stay under node_modules on purpose: SvelteKit restricts
+// vite's server.fs.allow to src/lib, src/routes, .svelte-kit, and
+// node_modules, so an .impeccable/ tree under the app root 403s (verified
+// against a real SvelteKit dev server). Staleness from node_modules being
+// unwatched is solved by REVISIONED module paths instead: every publish
+// snapshots the variant files into a fresh r<N>/ directory and the browser
+// imports from there, so a republished fix can never be pinned by a
+// transform cache keyed on the old path.
 export const SVELTE_COMPONENT_ROOT = 'node_modules/.impeccable-live';
+// A short-lived interim location; swept so no project keeps a stray tree.
+export const LEGACY_SVELTE_COMPONENT_ROOT = '.impeccable/live/previews';
 export const SVELTE_RUNTIME_FILE = `${SVELTE_COMPONENT_ROOT}/__runtime.js`;
+export const SVELTE_PROBE_FILE = `${SVELTE_COMPONENT_ROOT}/__probe.js`;
 export const DEFERRED_ACCEPTS_FILE = '.impeccable/live/deferred-svelte-component-accepts.json';
 
 const MUSTACHE_RE = /\{([^{}]+)\}/g;
@@ -32,9 +61,18 @@ export function manifestPathForSession(id, cwd = process.cwd()) {
 
 export function ensureRuntimeHelper(cwd = process.cwd()) {
   const file = path.join(cwd, SVELTE_RUNTIME_FILE);
-  if (fs.existsSync(file)) return file;
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
+  }
+  // Attach-time probe: the browser imports this through the dev server before
+  // the first mount. A 404 here means the resolved app root and the dev
+  // server's root disagree, and the session fails with a named error instead
+  // of a silent fall-back to the picker at first variant.
+  const probe = path.join(cwd, SVELTE_PROBE_FILE);
+  if (!fs.existsSync(probe)) {
+    fs.writeFileSync(probe, `export const impeccableLivePreviewProbe = true;\n`, 'utf-8');
+  }
   return file;
 }
 
@@ -136,6 +174,14 @@ function buildInsertVariantStub(variantNum) {
   return `${buildPropsScript([])}<div class="impeccable-insert-preview">Insert variant ${variantNum}</div>\n\n<style>\n  .impeccable-insert-preview { display: block; }\n</style>\n`;
 }
 
+/**
+ * Scaffold a component-preview session. The scaffold is AST-based: the app's
+ * own svelte compiler parses the selected markup, control-flow blocks are
+ * preserved (an each collection crosses the prop contract as ONE structured
+ * prop, its loop body verbatim), and constructs a detached preview cannot
+ * support return `{ fallback: 'source-preview', reason }` so the caller keeps
+ * the markup inside the route file instead of shipping a wrong preview.
+ */
 export function scaffoldSvelteComponentSession({
   id,
   count,
@@ -145,25 +191,55 @@ export function scaffoldSvelteComponentSession({
   originalLines,
   cwd = process.cwd(),
 }) {
+  const originalMarkup = originalLines.join('\n');
+
+  const compiler = loadSvelteCompiler(cwd);
+  if (!compiler) {
+    return { fallback: 'source-preview', reason: 'svelte 5 compiler not resolvable from the app root' };
+  }
+  const analysis = analyzeSvelteMarkup(originalMarkup, compiler.parse);
+  if (!analysis.ok) {
+    return { fallback: 'source-preview', reason: analysis.reason };
+  }
+
   ensureRuntimeHelper(cwd);
   const dir = componentSessionDir(id, cwd);
   fs.mkdirSync(dir, { recursive: true });
 
-  const originalMarkup = originalLines.join('\n');
-  const contract = buildPropContract(extractMustacheExpressions(originalMarkup));
-  const originalWithProps = substituteExprsWithProps(originalMarkup, contract);
+  const contract = analysis.contract;
+  const seeded = extractMatchingSourceCss(
+    safeReadSource(path.resolve(cwd, sourceFile)),
+    originalMarkup,
+  );
+  const seededCss = seeded.css;
+  // The preview compiles in isolation, so NONE of these source rules applied
+  // to what the user approved. Accept enforces that preview truth: any of
+  // them the variant does not re-declare is superseded and removed, instead
+  // of re-attaching to the accepted markup through kept class names (the
+  // ".decisions grid grabs the new board" failure). Only the CLASS-matched
+  // selectors are candidates; tag rules style shared route elements.
+  const seededSelectors = [...seeded.supersedable];
 
   const manifest = {
     id,
     previewMode: 'svelte-component',
+    contractVersion: 2,
     sourceFile: sourceFile.split(path.sep).join('/'),
     sourceStartLine,
     sourceEndLine,
     count,
     propContract: contract,
     originalMarkup,
+    seededSelectors,
     componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
+    // Absolute paths let the browser fall back to /@fs/ imports when the dev
+    // server's base or root makes root-relative URLs miss, and probe whether
+    // the preview tree is reachable at all before blaming a variant.
+    componentDirAbs: dir.split(path.sep).join('/'),
     runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
+    runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
+    probeModule: `/${SVELTE_PROBE_FILE}`,
+    probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
   };
 
   fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
@@ -171,7 +247,7 @@ export function scaffoldSvelteComponentSession({
   for (let n = 1; n <= count; n++) {
     const variantFile = path.join(dir, `v${n}.svelte`);
     if (!fs.existsSync(variantFile)) {
-      fs.writeFileSync(variantFile, buildVariantStub(n, originalWithProps, contract), 'utf-8');
+      fs.writeFileSync(variantFile, buildVariantStubV2(n, analysis.markupWithProps, contract, seededCss), 'utf-8');
     }
   }
 
@@ -180,9 +256,100 @@ export function scaffoldSvelteComponentSession({
     manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
     componentDir: manifest.componentDir,
     propContract: contract,
+    // Inlined so the generate event's scaffold payload carries the stub
+    // shape; the agent edits vN.svelte in place instead of spending reads on
+    // the manifest and stub files (or deleting and recreating them).
+    stubMarkup: analysis.markupWithProps,
+    seededCss,
   };
 }
 
+function safeReadSource(filePath) {
+  try { return fs.readFileSync(filePath, 'utf-8'); } catch { return ''; }
+}
+
+function escapeSelectorToken(token) {
+  return String(token).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Seed variant stubs with the source component's rules that already style the
+ * selected markup, so variants start from the real cascade (a detached
+ * preview inherits none of the route's compile-scoped CSS) instead of
+ * reimplementing it blind.
+ *
+ * Returns { css, supersedable }. `css` is every matching rule (class OR tag
+ * matched). `supersedable` holds only the CLASS-matched selectors: those are
+ * the accept-time removal candidates. Tag selectors (h1, a, p) style shared
+ * elements across the whole route, so they seed the preview but are never
+ * candidates for removal.
+ */
+export function extractMatchingSourceCss(routeSource, originalMarkup) {
+  const empty = { css: '', supersedable: new Set() };
+  const styleMatch = String(routeSource || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
+  if (!styleMatch) return empty;
+  const classNames = new Set();
+  const classRe = /class\s*=\s*(["'])(.*?)\1/g;
+  let m;
+  while ((m = classRe.exec(originalMarkup))) {
+    for (const cls of m[2].split(/\s+/)) if (cls && !cls.includes('{')) classNames.add(cls);
+  }
+  const tagRe = /<([a-z][a-z0-9-]*)/gi;
+  const tags = new Set();
+  while ((m = tagRe.exec(originalMarkup))) tags.add(m[1].toLowerCase());
+  if (classNames.size === 0 && tags.size === 0) return empty;
+
+  // Token-boundary matching, never substring: `.btn` must not match
+  // `.btn-primary`, and `.stage` must not match `.stages`. A substring hit
+  // seeds a rule that never styled the pick, and a falsely seeded selector
+  // becomes an accept-time DELETION of a hand-written rule.
+  const classRes = [...classNames].map((cls) => new RegExp('\\.' + escapeSelectorToken(cls) + '(?![A-Za-z0-9_-])'));
+  const tagRes = [...tags].map((tag) => new RegExp('(^|[\\s>+~,(])' + escapeSelectorToken(tag) + '(?![A-Za-z0-9_-])', 'i'));
+  const classMatches = (selector) => classRes.some((re) => re.test(selector));
+  const tagMatches = (selector) => tagRes.some((re) => re.test(selector));
+
+  const supersedable = new Set();
+  const ruleMatches = (prelude) => {
+    let matched = false;
+    for (const selector of splitSelectorList(prelude)) {
+      if (classMatches(selector)) {
+        matched = true;
+        supersedable.add(normalizeSelector(selector));
+      } else if (tagMatches(selector)) {
+        matched = true;
+      }
+    }
+    return matched;
+  };
+
+  const pick = (nodes) => {
+    const kept = [];
+    for (const node of nodes) {
+      if (node.type === 'rule' && ruleMatches(node.prelude)) kept.push(node);
+      else if (node.type === 'at' && node.children) {
+        const children = pick(node.children);
+        if (children.length) kept.push({ ...node, children });
+      }
+    }
+    return kept;
+  };
+  return { css: serializeNodes(pick(parseStylesheet(styleMatch[1]))), supersedable };
+}
+
+function buildVariantStubV2(variantNum, markupWithProps, contract, seededCss) {
+  const propsComment = contract.length > 0
+    ? `\n<!-- Props: ${contract.map((c) => `${c.prop} (${c.kind}) <- {${c.expr}}`).join(', ')} -->\n`
+    : '';
+  // The guard comments must never contain the literal "<style" character
+  // sequence: agents (and the fake test agent) locate the style block with
+  // string searches, and a mention inside a comment truncates their surgery
+  // mid-comment.
+  const css = seededCss
+    ? `\n<style>\n  /* Variant ${variantNum}: seeded from the route's current rules; restyle or delete freely.\n     ALL rules go inside THIS block. Svelte allows exactly one top-level style\n     element per component; appending a second one is a compile error. */\n${seededCss.split('\n').map((l) => (l.trim() ? '  ' + l : '')).join('\n')}\n</style>\n`
+    : `\n<style>\n  /* Variant ${variantNum}: add all CSS inside THIS block. Svelte allows exactly\n     one top-level style element; a second one is a compile error. */\n</style>\n`;
+  return `${buildPropsScriptV2(contract)}${propsComment}${markupWithProps.trim()}\n${css}`;
+}
+
 export function scaffoldSvelteComponentInsertSession({
   id,
   count,
@@ -213,7 +380,11 @@ export function scaffoldSvelteComponentInsertSession({
     count,
     propContract: [],
     componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
+    componentDirAbs: dir.split(path.sep).join('/'),
     runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
+    runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
+    probeModule: `/${SVELTE_PROBE_FILE}`,
+    probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
   };
 
   fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
@@ -238,16 +409,24 @@ export function findSvelteComponentManifest(id, cwd = process.cwd()) {
   if (fs.existsSync(direct)) {
     return readManifest(direct);
   }
-  const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
-  if (!fs.existsSync(root)) return null;
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const candidate = path.join(root, entry.name, 'manifest.json');
-    if (!fs.existsSync(candidate)) continue;
-    try {
-      const manifest = readManifest(candidate);
-      if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
-    } catch { /* skip */ }
+  // Legacy location: a session scaffolded by an older version can still be
+  // accepted after an upgrade.
+  const legacyDirect = path.join(cwd, LEGACY_SVELTE_COMPONENT_ROOT, id, 'manifest.json');
+  if (fs.existsSync(legacyDirect)) {
+    return readManifest(legacyDirect);
+  }
+  for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
+    const root = path.join(cwd, rootRel);
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(root, entry.name, 'manifest.json');
+      if (!fs.existsSync(candidate)) continue;
+      try {
+        const manifest = readManifest(candidate);
+        if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
+      } catch { /* skip */ }
+    }
   }
   return null;
 }
@@ -451,35 +630,6 @@ function rewriteParamSelectors(selector, paramValues) {
   return { keep, selector: next };
 }
 
-function splitSelectorList(prelude) {
-  const selectors = [];
-  let start = 0;
-  let bracket = 0;
-  let paren = 0;
-  let quote = null;
-  for (let i = 0; i < prelude.length; i++) {
-    const ch = prelude[i];
-    if (quote) {
-      if (ch === '\\') i++;
-      else if (ch === quote) quote = null;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      continue;
-    }
-    if (ch === '[') bracket++;
-    else if (ch === ']') bracket = Math.max(0, bracket - 1);
-    else if (ch === '(') paren++;
-    else if (ch === ')') paren = Math.max(0, paren - 1);
-    else if (ch === ',' && bracket === 0 && paren === 0) {
-      selectors.push(prelude.slice(start, i));
-      start = i + 1;
-    }
-  }
-  selectors.push(prelude.slice(start));
-  return selectors;
-}
 
 function selectorHasVariant(selector, variantNum) {
   return variantSelectorRegex(variantNum).test(selector);
@@ -527,10 +677,24 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
 
   const rootTag = matchOpeningTag(markup)?.tag || 'div';
   const contract = manifest.propContract || [];
+  const compiler = loadSvelteCompiler(cwd);
   const mergedMarkup = mergeOriginalTopLevelAttrs(markup, manifest.originalMarkup || '');
-  const restoredMarkup = substitutePropsWithExprs(mergedMarkup, contract)
-    .split('\n')
-    .map((line) => line.trimEnd());
+
+  // Restore props back to route expressions. Contract v2 restores through the
+  // AST so a prop used without braces (each headers, attribute positions)
+  // still maps back to its original expression; v1 falls back to the textual
+  // placeholder swap.
+  let restoredText;
+  if (Number(manifest.contractVersion) === 2 && compiler) {
+    const restored = restoreSvelteMarkup(mergedMarkup, contract, compiler.parse);
+    if (!restored.ok) {
+      return { handled: false, error: 'Accepted variant does not parse: ' + restored.reason, ...resultBase };
+    }
+    restoredText = restored.markup;
+  } else {
+    restoredText = substitutePropsWithExprs(mergedMarkup, contract);
+  }
+  const restoredMarkup = restoredText.split('\n').map((line) => line.trimEnd());
 
   const sourceContent = fs.readFileSync(sourceFile, 'utf-8');
   const sourceLines = sourceContent.split('\n');
@@ -541,10 +705,7 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
   }
 
   const indent = sourceLines[start].match(/^(\s*)/)?.[1] || '';
-  const indentedMarkup = restoredMarkup.map((line) => {
-    if (line.trim() === '') return '';
-    return indent + line.trimStart();
-  });
+  const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
 
   let newLines = [
     ...sourceLines.slice(0, start),
@@ -552,25 +713,235 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
     ...sourceLines.slice(end + 1),
   ];
 
-  const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
-  const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
-  if (bakedCss.length > 0) {
-    newLines = appendCssToSvelteStyle(newLines, bakedCss);
+  // Selectors that were already unused before this accept are the user's
+  // pre-existing code; the pruning pass must not touch them.
+  const preUnused = compiler ? collectUnusedSelectors(sourceContent, compiler.compile) : new Set();
+
+  // Bake params (declared kinds from params.json drive branch pruning), then
+  // MERGE into the component's existing style block: matching selectors are
+  // replaced, new ones appended. Appending alone is how superseded rules used
+  // to survive their own replacement.
+  const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
+  let variantCss = cssLines.join('\n');
+  if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
+    // Defensive: strip preview-wrapper selectors that authoring rules forbid
+    // on this path but an off-spec agent may still emit.
+    variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
+  }
+  const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
+  const cssStats = { replaced: 0, appended: 0, pruned: [], superseded: [] };
+  if (bakedCss.trim()) {
+    const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
+    newLines = merged.text.split('\n');
+    cssStats.replaced = merged.replaced;
+    cssStats.appended = merged.appended;
+  }
+
+  let finalText = newLines.join('\n');
+
+  // Preview truth: the detached preview never applied the source rules that
+  // styled the replaced selection, so the user approved a design without
+  // them. Any seeded selector the variant did not re-declare is superseded;
+  // left in place it re-attaches through kept class names (the accepted root
+  // keeps its original classes) and re-layouts markup it no longer owns.
+  //
+  // Removal is bounded by ownership: a selector whose classes are still used
+  // by route markup OUTSIDE the replaced region does not belong to the pick
+  // alone, and removing it would strip styling from markup this accept never
+  // touched. Keeping it risks a visible re-attachment quirk on the accepted
+  // region; deleting it breaks the rest of the route. Keep it.
+  const outsideMarkup = [...sourceLines.slice(0, start), ...sourceLines.slice(end + 1)]
+    .join('\n')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, '');
+  const outsideClasses = new Set();
+  {
+    const attrRe = /class\s*=\s*(["'])(.*?)\1/g;
+    let cm;
+    while ((cm = attrRe.exec(outsideMarkup))) {
+      for (const cls of cm[2].split(/\s+/)) if (cls && !cls.includes('{')) outsideClasses.add(cls);
+    }
+    const directiveRe = /class:([A-Za-z0-9_-]+)/g;
+    while ((cm = directiveRe.exec(outsideMarkup))) outsideClasses.add(cm[1]);
+  }
+  const usedOutsideReplacedRegion = (selector) => {
+    const classTokenRe = /\.([A-Za-z0-9_-]+)/g;
+    let tm;
+    while ((tm = classTokenRe.exec(selector))) {
+      if (outsideClasses.has(tm[1])) return true;
+    }
+    return false;
+  };
+  const incomingSelectors = collectAllSelectors(bakedCss);
+  const superseded = (manifest.seededSelectors || [])
+    .map((selector) => normalizeSelector(selector))
+    .filter((selector) => selector && !incomingSelectors.has(selector) && !usedOutsideReplacedRegion(selector));
+  if (superseded.length > 0) {
+    const scrubbed = removeSelectorsFromSvelteSource(finalText, new Set(superseded));
+    finalText = scrubbed.text;
+    cssStats.superseded = scrubbed.removed;
+  }
+
+  if (compiler) {
+    const pruned = pruneUnusedSelectors(finalText, compiler.compile, { skipSelectors: preUnused });
+    finalText = pruned.source;
+    cssStats.pruned = pruned.removed;
+  }
+
+  // Postcondition: no selector from the user's pre-accept CSS may vanish
+  // unless the compiler-driven prune or the preview-truth supersession
+  // deliberately removed it. This turns any parser or reconciler defect into
+  // a loud refusal instead of silent damage to a hand-written style block.
+  const lostSelectors = findLostSelectors(sourceContent, finalText, [
+    ...cssStats.pruned,
+    ...cssStats.superseded,
+  ]);
+  if (lostSelectors.length > 0) {
+    return {
+      handled: false,
+      error: 'CSS reconciliation would lose selectors from the existing style block: '
+        + lostSelectors.join(', ')
+        + '. Source not modified; accept the variant manually.',
+      mode: 'error',
+      ...resultBase,
+    };
   }
 
   try {
-    fs.writeFileSync(sourceFile, newLines.join('\n'), 'utf-8');
+    fs.writeFileSync(sourceFile, finalText, 'utf-8');
   } catch (err) {
     return { handled: false, error: 'Failed to write Svelte source: ' + err.message, ...resultBase };
   }
   removeSvelteComponentSession(manifest.id, cwd);
 
+  const verify = verifyAcceptedSource(finalText);
   return {
     handled: true,
+    css: cssStats,
+    verify,
     ...resultBase,
   };
 }
 
+/** Re-indent a block onto `indent` while preserving its internal structure. */
+export function reindentPreservingStructure(lines, indent) {
+  const nonEmpty = lines.filter((line) => line.trim() !== '');
+  if (nonEmpty.length === 0) return lines.map(() => '');
+  const minIndent = Math.min(...nonEmpty.map((line) => (line.match(/^\s*/) || [''])[0].length));
+  return lines.map((line) => {
+    if (line.trim() === '') return '';
+    const current = (line.match(/^\s*/) || [''])[0].length;
+    return indent + line.slice(Math.min(minIndent, current));
+  });
+}
+
+function styleBlockText(sourceText) {
+  const match = String(sourceText || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
+  return match ? match[1] : '';
+}
+
+/**
+ * Remove every rule whose (normalized) selector list is fully contained in
+ * `selectors` from the component's style block, at any at-rule nesting depth.
+ * Rules that mix doomed and surviving selectors keep the survivors.
+ */
+export function removeSelectorsFromSvelteSource(sourceText, selectors) {
+  const text = String(sourceText || '');
+  const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+  let lastMatch = null;
+  let m;
+  while ((m = styleRe.exec(text))) lastMatch = m;
+  if (!lastMatch) return { text, removed: [] };
+
+  const removed = [];
+  const transform = (nodes) => {
+    const kept = [];
+    for (const node of nodes) {
+      if (node.type === 'rule') {
+        const survivors = [];
+        for (const selector of splitSelectorList(node.prelude)) {
+          if (selectors.has(normalizeSelector(selector))) removed.push(normalizeSelector(selector));
+          else survivors.push(selector);
+        }
+        if (survivors.length > 0) kept.push({ ...node, prelude: survivors.join(', ') });
+      } else if (node.type === 'at' && node.children) {
+        const children = transform(node.children);
+        if (children.length > 0) kept.push({ ...node, children });
+      } else {
+        kept.push(node);
+      }
+    }
+    return kept;
+  };
+
+  const nodes = transform(parseStylesheet(lastMatch[1]));
+  if (removed.length === 0) return { text, removed };
+  const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
+  const rebuilt = `${openTag}\n${serializeNodes(nodes).split('\n').map((l) => (l.trim() ? '  ' + l : '')).join('\n')}\n</style>`;
+  return {
+    text: text.slice(0, lastMatch.index) + rebuilt + text.slice(lastMatch.index + lastMatch[0].length),
+    removed,
+  };
+}
+
+export function findLostSelectors(beforeSource, afterSource, prunedSelectors = []) {
+  const before = collectAllSelectors(styleBlockText(beforeSource));
+  const after = collectAllSelectors(styleBlockText(afterSource));
+  const pruned = new Set((prunedSelectors || []).map((s) => normalizeSelector(s)));
+  const lost = [];
+  for (const selector of before) {
+    if (!after.has(selector) && !pruned.has(selector)) lost.push(selector);
+  }
+  return lost;
+}
+
+function readDeclaredParams(manifest, variantNum, cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(cwd, manifest.componentDir, 'params.json'), 'utf-8'));
+    const list = raw?.[String(variantNum)];
+    return Array.isArray(list) ? list : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Merge CSS into a svelte component's top-level style block (created when
+ * absent), replacing rules whose selectors match and appending the rest.
+ */
+export function mergeCssIntoSvelteSource(sourceText, incomingCss) {
+  const text = String(sourceText || '');
+  const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+  let lastMatch = null;
+  let m;
+  while ((m = styleRe.exec(text))) lastMatch = m;
+
+  if (!lastMatch) {
+    const { css, replaced, appended } = reconcileCss('', incomingCss);
+    return {
+      text: `${text.replace(/\s*$/, '')}\n\n<style>\n${indentCssBlock(css)}\n</style>\n`,
+      replaced,
+      appended,
+    };
+  }
+
+  const inner = lastMatch[1];
+  const { css, replaced, appended } = reconcileCss(inner, incomingCss);
+  const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
+  const replacedBlock = `${openTag}\n${indentCssBlock(css)}\n</style>`;
+  return {
+    text: text.slice(0, lastMatch.index) + replacedBlock + text.slice(lastMatch.index + lastMatch[0].length),
+    replaced,
+    appended,
+  };
+}
+
+function indentCssBlock(css) {
+  return String(css || '')
+    .split('\n')
+    .map((line) => (line.trim() === '' ? '' : '  ' + line))
+    .join('\n');
+}
+
 function inlineSvelteComponentInsertAccept({
   manifest,
   markup,
@@ -601,10 +972,7 @@ function inlineSvelteComponentInsertAccept({
 
   const nearbyLine = sourceLines[insertIndex] ?? sourceLines[insertIndex - 1] ?? '';
   const indent = nearbyLine.match(/^(\s*)/)?.[1] || '';
-  const indentedMarkup = restoredMarkup.map((line) => {
-    if (line.trim() === '') return '';
-    return indent + line.trimStart();
-  });
+  const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
 
   let newLines = [
     ...sourceLines.slice(0, insertIndex),
@@ -612,10 +980,15 @@ function inlineSvelteComponentInsertAccept({
     ...sourceLines.slice(insertIndex),
   ];
 
-  const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
-  const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
-  if (bakedCss.length > 0) {
-    newLines = appendCssToSvelteStyle(newLines, bakedCss);
+  let variantCss = cssLines.join('\n');
+  if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
+    variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
+  }
+  const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
+  const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
+  if (bakedCss.trim()) {
+    const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
+    newLines = merged.text.split('\n');
   }
 
   try {
@@ -625,8 +998,10 @@ function inlineSvelteComponentInsertAccept({
   }
   removeSvelteComponentSession(manifest.id, cwd);
 
+  const verify = verifyAcceptedSource(newLines.join('\n'));
   return {
     handled: true,
+    verify,
     ...resultBase,
   };
 }
@@ -729,18 +1104,159 @@ export function removeSvelteComponentSession(id, cwd = process.cwd()) {
   } catch { /* non-fatal */ }
 }
 
-export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
-  const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
-  if (!fs.existsSync(root)) return;
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    if (entry.name.startsWith('__')) continue;
+/**
+ * Compile-check every variant component of a session with the app's own
+ * compiler, BEFORE the browser ever imports them. A variant that does not
+ * compile (the classic: a second top-level <style> appended next to the
+ * seeded one) used to surface as a red Vite overlay in the user's page plus
+ * a mount-failure round trip; bounced at publish time it is a private
+ * agent-side fix with the exact file and line.
+ */
+export function compileCheckVariants(id, cwd = process.cwd()) {
+  const manifest = findSvelteComponentManifest(id, cwd);
+  if (!manifest || !manifest.manifestPath) return { ok: true, failures: [], checked: 0 };
+  const compiler = loadSvelteCompiler(cwd);
+  if (!compiler || typeof compiler.compile !== 'function') return { ok: true, failures: [], checked: 0 };
+  const sessionDir = path.dirname(manifest.manifestPath);
+  const failures = [];
+  let checked = 0;
+  let entries = [];
+  try { entries = fs.readdirSync(sessionDir); } catch { return { ok: true, failures: [], checked: 0 }; }
+  for (const name of entries) {
+    if (!/^v\d+\.svelte$/.test(name)) continue;
+    checked++;
     try {
-      fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
+      compiler.compile(fs.readFileSync(path.join(sessionDir, name), 'utf-8'), { generate: false });
+    } catch (err) {
+      failures.push({
+        file: `${manifest.componentDir}/${name}`,
+        line: err?.start?.line ?? null,
+        column: err?.start?.column ?? null,
+        message: String(err?.message || err).split('\n')[0].slice(0, 300),
+      });
+    }
+  }
+  return { ok: failures.length === 0, failures, checked };
+}
+
+/**
+ * Snapshot the agent-authored variant files into a fresh revision directory
+ * and stamp the manifest. Called by the server on every publish (`done`
+ * reply) for a component session; the browser imports from the revision dir,
+ * so the dev server can never serve a stale compile of a republished file.
+ */
+export function bumpSvelteComponentPreviewRevision(id, cwd = process.cwd()) {
+  const manifest = findSvelteComponentManifest(id, cwd);
+  if (!manifest || !manifest.manifestPath) return null;
+  const sessionDir = path.dirname(manifest.manifestPath);
+  const revision = Number(manifest.revision || 0) + 1;
+  const revDirName = `r${revision}`;
+  const revDir = path.join(sessionDir, revDirName);
+  try {
+    fs.mkdirSync(revDir, { recursive: true });
+    let entries = [];
+    try { entries = fs.readdirSync(sessionDir, { withFileTypes: true }); } catch { /* empty */ }
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (entry.name === 'manifest.json') continue;
+      fs.copyFileSync(path.join(sessionDir, entry.name), path.join(revDir, entry.name));
+    }
+    // Previous revision dirs are dead the moment a new one exists.
+    for (const entry of entries) {
+      if (entry.isDirectory() && /^r\d+$/.test(entry.name) && entry.name !== revDirName) {
+        try { fs.rmSync(path.join(sessionDir, entry.name), { recursive: true, force: true }); } catch { /* non-fatal */ }
+      }
+    }
+    const relSessionDir = path.relative(cwd, sessionDir).split(path.sep).join('/');
+    const updated = {
+      ...manifest,
+      revision,
+      revisionDir: `${relSessionDir}/${revDirName}`,
+      revisionDirAbs: revDir.split(path.sep).join('/'),
+    };
+    delete updated.manifestPath;
+    fs.writeFileSync(manifest.manifestPath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
+    return { revision, revisionDir: updated.revisionDir };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stop-path sweep. The whole `node_modules/.impeccable-live` tree is
+ * impeccable-owned and gitignored, so once no session should survive there is
+ * nothing left worth keeping: the per-session dirs, the generated
+ * `__runtime.js`, and the parent directory all go. The old per-entry loop
+ * skipped `__*` entries and the parent, which left the runtime shim and an
+ * empty directory in every project that ever ran live mode once.
+ */
+export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
+  for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
+    const root = path.join(cwd, rootRel);
+    if (!fs.existsSync(root)) continue;
+    try {
+      fs.rmSync(root, { recursive: true, force: true });
     } catch { /* non-fatal */ }
   }
 }
 
+/**
+ * Boot-path sweep. A restart must not delete the tree wholesale: sessions
+ * recorded in the session store may still be mid-generation. Remove only the
+ * session dirs whose id has no active snapshot, then drop `__runtime.js` and
+ * the parent directory when nothing is left to serve.
+ *
+ * @param {Iterable<string>} activeIds session ids that must be preserved
+ * @returns {{ removed: string[], removedRoot: boolean, kept: string[] }}
+ */
+export function sweepInactiveSvelteComponentSessions(activeIds = [], cwd = process.cwd()) {
+  const result = { removed: [], removedRoot: false, kept: [] };
+  const active = new Set();
+  for (const id of activeIds || []) {
+    if (typeof id === 'string' && id) active.add(id);
+  }
+
+  for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
+    const root = path.join(cwd, rootRel);
+    if (!fs.existsSync(root)) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    let keptHere = 0;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('__')) continue;
+      if (active.has(entry.name)) {
+        result.kept.push(entry.name);
+        keptHere++;
+        continue;
+      }
+      try {
+        fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
+        result.removed.push(entry.name);
+      } catch {
+        // Could not remove it, so it still occupies the tree; treat it as kept
+        // so the parent directory is not torn out from under it.
+        result.kept.push(entry.name);
+        keptHere++;
+      }
+    }
+
+    if (keptHere === 0) {
+      try {
+        fs.rmSync(root, { recursive: true, force: true });
+        result.removedRoot = true;
+      } catch { /* non-fatal */ }
+    }
+  }
+  return result;
+}
+
 export function deferredAcceptsPath(cwd = process.cwd()) {
   const key = createHash('sha1').update(path.resolve(cwd)).digest('hex').slice(0, 16);
   return path.join(os.tmpdir(), 'impeccable-live', key, 'deferred-svelte-component-accepts.json');

.agents/skills/impeccable/scripts/live/sveltekit-adapter.mjs

@@ -7,6 +7,7 @@
  * actual live UI remains the shared plain-DOM browser chrome.
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -14,6 +15,28 @@ export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot
 export const SVELTE_LAYOUT_MARKER_OPEN = '<!-- impeccable-live-svelte-start -->';
 export const SVELTE_LAYOUT_MARKER_CLOSE = '<!-- impeccable-live-svelte-end -->';
 export const SVELTE_ROOT_IMPORT = "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte';";
+// Matches the import at ANY revision (or none). [ \t]* bounds only, never
+// \s*: a greedy \s* after the statement swallowed the next line's
+// indentation on removal, leaving a formatting scar in user layouts.
+const SVELTE_ROOT_IMPORT_LINE_RE = /^[ \t]*import ImpeccableLiveRoot from '\$lib\/impeccable\/ImpeccableLiveRoot\.svelte(?:\?[^']*)?';[ \t]*\r?\n?/gm;
+
+/**
+ * The import specifier carries a token-derived revision query. The adapter
+ * component embeds the helper token, and Vite (client AND SSR) can keep
+ * serving a stale compiled module after the file is rewritten on a helper
+ * restart; the browser then requests /live.js with a rotated-out token and
+ * gets a 401 with no picker. A changed specifier is a different module id,
+ * which no cache survives.
+ */
+export function svelteRootImportLine(rev) {
+  if (!rev) return SVELTE_ROOT_IMPORT;
+  return "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte?impeccable-live=" + rev + "';";
+}
+
+export function svelteAdapterRev(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 8);
+}
 
 export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   const appHtml = findSvelteKitAppHtml(cwd, config);
@@ -50,7 +73,7 @@ export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, co
   fs.mkdirSync(path.dirname(layoutAbs), { recursive: true });
   const layoutExisted = fs.existsSync(layoutAbs);
   const before = layoutExisted ? fs.readFileSync(layoutAbs, 'utf-8') : defaultSvelteLayout();
-  const after = patchSvelteLayout(before);
+  const after = patchSvelteLayout(before, { rev: svelteAdapterRev(token) });
   fs.writeFileSync(layoutAbs, after, 'utf-8');
 
   return {
@@ -94,15 +117,27 @@ export function removeSvelteKitLiveAdapter({ cwd = process.cwd(), config = null
   };
 }
 
-export function patchSvelteLayout(content) {
+export function patchSvelteLayout(content, { rev = null } = {}) {
   let out = String(content || '');
-  if (!out.includes(SVELTE_ROOT_IMPORT)) {
-    const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
-    if (scriptMatch) {
-      const insertAt = scriptMatch.index + scriptMatch[0].length;
-      out = out.slice(0, insertAt) + '\n  ' + SVELTE_ROOT_IMPORT + out.slice(insertAt);
-    } else {
-      out = `<script>\n  ${SVELTE_ROOT_IMPORT}\n</script>\n\n` + out;
+  const importLine = svelteRootImportLine(rev);
+  if (!out.includes(importLine)) {
+    // An import at an older revision is replaced in place, keeping its
+    // indentation; only a layout with no impeccable import gets an insert.
+    let replaced = false;
+    out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, (line) => {
+      if (replaced) return '';
+      replaced = true;
+      const indent = (line.match(/^[ \t]*/) || [''])[0];
+      return indent + importLine + '\n';
+    });
+    if (!replaced) {
+      const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
+      if (scriptMatch) {
+        const insertAt = scriptMatch.index + scriptMatch[0].length;
+        out = out.slice(0, insertAt) + '\n  ' + importLine + out.slice(insertAt);
+      } else {
+        out = `<script>\n  ${importLine}\n</script>\n\n` + out;
+      }
     }
   }
 
@@ -131,8 +166,8 @@ export function unpatchSvelteLayout(content) {
     'g',
   );
   out = out.replace(blockRe, '$1');
-  out = out.replace(new RegExp('^\\s*' + escapeRegExp(SVELTE_ROOT_IMPORT) + '\\s*\\n?', 'gm'), '');
-  out = out.replace(/<script>\s*<\/script>\s*\n?/g, '');
+  out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, '');
+  out = out.replace(/<script>\s*<\/script>[ \t]*\r?\n?/g, '');
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
@@ -193,6 +228,11 @@ export function buildSvelteLiveRootComponent(port, token) {
     script.src = LIVE_URL;
     script.async = true;
     script.dataset.impeccableLiveScript = 'true';
+    script.onerror = () => console.error(
+      '[impeccable] live.js failed to load from ' + LIVE_URL
+      + ' (helper down, or the token rotated while a stale adapter module was cached).'
+      + ' Re-run the live boot, then reload this page.'
+    );
     document.head.appendChild(script);
 
     return () => {

.agents/skills/impeccable/scripts/live/tanstack-adapter.mjs

@@ -19,7 +19,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildLiveScriptSrc } from '../live-inject.mjs';
+import { buildLiveScriptSrc } from './frameworks/script-src.mjs';
 
 export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
 export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';

.agents/skills/impeccable/scripts/live/ui-core.mjs

@@ -1,180 +0,0 @@
-/**
- * Framework-neutral Impeccable live chrome contract.
- *
- * The production browser bundle is intentionally plain DOM so Svelte, React,
- * Vue, and static adapters can all mount the same chrome. This module is the
- * testable contract/inventory for that bundle; live-browser.js mirrors these
- * values at runtime because it is served as a standalone script.
- */
-
-export const LIVE_CHROME_MOUNT_CONTRACT = Object.freeze([
-  'root',
-  'transport',
-  'state',
-  'actions',
-]);
-
-export const LIVE_UI_SURFACES = Object.freeze([
-  {
-    key: 'global-bottom-bar',
-    ids: [
-      'impeccable-live-global-bar',
-      'impeccable-live-global-bar-brand',
-      'impeccable-live-pick-toggle',
-      'impeccable-live-insert-toggle',
-      'impeccable-live-detect-toggle',
-      'impeccable-live-detect-badge',
-      'impeccable-live-design-toggle',
-      'impeccable-live-page-chat',
-      'impeccable-live-page-chat-input',
-      'impeccable-live-page-chat-voice',
-    ],
-    states: ['rest', 'hover', 'focus-visible', 'pressed', 'active', 'tooltip'],
-  },
-  {
-    key: 'pending-copy-edit-dock',
-    ids: ['impeccable-live-pending-dock'],
-    states: ['closed', 'open', 'hover', 'pressed', 'loading', 'rollback', 'keep-fixing'],
-  },
-  {
-    key: 'element-selection-chrome',
-    ids: [
-      'impeccable-live-highlight',
-      'impeccable-live-tooltip',
-      'impeccable-live-bar',
-      'impeccable-live-selection-pill',
-      'impeccable-live-input',
-      'impeccable-live-configure-voice',
-      'impeccable-live-configure-bar-tooltip',
-    ],
-    states: ['rest', 'hover', 'focus-visible', 'pressed', 'disabled'],
-  },
-  {
-    key: 'action-picker',
-    ids: ['impeccable-live-picker'],
-    states: ['closed', 'open', 'option-hover', 'option-focus'],
-  },
-  {
-    key: 'edit-chrome',
-    ids: ['impeccable-live-edit-badge'],
-    states: ['enabled', 'disabled', 'editing', 'cancel', 'save', 'edited-content'],
-  },
-  {
-    key: 'generating-row',
-    ids: ['impeccable-live-bar', 'impeccable-live-shader'],
-    states: ['action-label', 'animated-dots', 'generating', 'done'],
-  },
-  {
-    key: 'variant-cycling-row',
-    ids: ['impeccable-live-bar', 'impeccable-live-params-panel'],
-    states: ['variant-1', 'variant-2', 'variant-3', 'left-disabled', 'right-disabled', 'dot-click', 'accept', 'discard'],
-  },
-  {
-    key: 'variant-params-panel',
-    ids: ['impeccable-live-params-panel'],
-    states: ['closed', 'open-above', 'open-below', 'range', 'steps', 'toggle'],
-  },
-  {
-    key: 'saving-confirmed-rows',
-    ids: ['impeccable-live-bar'],
-    states: ['saving', 'applying-variant', 'confirmed'],
-  },
-  {
-    key: 'insert-mode-chrome',
-    ids: [
-      'impeccable-live-insert-line',
-      'impeccable-live-insert-placeholder',
-      'impeccable-live-placeholder-resize',
-      'impeccable-live-insert-input',
-      'impeccable-live-insert-voice',
-      'impeccable-live-insert-create',
-      'impeccable-live-insert-create-tooltip',
-    ],
-    states: ['toggle-active', 'line', 'placeholder', 'resize', 'enabled', 'disabled', 'tooltip'],
-  },
-  {
-    key: 'annotation-chrome',
-    ids: [
-      'impeccable-live-annot',
-      'impeccable-live-annot-svg',
-      'impeccable-live-annot-pins',
-      'impeccable-live-annot-clear',
-    ],
-    states: ['overlay', 'drawing', 'pin', 'pin-edit', 'clear'],
-  },
-  {
-    key: 'design-system-panel',
-    ids: ['impeccable-live-design-host'],
-    states: ['closed', 'open', 'tabs', 'token-tiles', 'copy'],
-  },
-  {
-    key: 'toasts-and-errors',
-    ids: ['impeccable-live-toast'],
-    states: ['normal', 'error', 'no-variants-mounted'],
-  },
-  {
-    key: 'css-isolation-boundary',
-    ids: ['impeccable-live-root'],
-    states: ['shadow-root', 'style-tags', 'hostile-css'],
-  },
-]);
-
-export const LIVE_UI_COMPONENT_IDS = Object.freeze([
-  ...new Set(LIVE_UI_SURFACES.flatMap((surface) => surface.ids)),
-]);
-
-export function resolveLiveUiRoot(env = globalThis) {
-  const doc = env?.document;
-  const explicit = env?.__IMPECCABLE_LIVE_UI_ROOT__
-    || env?.window?.__IMPECCABLE_LIVE_UI_ROOT__;
-  if (explicit && typeof explicit.appendChild === 'function') return explicit;
-  return doc?.body || null;
-}
-
-export function getLiveUiElementById(id, env = globalThis) {
-  const doc = env?.document;
-  const root = resolveLiveUiRoot(env);
-  if (!id) return null;
-  if (root?.getElementById) {
-    const found = root.getElementById(id);
-    if (found) return found;
-  }
-  if (root?.querySelector) {
-    const found = root.querySelector('#' + escapeCssIdent(id));
-    if (found) return found;
-  }
-  return doc?.getElementById?.(id) || null;
-}
-
-export function appendToLiveUiRoot(el, env = globalThis) {
-  const root = resolveLiveUiRoot(env);
-  if (!root) throw new Error('Impeccable live UI root is not available');
-  root.appendChild(el);
-  return el;
-}
-
-export function appendStyleToLiveUiRoot(styleEl, env = globalThis) {
-  const doc = env?.document;
-  const root = resolveLiveUiRoot(env);
-  if (root && root !== doc?.body) {
-    root.appendChild(styleEl);
-  } else {
-    (doc?.head || doc?.body || root).appendChild(styleEl);
-  }
-  return styleEl;
-}
-
-export function activeElementDeep(doc = globalThis.document) {
-  let active = doc?.activeElement || null;
-  while (active?.shadowRoot?.activeElement) {
-    active = active.shadowRoot.activeElement;
-  }
-  return active;
-}
-
-function escapeCssIdent(value) {
-  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
-    return CSS.escape(String(value));
-  }
-  return String(value).replace(/([ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~])/g, '\\$1');
-}

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

@@ -34,3 +34,138 @@ export const LIVE_COMMANDS = [
 
 // Action values accepted by the live event protocol, in palette order.
 export const VISUAL_ACTIONS = LIVE_COMMANDS.map((c) => c.value);
+
+/*
+ * ---------------------------------------------------------------------------
+ * Protocol vocabulary
+ * ---------------------------------------------------------------------------
+ * The enums below are the wire contract between the browser overlay, the live
+ * helper server, and the durable session journal. They live here rather than in
+ * the modules that use them so a value cannot be added to the validator without
+ * the store and the server seeing it too.
+ *
+ * live-browser.js still cannot import this file (it is served raw and injected
+ * as an IIFE), so its local phase table repeats the agent-phase names. Anything
+ * the server can broadcast must appear in AGENT_PHASES here first.
+ */
+
+/**
+ * Phases the live server broadcasts as `agent_phase`, in lifecycle order.
+ * Every one of these is emitted by `recordAgentPhase()` in live-server.mjs;
+ * the validator rejects anything else, so a typo in a phase name fails loudly
+ * instead of quietly ranking as an unknown phase in the browser's progress bar.
+ */
+export const AGENT_PHASES = Object.freeze([
+  'picked_up',
+  'scaffolding',
+  'source_ready',
+  'scaffold_fallback',
+  'generation_ready',
+  'first_reviewable',
+  'second_reviewable',
+  'all_variants_ready',
+]);
+
+/** Event types the helper server accepts from the browser over POST /events. */
+export const CLIENT_EVENT_TYPES = Object.freeze([
+  'generate',
+  'accept',
+  'discard',
+  'checkpoint',
+  'agent_phase',
+  'variant_mounted',
+  'variant_mount_failed',
+  'exit',
+  'prefetch',
+  'manual_edits',
+  'steer',
+  'carbonize_cleanup',
+]);
+
+/**
+ * Event types the durable journal applies. A superset of CLIENT_EVENT_TYPES:
+ * the agent-side helpers (live-poll, live-complete) and the server itself
+ * append the rest. An event type missing here lands as `unknown_event_type`
+ * in the snapshot diagnostics.
+ */
+export const JOURNAL_EVENT_TYPES = Object.freeze([
+  'generate',
+  'variant_plan',
+  'detector_waivers',
+  'agent_phase',
+  'variants_ready',
+  'agent_done',
+  'variant_mounted',
+  'variant_mount_failed',
+  'checkpoint',
+  'accept',
+  'accept_intent',
+  'manual_edit_apply',
+  'steer',
+  'steer_done',
+  'carbonize_cleanup',
+  'discard',
+  'discarded',
+  'complete',
+  'agent_error',
+]);
+
+/** Phases the session store assigns to a snapshot. */
+export const SESSION_PHASES = Object.freeze([
+  'new',
+  'generate_requested',
+  'variants_ready',
+  'carbonize_required',
+  'carbonize_cleanup_requested',
+  'manual_edit_apply_requested',
+  'steer_requested',
+  'steer_done',
+  'accept_requested',
+  'discard_requested',
+  'discarded',
+  'completed',
+  'agent_error',
+]);
+
+/** Phases that retire a session from the active list. */
+export const COMPLETED_SESSION_PHASES = Object.freeze(['completed', 'discarded']);
+
+/**
+ * Phases after which a late generation write is a ghost from a canceled cycle.
+ * The store journals such an event as a diagnostic instead of applying it.
+ */
+export const GENERATION_FENCED_SESSION_PHASES = Object.freeze([
+  'accept_requested',
+  'discard_requested',
+  'carbonize_required',
+  'completed',
+  'discarded',
+]);
+
+/**
+ * `reason` values carried on checkpoint events. Not validated (an unknown
+ * reason is journaled, never rejected) because the reason is diagnostic
+ * breadcrumb, not control flow. Two exceptions drive behavior and are split
+ * out below.
+ */
+export const CHECKPOINT_REASONS = Object.freeze([
+  'generate_started',
+  'variants_progress',
+  'variants_ready',
+  'browser_resumed',
+  'browser_resumed_svelte_component',
+  'param_changed',
+  'variant_anchor_missing',
+  'component_preview_anchor_missing',
+  'steer_input_focused',
+  'steer_submitted',
+  'steer_send_failed',
+  'steer_done',
+  'steer_error',
+]);
+
+/** Checkpoint reasons the server reads as variant-publication progress. */
+export const VARIANT_PROGRESS_CHECKPOINT_REASONS = Object.freeze([
+  'variants_progress',
+  'variants_ready',
+]);

.agents/skills/impeccable/scripts/pin.mjs

@@ -21,7 +21,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // All known harness directories
 const HARNESS_DIRS = [
-  '.claude', '.cursor', '.gemini', '.codex', '.agents', '.github', '.grok',
+  '.claude', '.cursor', '.gemini', '.codex', '.agents', '.agent', '.github', '.grok',
   '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev', '.vibe', '.qoder',
 ];
 
@@ -93,15 +93,17 @@ function commandPrefixForSkillsDir(skillsDir) {
   return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
 }
 
-function generatePinnedSkill(command, metadata, commandPrefix) {
+function generatePinnedSkill(command, metadata, commandPrefix, isCodex) {
   const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}impeccable ${command}.`;
   const hint = metadata[command]?.argumentHint || '[target]';
+  const providerFrontmatter = isCodex
+    ? `metadata:\n  argument-hint: "${hint}"`
+    : `argument-hint: "${hint}"\nuser-invocable: true`;
 
   return `---
 name: ${command}
 description: "${desc}"
-argument-hint: "${hint}"
-user-invocable: true
+${providerFrontmatter}
 ---
 
 ${PIN_MARKER}
@@ -128,7 +130,7 @@ function pin(command, projectRoot) {
 
   for (const skillsDir of harnessDirs) {
     const commandPrefix = commandPrefixForSkillsDir(skillsDir);
-    const content = generatePinnedSkill(command, metadata, commandPrefix);
+    const content = generatePinnedSkill(command, metadata, commandPrefix, commandPrefix === '$');
     // Check if skill already exists (and isn't a pin)
     const skillDir = join(skillsDir, command);
     if (existsSync(skillDir)) {

.agents/skills/impeccable/scripts/serve-question.mjs

@@ -79,6 +79,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { openSystemBrowser } from './lib/open-system-browser.mjs';
 
 function arg(name, fallback = null) {
   const i = process.argv.indexOf(`--${name}`);
@@ -143,7 +144,7 @@ if (hasFlag('schema')) {
     title: 'Choose the visual world',
     question: 'The roll assigned Fillmore Handbill. Keep it, take an alternate, or re-roll.',
     options: [
-      { id: 'assigned', label: 'Fillmore Handbill', kicker: 'THE ROLL', lineage: '1966-71 Fillmore psychedelic handbills', thesis: 'The gig poster that treats every release like a one-night stand.', palette: ['#e8452c', '#f5d64c', '#1b2a52', '#f3ead8'], materials: ['letterpress', 'split-fountain ink'], viewport: 'A full-bleed dated bill with the product name in warped display type.', risk: 'Reads nostalgic when the type is set timidly.', sketch: '.impeccable/sketches/assigned.webp', hero: 'https://impeccable.style/worlds/cards/fillmore-handbill-hero.webp', board: 'https://impeccable.style/worlds/cards/fillmore-handbill.webp' },
+      { id: 'assigned', label: 'Fillmore Handbill', kicker: 'THE ROLL', lineage: '1966-71 Fillmore psychedelic handbills', thesis: 'The gig poster that treats every release like a one-night stand.', palette: ['#e8452c', '#f5d64c', '#1b2a52', '#f3ead8'], materials: ['letterpress', 'split-fountain ink'], viewport: 'A full-bleed dated bill with the product name in warped display type.', risk: 'Reads nostalgic when the type is set timidly.', sketch: '.impeccable/sketches/assigned.webp', hero: 'https://impeccable.style/worlds/cards/posters-covers-sleeves-fillmore-handbill-hero.webp', board: 'https://impeccable.style/worlds/cards/posters-covers-sleeves-fillmore-handbill.webp' },
       { id: 'challenger-teletext', label: 'Teletext Service', lineage: 'broadcast teletext magazines', thesis: 'The catalog as a broadcast index: pages, not sections.', case: 'Fuses cleanly: releases map to numbered pages.', sketch: '.impeccable/sketches/challenger-teletext.webp', hero: 'https://impeccable.style/worlds/cards/broadcast-programming-teletext-service-hero.webp' },
     ],
     reroll: true,
@@ -151,7 +152,7 @@ if (hasFlag('schema')) {
     canonCard: { label: 'The category standard', thesis: 'What this category ships, executed impeccably.', viewport: 'The arrangement a visitor expects, at full craft.', sketch: '.impeccable/sketches/canon.webp' },
     steer: true,
   }, null, 2));
-  console.log('\nOption ids return verbatim in ANSWER; "reroll" and "canon" are reserved. hero/board/sketch accept URLs or local paths; sketch slots may point at files that do not exist yet (serve first, generate after; the page polls until they land, so never block serving on generation). hero on a challenger is the inspiration it draws from and renders picture-in-picture beside the sketch, never as the promise of the build. canonCard renders the standing exit as a subordinate card with the same anatomy; without it, canon stays a quiet footer action. Include canon only for visual-direction rounds; never present it as your own recommendation. Keep thesis and each fact to one short sentence: the card front shows thesis, identity, and a two-line risk, while first viewport and the case read on the card back behind the Details chip, so long facts cost the reader a flip, not the page its scanability.');
+  console.log('\nOption ids return verbatim in ANSWER; "reroll" and "canon" are reserved. hero/board/sketch accept URLs or local paths; sketch slots may point at files that do not exist yet (serve first, generate after; the page polls until they land, so never block serving on generation). hero on a challenger is the inspiration it draws from and renders picture-in-picture beside the sketch, never as the promise of the build. canonCard renders the standing exit as a subordinate card with the same anatomy; without it, canon stays a quiet footer action. Include canon only for visual-direction rounds; never present it as your own recommendation. Keep thesis and each fact to one short sentence: the card front shows thesis, identity, and a two-line risk, while first viewport and the case read on the card back behind the Details chip, so long facts cost the reader a flip, not the page its scanability. A card with no imagery at all has no back; its full read renders on the front, so a text-only round loses nothing. Sketch aspect follows the surface: portrait at device viewport for native or mobile-first surfaces, landscape otherwise; the page adapts its cards to either.');
   process.exit(0);
 }
 
@@ -161,15 +162,25 @@ if (hasFlag('wait')) {
   const pollSec = Number(arg('poll', '60'));
   const deadline = Date.now() + pollSec * 1000;
   const answered = () => fs.existsSync(answerFile(key));
+  // Liveness must survive sandboxes: a sandboxed --wait cannot signal the
+  // daemon (kill throws EPERM even for a living process), so a fresh page
+  // heartbeat in the state file is the primary proof of life, the kill probe
+  // is secondary, and EPERM specifically means "exists, but the sandbox
+  // blocks signals", never "dead". Treating EPERM as death told one session
+  // the user had walked away while they were still reading the board.
   const alive = () => {
-    try { process.kill(JSON.parse(fs.readFileSync(stateFile(key), 'utf8')).pid, 0); return true; }
-    catch { return false; }
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile(key), 'utf8'));
+      if (state.lastBeat && Date.now() - state.lastBeat < 12000) return true;
+      try { process.kill(state.pid, 0); return true; }
+      catch (err) { return err.code === 'EPERM'; }
+    } catch { return false; }
   };
   let sawClose = false;
   while (Date.now() < deadline) {
     if (answered()) break;
     if (!alive()) {
-      console.log('serve-question: the question server is gone with no answer');
+      console.log('serve-question: the question server is gone with no answer. This is a server failure, not a user decision: restart it with --start and the same payload, reopen the URL for the user, and wait again. Never proceed without their choice while their browser session is open.');
       process.exit(2);
     }
     try {
@@ -311,7 +322,11 @@ function page() {
   // and material tags give a text-only direction an immediate identity that
   // no generation luck can distort.
   const fact = (label, value, cls = '') => value ? `<p class="fact${cls ? ` ${cls}` : ''}"><span class="fact-label">${label}</span>${esc(value)}</p>` : '';
-  const hasBack = (option) => Boolean(option.viewport || option.case || (option.boardSrc && option.heroSrc));
+  const hasMedia = (option) => Boolean(option.sketchSrc || option.heroSrc || option.boardSrc);
+  // The back exists to keep long facts off a card whose front is an image;
+  // a card with no art has no flip chip to reach it, so it gets no back and
+  // the full read lives on the front instead.
+  const hasBack = (option) => hasMedia(option) && Boolean(option.viewport || option.case || (option.boardSrc && option.heroSrc));
   const anatomy = (option) => {
     const rows = [];
     if (option.thesis) rows.push(`<p class="thesis">${esc(option.thesis)}</p>`);
@@ -326,7 +341,15 @@ function page() {
     // The front carries only what the choice needs: thesis, identity, and the
     // honest risk clamped to two lines. First viewport and the case read on
     // the card's back; once the sketch lands, the first viewport is a picture.
-    rows.push(fact('Risk', option.risk, 'clamp'));
+    // With no art there is no back, so the full read fills the room the
+    // image would have taken.
+    if (hasMedia(option)) {
+      rows.push(fact('Risk', option.risk, 'clamp'));
+    } else {
+      rows.push(fact('First viewport', option.viewport));
+      rows.push(fact('The case', option.case));
+      rows.push(fact('Risk', option.risk));
+    }
     if (!option.thesis && option.body) rows.push(`<p class="detail">${esc(option.body)}</p>`);
     else if (option.body && option.thesis && !hasBack(option)) rows.push(`<p class="detail more">${esc(option.body)}</p>`);
     return rows.join('\n            ');
@@ -352,8 +375,11 @@ function page() {
           </div>`;
     }
     if (option.heroSrc || option.boardSrc) {
-      return `<div class="media">
+      // Without a sketch the catalog art is the card's face; it stays a
+      // labeled reference so it never reads as the promise of the build.
+      return `<div class="media" title="Inspiration: the world this direction draws from. Your page will not look like this image.">
             <img src="${esc(option.heroSrc || option.boardSrc)}" alt="">
+            <p class="media-label">inspiration</p>
             <div class="chips">${expandChip}${details}</div>
           </div>`;
     }
@@ -441,7 +467,10 @@ function page() {
      its axis with snap points and the arrows page it card by card. */
   .grid { --deck-inset: max(clamp(1rem, 5vw, 4rem), calc((100vw - 90rem) / 2)); display: flex; gap: 1.6rem; width: 100%; overflow-x: auto; overflow-y: hidden; scroll-snap-type: x mandatory; scrollbar-width: none; padding: 6px var(--deck-inset); scroll-padding-inline: var(--deck-inset); align-items: stretch; }
   .grid::-webkit-scrollbar { display: none; }
-  .grid > .card { flex: 0 0 clamp(20rem, 27vw, 27rem); scroll-snap-align: center; }
+  /* Wide enough that the sketch carries the card: at 27vw the imagery read
+     as a thumbnail above a column of copy, and the copy won the attention
+     contest the sketch is supposed to win. */
+  .grid > .card { flex: 0 0 clamp(24rem, 34vw, 34rem); scroll-snap-align: center; }
   .nav { position: absolute; z-index: 6; width: 42px; height: 42px; display: flex; align-items: center; justify-content: center; border-radius: 50%; background: oklch(7% 0.006 95 / 0.78); border: 1px solid var(--ks-rule); color: var(--ks-kinpaku); cursor: pointer; backdrop-filter: blur(6px); transition: border-color .2s, color .2s, opacity .2s; }
   .nav:hover { border-color: var(--ks-kinpaku-deep); color: var(--ks-kinpaku-pale); }
   .nav[disabled] { opacity: .25; cursor: default; }
@@ -491,8 +520,13 @@ function page() {
      region entirely instead of reserving a blank 16:9 void. */
   .face.text-only .kicker { position: static; align-self: flex-start; margin: 14px 0 0 14px; }
   .face.text-only .body { padding-top: 12px; }
-  .media { position: relative; width: 100%; aspect-ratio: 16/9; flex: none; }
+  /* 16/10 matches the landscape sketch frame; portrait art overrides the
+     slot with its own exact ratio at load (see the load listener), and the
+     deck narrows so portrait cards line up side by side. */
+  .media { position: relative; width: 100%; aspect-ratio: 16/10; flex: none; }
+  .grid.portrait-media > .card { flex-basis: clamp(14rem, 19vw, 19rem); }
   .media img { width: 100%; height: 100%; object-fit: cover; display: block; background: linear-gradient(100deg, var(--ks-graphite) 40%, var(--ks-graphite-2) 50%, var(--ks-graphite) 60%); }
+  .media > img:not([hidden]) { cursor: zoom-in; }
   .face.back { background: var(--ks-lacquer-raised); }
   .back-bar { margin-top: auto; background: var(--ks-lacquer-raised); }
   .hero-blank { width: 100%; height: 100%; background: linear-gradient(100deg, var(--ks-graphite) 40%, var(--ks-graphite-2) 50%, var(--ks-graphite) 60%); }
@@ -529,6 +563,17 @@ function page() {
   .pip figcaption { position: absolute; left: 0; right: 0; bottom: 0; font-family: var(--ks-mono); font-size: .5rem; letter-spacing: .2em; text-transform: uppercase; color: var(--ks-text); text-align: center; padding: 3px 0 4px; background: oklch(7% 0.006 95 / 0.72); backdrop-filter: blur(3px); }
   .pip:hover { left: 0; bottom: 0; width: 100%; height: 100%; border-radius: 0; z-index: 3; }
   .sketch-note { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; font-family: var(--ks-mono); font-size: .66rem; letter-spacing: .22em; text-transform: uppercase; color: var(--ks-text-faint); }
+  /* Catalog art standing in for a sketchless card is a reference, and says so
+     on its face; the same pill later carries "artwork unavailable". */
+  .media-label { position: absolute; z-index: 2; left: 10px; bottom: 10px; margin: 0; font-family: var(--ks-mono); font-size: .5rem; letter-spacing: .2em; text-transform: uppercase; color: var(--ks-text); padding: 3px 8px 4px; background: oklch(7% 0.006 95 / 0.72); border: 1px solid var(--ks-rule); border-radius: 4px; backdrop-filter: blur(3px); }
+  /* Art that never arrives collapses to the card's own palette (painted
+     inline from its swatches) instead of sitting as a dark void wearing a
+     zoom cursor; the scrim keeps the label legible over saturated fields,
+     passes clicks through, and the flip chips stay above it. A card with no
+     palette falls back to the quiet graphite field. */
+  .media.unavailable { background: linear-gradient(100deg, var(--ks-graphite) 40%, var(--ks-graphite-2) 50%, var(--ks-graphite) 60%); }
+  .media.unavailable::after { content: ""; position: absolute; inset: 0; z-index: 1; background: oklch(10% 0.008 95 / 0.45); pointer-events: none; }
+  .media.unavailable .chips { z-index: 2; }
   /* A stand-in is honest about being one: dimmed, labeled, and replaced by
      the real sketch whenever it lands. */
   .media.stand-in img.sketch { filter: brightness(.72) saturate(.85); }
@@ -691,6 +736,36 @@ function page() {
     tryLoad();
   });
 
+  // A declared image that never loads (missing catalog asset, offline shell)
+  // must not sit as a dark void: the slot collapses to the card's own
+  // palette, labeled honestly, and the card competes on its facts. Sketch
+  // slots are excluded; their polling owns the wait.
+  const artFailed = (img) => {
+    const m = img.closest('.media');
+    if (!m || m.classList.contains('sketching') || m.classList.contains('unavailable')) return;
+    m.classList.add('unavailable');
+    const colors = [...(img.closest('.card')?.querySelectorAll('.swatches i') || [])].map(i => i.style.background).filter(Boolean);
+    if (colors.length) m.style.background = 'linear-gradient(135deg, ' + colors.map((c, i) => c + ' ' + Math.round(i * 100 / colors.length) + '% ' + Math.round((i + 1) * 100 / colors.length) + '%').join(', ') + ')';
+    m.querySelector('.media-label')?.remove();
+    m.querySelector('.chip.expand')?.remove();
+    m.removeAttribute('title');
+    img.remove();
+    const label = document.createElement('p');
+    label.className = 'media-label';
+    label.textContent = 'artwork unavailable';
+    m.appendChild(label);
+  };
+  document.querySelectorAll('.media:not(.sketching) > img').forEach(img => {
+    if (img.complete && img.naturalWidth === 0 && img.getAttribute('src')) artFailed(img);
+    else img.addEventListener('error', () => artFailed(img), { once: true });
+  });
+  // A broken inspiration PIP just leaves; nothing depends on it.
+  document.querySelectorAll('.pip img').forEach(img => {
+    const gone = () => img.closest('.pip')?.remove();
+    if (img.complete && img.naturalWidth === 0) gone();
+    else img.addEventListener('error', gone, { once: true });
+  });
+
   // Inspiration PIP opens the full catalog card in the lightbox.
   document.querySelectorAll('.pip').forEach(p => p.addEventListener('click', (e) => {
     e.stopPropagation();
@@ -759,6 +834,30 @@ function page() {
     lightbox.hidden = false;
     requestAnimationFrame(() => lightbox.classList.add('open'));
   }));
+  // Portrait art (native / mobile-first surfaces): the slot takes the
+  // image's own ratio so nothing crops, and the whole deck narrows so
+  // portrait cards sit side by side. Load events don't bubble; capture.
+  document.addEventListener('load', (e) => {
+    const img = e.target;
+    if (!(img instanceof HTMLImageElement) || !img.matches('.media > img')) return;
+    if (img.naturalHeight > img.naturalWidth * 1.05) {
+      const m = img.closest('.media');
+      m.classList.add('portrait');
+      m.style.aspectRatio = img.naturalWidth + ' / ' + img.naturalHeight;
+      document.querySelector('.grid')?.classList.add('portrait-media');
+    }
+  }, true);
+
+  // The whole image is the zoom target, not just the expand chip; the chip
+  // stays as the visible affordance. Chip and PIP handlers stop propagation,
+  // so this fires only for clicks on the art itself.
+  document.querySelectorAll('.media').forEach(m => m.addEventListener('click', () => {
+    const img = m.querySelector(':scope > img:not([hidden])');
+    if (!img || !img.getAttribute('src')) return;
+    lightboxImg.src = img.getAttribute('src');
+    lightbox.hidden = false;
+    requestAnimationFrame(() => lightbox.classList.add('open'));
+  }));
   const closeLightbox = () => { lightbox.classList.remove('open'); setTimeout(() => { lightbox.hidden = true; }, 250); };
   lightbox.addEventListener('click', closeLightbox);
   document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && !lightbox.hidden) closeLightbox(); });
@@ -878,8 +977,7 @@ server.listen(portArg, '127.0.0.1', () => {
     console.log('Waiting for the user to choose in the browser (Ctrl-C aborts)...');
   }
   if (!hasFlag('no-open')) {
-    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    try { spawn(opener, [url], { stdio: 'ignore', detached: true }).unref(); } catch { /* URL printed anyway */ }
+    openSystemBrowser(url);
   }
   if (timeoutSec > 0) {
     setTimeout(() => {

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

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

.claude/agents/impeccable-asset-producer.md

@@ -18,7 +18,7 @@ Do not redesign. Preserve the reference's visual role, silhouette, palette, ligh
 
 ## Decision Sketches
 
-When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss. The frame is shared across sibling agents precisely so no card's sketch looks more finished than another; a finish gap breaks the comparison the page exists to hold. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more.
+When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame, including its aspect: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss; a native app or mobile-first surface is a portrait frame at its device viewport, never a landscape default. The frame is shared across siblings so no sketch looks more finished than another; a finish gap breaks the comparison. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more. Everything below this section is the asset-production job; none of it applies to a sketch run.
 
 ## Input Contract
 
@@ -49,19 +49,17 @@ Ask blockers once, globally. Missing source path/crops or output directory block
 1. Inventory the full approved mock or every assigned crop.
 2. Put each visual role in exactly one bucket:
    - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
-   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `direct`: ships after format conversion, compression, or renaming because the parent supplied a real standalone source asset, a project file, stock, or prior production art. A crop from the approved mock is never `direct`, whatever its apparent size.
    - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
-3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+3. Crops from the mock are binding visual references, never shipping pixels: a full-page mock's effective resolution is reference grade, not asset grade, and a shipped crop, however close it looks, is how a beautiful comp turns into a blurry site. Every mock-derived asset goes through `produce` as a clean regeneration.
 4. Give the parent an execution order for the `produce` bucket.
 5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
-6. Treat every crop as binding reference. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
+6. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
 
 7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
 8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
-9. Save outputs non-destructively in the requested project directory.
-10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
-
-Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: after every generation, run `node .claude/skills/impeccable/scripts/embed-prompt.mjs <asset> --prompt "<the prompt used>"` so the prompt is embedded in the image itself, because the build thread composes what you made and needs to know what it is looking at, and the embedding survives copies where sidecars get lost.
+10. Compare each output against its source crop, opening every image by its workspace-relative path; sandboxed viewers reject absolute paths. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
 
 Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
 
@@ -69,8 +67,6 @@ Use `semantic` for dashboards, charts, controls, screenshots of whole UI section
 
 Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
 
-For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
-
 ## Prompt Pattern
 
 Use this shape for image-to-image work:
@@ -84,7 +80,7 @@ Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, persp
 Do not add new objects. Do not change the concept. Do not redesign the composition.
 ```
 
-For transparent cutouts, use a chroma-key workflow by default: generate on a flat color that cannot appear in the subject, then post-process to alpha; use true native transparency only when the tool supports it or the parent authorizes it.
+For transparent cutouts: use true alpha when the tool supports it; otherwise generate on a flat chroma-key color that cannot appear in the subject and post-process that color to alpha before shipping the PNG/WebP. Never ship the keyed background as the final asset.
 
 ## Output Contract
 

.claude/agents/impeccable-documenter.md

@@ -22,6 +22,7 @@ Expect: the project root; the artifact path(s); the direction contract text (THE
 2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence.
 3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system.
 4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear.
+5. Never canonize a craft-floor refusal into the system: an element the floor bans (kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces) is recorded in your not-canonized line as a defect the build carries, never as a design-system rule for future surfaces to inherit. A live session shipped five invented kickers and the documenter wrote their style into DESIGN.md; that is how one violation becomes the house style.
 
 ## Output Contract
 

.claude/agents/impeccable-finish-reviewer.md

@@ -12,26 +12,31 @@ You are the finishing reviewer for an Impeccable build: fresh eyes on a done art
 
 You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable.
 
-You run under a hard turn ceiling that ends the run without warning, and a run that ends before the five sections are written returns nothing; a review built from what you saw beats a perfect review that never arrives. So treat reading as an allowance, not a prerequisite: read only the provided inputs, never the skill's own reference files, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
+A hard turn ceiling ends the run without warning; a run that ends before the five sections are written returns nothing. Treat reading as an allowance: read only the provided inputs plus the craft floor, never any other skill reference file, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
 
 ## Input Contract
 
-Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: the contract is the builder's abstraction of the comp, and a review anchored on it inherits whatever that abstraction dropped.
+Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path; and the skill's `reference/craft-floor.md` path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: a review anchored on the contract inherits whatever the builder's abstraction dropped.
 
 ## Checks, in order
 
-1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding.
-2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
+1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. When comps exist under `.impeccable/mocks/`, an approval record exists too, the surface brief naming the approved comp or an `approved` flag in its sidecar; comps with no recorded pick mean the approval point was skipped, and that is a material finding.
+2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, the primary action's treatment (a CTA the comp physically works, dissolves, or stamps is a signature element, and its plain-rectangle rendition is contradicted), navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. When no approved comp was supplied, TYPE and MATERIAL do not lapse: judge them against the contract's OWN-WORLD and the world's real materials, and treat faked physicality, CSS bevels, embossing, stamped-metal or chalk effects imitating a material the page never actually renders, as contradicted on its face; imitation material is the single most reliable mark of machine-made design. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. When MATERIAL is contradicted on the focal element, or contradiction is the page rather than the exception, stop ordering repairs: make the first material fix a rebuild directive naming the comp regions to re-derive and the assets to produce; a list of patches against a rejected page launders the rejection into an approval. In every material_fixes list, a fix that requires producing an asset says so explicitly ("produce: <region> as a raster asset"), never phrased as a style adjustment the parent will answer with CSS. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
 3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition.
 4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport.
 5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind other paint is a compliance token, not a shipped material.
+6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp, because the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and the last two live sessions shipped five kickers past a reviewer that never looked.
 
 Do not run a second detector pass; mechanical findings belong to the parent's hooks.
 
-## Verdict Pass
+## Disposition
 
-When the parent returns with post-fix recaptures, you are scoring, not re-hunting. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear").
+The first line of your return is `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. It is derived, never felt: rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it.
 
 ## Output Contract
 
-Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+Return the disposition line first, then exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+
+## Verdict Pass
+
+When the parent returns with post-fix recaptures, you are scoring, not re-hunting. The parent's narration of what was fixed is not evidence; a claimed fix you cannot see in the recaptures is unresolved. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear"), and end with the disposition line recomputed against what remains open; unresolved or partial material findings can never recompute to ship.

.claude/agents/impeccable-manual-edit-applier.md

@@ -21,12 +21,12 @@ Expect a self-contained handoff with:
 - Event id.
 - Page URL.
 - Optional chunk metadata.
-- Optional repair metadata. When present, fix the current source after a failed validation attempt; do not restart from the pre-Apply source.
+- Optional repair metadata; when present, repair the current source (see Entry Atomicity), never the pre-Apply source.
 - Optional deadline.
 - The current event `batch`.
 - Optional `evidencePath`.
 
-The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not run `live-commit-manual-edits.mjs` for a leased manual Apply event. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
+The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
 
 ## Workflow
 

.claude/settings.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "[ ! -f \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\" ] || ! { node -e \"process.exit(parseInt(process.versions.node,10)>=22?0:1)\" 2>/dev/null || { D=\"$HOME/.impeccable\"; [ -f \"$D/node-unsupported\" ] || { mkdir -p \"$D\" 2>/dev/null && : > \"$D/node-unsupported\" 2>/dev/null && printf '%s' '{\"systemMessage\":\"The impeccable design hook is not running: no Node 22 or newer on PATH. Install one, or remove the impeccable hook from your harness settings.\"}'; }; exit 0; }; } || node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
+            "command": "[ ! -f \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\" ] || ! { node -e \"process.exit(Math.min(parseInt(process.versions.node,10),22)===22?0:1)\" 2>/dev/null || { D=\"$HOME/.impeccable\"; [ -f \"$D/node-unsupported\" ] || { mkdir -p \"$D\" 2>/dev/null && : > \"$D/node-unsupported\" 2>/dev/null && printf '%s' '{\"systemMessage\":\"The impeccable design hook is not running: no Node 22 or newer on PATH. Install one, or remove the impeccable hook from your harness settings.\"}'; }; exit 0; }; } || node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
             "timeout": 5,
             "statusMessage": "Checking UI changes"
           }
@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "[ ! -f \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\" ] || ! { node -e \"process.exit(parseInt(process.versions.node,10)>=22?0:1)\" 2>/dev/null || { D=\"$HOME/.impeccable\"; [ -f \"$D/node-unsupported\" ] || { mkdir -p \"$D\" 2>/dev/null && : > \"$D/node-unsupported\" 2>/dev/null && printf '%s' '{\"systemMessage\":\"The impeccable design hook is not running: no Node 22 or newer on PATH. Install one, or remove the impeccable hook from your harness settings.\"}'; }; exit 0; }; } || node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
+            "command": "[ ! -f \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\" ] || ! { node -e \"process.exit(Math.min(parseInt(process.versions.node,10),22)===22?0:1)\" 2>/dev/null || { D=\"$HOME/.impeccable\"; [ -f \"$D/node-unsupported\" ] || { mkdir -p \"$D\" 2>/dev/null && : > \"$D/node-unsupported\" 2>/dev/null && printf '%s' '{\"systemMessage\":\"The impeccable design hook is not running: no Node 22 or newer on PATH. Install one, or remove the impeccable hook from your harness settings.\"}'; }; exit 0; }; } || node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
             "timeout": 30,
             "statusMessage": "Design deep pass"
           }

.claude/skills/impeccable/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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: 4.0.3
+version: 4.0.4
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · init|document|extract|live] [target]"
+argument-hint: "[shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · init|document|extract|live] [target]"
 license: Apache 2.0
 allowed-tools:
   - Bash(npx impeccable *)

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

@@ -12,6 +12,7 @@ Each of these is a check on the built result, not an intention. Run them togethe
 - **Type:** body measure 65–75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale and weight steps. Run the real copy at every breakpoint and fix what overflows.
 - **Motion:** one authored moment, not scattered effects and not one identical entrance on every section. Exponential ease-out from an already-visible default. Reach past transform and opacity: blur, backdrop-filter, clip-path, mask, and shadow belong to the palette when they stay smooth.
 - **States:** hover, disabled, loading, error, empty. Plus real content, working controls, responsive composition, keyboard focus.
+- **Browser surfaces:** the parts you did not draw still carry the design. Text selection, the caret, custom scrollbars, focus rings, underline offset, and the numerals in tabular data all ship with browser defaults that belong to no design system. Theme them from the palette. This is the cheapest signal that a page was built rather than assembled, and the one models skip most reliably.
 - **Copy:** the product's own language. Controls name their action; errors name the problem and the recovery.
 - **Coverage:** every brief requirement present and findable within seconds.
 
@@ -32,8 +33,11 @@ Surface habits:
 - Gradient text. Emphasis comes from weight or size.
 - Glass and blur as decoration rather than as a specific effect.
 - A colored `border-left` or `border-right` above 1px on cards, list items, callouts, or alerts.
+- Hard offset shadows (`box-shadow: 4px 4px 0`) outside a world that is actually neobrutalist. The zero-blur block shadow is a costume, not a depth system; a world that did not choose it never earns it as a default.
 - Sparklines, progress rings, and soft-shadowed rounded rectangles standing in for content.
 - Monospace as a costume for "technical" rather than for code, data, or measurement.
+- A system display face (Impact, Arial Black, the platform sans) as the display voice of an own-world page. Source and self-host a face whose character matches the approved lettering; the closest installed font is a failure, not a fallback.
+- Unicode glyphs or emoji standing in for an icon system. Icons are drawn, from a real library or authored SVG, in one consistent stroke and weight.
 - Light or dark picked by category. Pick it from the use scene: who, where, under what ambient light.
 
 The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit.

.claude/skills/impeccable/reference/degraded/asset-producer.md

@@ -13,7 +13,7 @@ Do not redesign. Preserve the reference's visual role, silhouette, palette, ligh
 
 ## Decision Sketches
 
-When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss. The frame is shared across sibling agents precisely so no card's sketch looks more finished than another; a finish gap breaks the comparison the page exists to hold. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more.
+When the parent hands you a decision card packet instead of an approved mock, the job is one sketch: one card, one file, written to the card's declared `sketch` path the moment it renders. The parent runs several of you in parallel, one per card, so your entire contract is this card; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; a card too thin to brief a sketch is reported back, not padded from imagination. Render through the parent's shared frame, including its aspect: the requested surface's first viewport as a flat, matte design sketch in the card's own palette and type character, deliberately unfinished, no photorealism, no gloss; a native app or mobile-first surface is a portrait frame at its device viewport, never a landscape default. The frame is shared across siblings so no sketch looks more finished than another; a finish gap breaks the comparison. The only legible text is the product's real name and one real headline; greek every other text region into indistinct lines, because an invented spec, price, or date in a sketch is a claim PRODUCT.md never made. Return one line naming the path and any deviation, nothing more. Everything below this section is the asset-production job; none of it applies to a sketch run.
 
 ## Input Contract
 
@@ -44,19 +44,17 @@ Ask blockers once, globally. Missing source path/crops or output directory block
 1. Inventory the full approved mock or every assigned crop.
 2. Put each visual role in exactly one bucket:
    - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
-   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `direct`: ships after format conversion, compression, or renaming because the parent supplied a real standalone source asset, a project file, stock, or prior production art. A crop from the approved mock is never `direct`, whatever its apparent size.
    - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
-3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+3. Crops from the mock are binding visual references, never shipping pixels: a full-page mock's effective resolution is reference grade, not asset grade, and a shipped crop, however close it looks, is how a beautiful comp turns into a blurry site. Every mock-derived asset goes through `produce` as a clean regeneration.
 4. Give the parent an execution order for the `produce` bucket.
 5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
-6. Treat every crop as binding reference. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
+6. Use the harness's native image tool by default when generation or editing is needed; otherwise use the skill's generate-image.mjs.
 
 7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
 8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
-9. Save outputs non-destructively in the requested project directory.
-10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
-
-Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+9. Save outputs non-destructively in the requested project directory, and leave the intent with the file: after every generation, run `node .claude/skills/impeccable/scripts/embed-prompt.mjs <asset> --prompt "<the prompt used>"` so the prompt is embedded in the image itself, because the build thread composes what you made and needs to know what it is looking at, and the embedding survives copies where sidecars get lost.
+10. Compare each output against its source crop, opening every image by its workspace-relative path; sandboxed viewers reject absolute paths. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
 
 Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
 
@@ -64,8 +62,6 @@ Use `semantic` for dashboards, charts, controls, screenshots of whole UI section
 
 Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
 
-For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
-
 ## Prompt Pattern
 
 Use this shape for image-to-image work:
@@ -79,7 +75,7 @@ Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, persp
 Do not add new objects. Do not change the concept. Do not redesign the composition.
 ```
 
-For transparent cutouts, use a chroma-key workflow by default: generate on a flat color that cannot appear in the subject, then post-process to alpha; use true native transparency only when the tool supports it or the parent authorizes it.
+For transparent cutouts: use true alpha when the tool supports it; otherwise generate on a flat chroma-key color that cannot appear in the subject and post-process that color to alpha before shipping the PNG/WebP. Never ship the keyed background as the final asset.
 
 ## Output Contract
 

.claude/skills/impeccable/reference/degraded/documenter.md

@@ -17,6 +17,7 @@ Expect: the project root; the artifact path(s); the direction contract text (THE
 2. Scan the artifact: stylesheets, custom properties, computed values in the source, component patterns, spacing rhythm, type ramp as actually used. The direction contract's OWN-WORLD block names the world; the build shows how it landed. Where they diverge, the build wins and the prose may note the divergence.
 3. Write DESIGN.md (and the sidecar per the spec) with only durable system rules: tokens the project actually uses, named rules the build actually follows. Skip one-off values; a token used once is not a system.
 4. Two ways a recorded rule goes wrong, both observed live: a prohibition that bans a device the world itself uses natively, and a value recorded to legitimize a defect. Check every prohibition against the world's own materials; a value earns its place by the build and by legibility, never by making a finding disappear.
+5. Never canonize a craft-floor refusal into the system: an element the floor bans (kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces) is recorded in your not-canonized line as a defect the build carries, never as a design-system rule for future surfaces to inherit. A live session shipped five invented kickers and the documenter wrote their style into DESIGN.md; that is how one violation becomes the house style.
 
 ## Output Contract
 

.claude/skills/impeccable/reference/degraded/finish-reviewer.md

@@ -7,26 +7,31 @@ You are the finishing reviewer for an Impeccable build: fresh eyes on a done art
 
 You have no browser. Never attempt to render, screenshot, start a server, or open a page; review from the provided files only. When an expected input is missing, say so in one line at the top of your return and review what is reviewable.
 
-You run under a hard turn ceiling that ends the run without warning, and a run that ends before the five sections are written returns nothing; a review built from what you saw beats a perfect review that never arrives. So treat reading as an allowance, not a prerequisite: read only the provided inputs, never the skill's own reference files, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
+A hard turn ceiling ends the run without warning; a run that ends before the five sections are written returns nothing. Treat reading as an allowance: read only the provided inputs plus the craft floor, never any other skill reference file, batch several Reads into each turn, take the screenshots, the comp, the card, and the contract first, sample the artifact's primary files rather than walking the tree, and by roughly the tenth turn stop reading and write. Name whatever went unread in the line above the sections.
 
 ## Input Contract
 
-Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: the contract is the builder's abstraction of the comp, and a review anchored on it inherits whatever that abstraction dropped.
+Expect: the original request; the confirmed user answers; the artifact path(s); desktop and mobile screenshot paths captured by the parent; the direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; existing hook or detector findings; the chosen world's QUALITY BAR card paths and the approved comp path; and the skill's `reference/craft-floor.md` path. When the harness can view images, open the screenshots, the comp, and the card first, and inventory the comp's salient elements in your own words before reading the direction contract or any builder-authored summary: a review anchored on the contract inherits whatever the builder's abstraction dropped.
 
 ## Checks, in order
 
-1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding.
-2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
+1. **Persistence.** PRODUCT.md exists. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. When comps exist under `.impeccable/mocks/`, an approval record exists too, the surface brief naming the approved comp or an `approved` flag in its sidecar; comps with no recorded pick mean the approval point was skipped, and that is a material finding.
+2. **Fidelity.** Against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, the primary action's treatment (a CTA the comp physically works, dissolves, or stamps is a signature element, and its plain-rectangle rendition is contradicted), navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Two rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement, because medium is part of the promise. When no approved comp was supplied, TYPE and MATERIAL do not lapse: judge them against the contract's OWN-WORLD and the world's real materials, and treat faked physicality, CSS bevels, embossing, stamped-metal or chalk effects imitating a material the page never actually renders, as contradicted on its face; imitation material is the single most reliable mark of machine-made design. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. When MATERIAL is contradicted on the focal element, or contradiction is the page rather than the exception, stop ordering repairs: make the first material fix a rebuild directive naming the comp regions to re-derive and the assets to produce; a list of patches against a rejected page launders the rejection into an approval. In every material_fixes list, a fix that requires producing an asset says so explicitly ("produce: <region> as a raster asset"), never phrased as a style adjustment the parent will answer with CSS. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement.
 3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition.
 4. **Contract, promise by promise.** First verify FORM carries the seed key the concept roll printed; a contract with no seed key, or one the parent cannot corroborate, means the roll was skipped and that is a material fix ahead of any craft point. Then, for each of the five blocks, does the render keep the promise? Apply the memory test to the first viewport.
 5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every image-native region of the approved comp shipped as a real asset, not a gradient standing in for one, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind other paint is a compliance token, not a shipped material.
+6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp, because the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and the last two live sessions shipped five kickers past a reviewer that never looked.
 
 Do not run a second detector pass; mechanical findings belong to the parent's hooks.
 
-## Verdict Pass
+## Disposition
 
-When the parent returns with post-fix recaptures, you are scoring, not re-hunting. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear").
+The first line of your return is `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. It is derived, never felt: rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it.
 
 ## Output Contract
 
-Return exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+Return the disposition line first, then exactly five sections: `persistence` (pass/fail with specifics), `fidelity` (the element matrix: match, adaptation, missing, contradicted, or added without approval per salient element, adaptations citing their evidence, or "faithful"), `ceiling` (unused native devices, or "reached"), `material_fixes` (ordered, most material first, fidelity failures ahead of craft, each one line tied to a check or contract promise, at most eight), and `keep` (one line naming what must not be diluted while fixing). Missing inputs are named in one line above the sections. No praise, no summary prose.
+
+## Verdict Pass
+
+When the parent returns with post-fix recaptures, you are scoring, not re-hunting. The parent's narration of what was fixed is not evidence; a claimed fix you cannot see in the recaptures is unresolved. For each material fix from your review, one line: resolved, partial, or unresolved, tied to what the new screenshots visibly show; a fix answered mechanically, positions moved but the quality the finding named still absent, is partial at best. Then name at most three regressions the fix batch itself introduced, judged by the same matrix rules, and nothing else; no new hunt, no new checks. Return exactly two sections: `verdict` (the scored list) and `remaining` (what stays open, or "clear"), and end with the disposition line recomputed against what remains open; unresolved or partial material findings can never recompute to ship.

.claude/skills/impeccable/reference/degraded/manual-edit-applier.md

@@ -16,12 +16,12 @@ Expect a self-contained handoff with:
 - Event id.
 - Page URL.
 - Optional chunk metadata.
-- Optional repair metadata. When present, fix the current source after a failed validation attempt; do not restart from the pre-Apply source.
+- Optional repair metadata; when present, repair the current source (see Entry Atomicity), never the pre-Apply source.
 - Optional deadline.
 - The current event `batch`.
 - Optional `evidencePath`.
 
-The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not run `live-commit-manual-edits.mjs` for a leased manual Apply event. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
+The user already clicked Apply. Do not ask what to do. Do not discard edits. Do not run `live-poll.mjs`, `live-commit-manual-edits.mjs`, or any live server endpoint. Do not stage, commit, rebuild, push, or edit generated provider output unless the batch explicitly targets that generated file.
 
 ## Workflow
 

.claude/skills/impeccable/reference/init.md

@@ -36,7 +36,7 @@ Start with the unknowns that most change future product decisions:
 2. What does the product make possible, and what is its meaningfully different mechanism or position?
 3. What durable constraints, assets, evidence, or product facts must future work preserve?
 
-Confirm ambiguous platform separately. Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them.
+Confirm ambiguous platform separately. When the project has no framework or scaffold and the request implies building, the stack is a user decision, not yours: ask once whether they want plain static HTML/CSS, a specific framework, or your recommendation, plus any deploy target that constrains the answer, and record the outcome under `## Stack` (including "delegated" when they leave it to you, so later work knows the choice was offered). Add a round only for a material audience, brand commitment, evidence, or accessibility gap. Record undecided facts instead of inventing them.
 
 Do not ask for an aesthetic direction, emotional feel, visual references, colors, typography, or style during init. If the user volunteers a binding visual constraint, record it without expanding it.
 
@@ -66,6 +66,9 @@ Write only confirmed facts and explicitly marked open decisions. Omit irrelevant
 
 web
 
+## Stack
+[Greenfield only: the user's answer to the stack question, e.g. "static HTML/CSS", "Astro", or "delegated: <what you chose and why>". Omit the section when an existing codebase already answers it.]
+
 ## Users
 [Primary users, their situation, and job. Add other audiences only when confirmed.]
 

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

@@ -0,0 +1,102 @@
+One-time live-mode project setup. Loaded from [live.md](live.md) only when `live.mjs` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
+
+## Write the config
+
+Create the file at the `path` the boot reported (default `.impeccable/live/config.json`):
+
+```json
+{
+  "files": ["<path-or-glob>", "<path-or-glob>", ...],
+  "exclude": ["<optional-glob>", ...],
+  "insertBefore": "</body>",
+  "commentSyntax": "html",
+  "cspChecked": true
+}
+```
+
+`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
+
+**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
+
+**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
+
+| Framework | `files` | `insertBefore` | `commentSyntax` |
+|-----------|---------|----------------|-----------------|
+| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
+| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
+| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
+| Nuxt | `["app.vue"]` | `</body>` | `html` |
+| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
+| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
+| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
+
+Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `live.mjs` after each build (accept is unaffected; it writes true source via the fallback flow).
+
+**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.impeccable/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `live-inject.mjs` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `ImpeccableLiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
+
+## Config drift
+
+On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
+
+## CSP detection (first-time only)
+
+If `config.cspChecked === true`, skip this whole section; the user was already asked once.
+
+```bash
+node .claude/skills/impeccable/scripts/detect-csp.mjs
+```
+
+Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
+
+- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
+- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
+- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
+- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
+
+### Consent prompt (use this phrasing)
+
+> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
+>
+> ```diff
+> [file: <patchTarget>]
+> [exact diff, 2-5 lines]
+> ```
+>
+> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
+
+On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
+
+### append-arrays
+
+Declare near the top of the file that holds the CSP arrays, then append `...__impeccableLiveDev` to the script-src and connect-src arrays:
+
+```ts
+// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
+const __impeccableLiveDev =
+  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
+```
+
+Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`, `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js`. Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
+
+### append-string
+
+Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
+
+```ts
+// Dev-only allowance so impeccable live mode can load.
+const __impeccableLiveDev =
+  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
+```
+
+- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
+- `connect-src 'self'` becomes `` `connect-src 'self'${__impeccableLiveDev}` ``
+
+Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js`, `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts`.
+
+## Troubleshooting
+
+If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`; setup asks again.
+
+After setup, re-run `live.mjs`.

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

@@ -2,50 +2,33 @@ Interactive live variant mode: select elements in the browser, pick a design act
 
 ## Prerequisites
 
-A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
+A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
 
 ## The contract (read once)
 
-Execute in order. No step skipped, no step reordered.
+Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins.
 
-1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .claude/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
+1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .claude/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root.
 2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
-3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
-
-The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
-5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
-6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
+3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `live-poll.mjs` to reconnect.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant.
+5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack.
+6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges delivery, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts stay recoverable until `live-complete.mjs --id EVENT_ID` runs. Finish that cleanup before polling again.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The journal under `.impeccable/live/sessions/` is canonical and replays unacknowledged work after a helper restart; the injected `live.js` re-attaches when the page reopens. Fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
-- **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free while you generate and publish in it. Do not block the shell.
-- **Cursor**: run **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|exit)"`. After each event the poll exits; handle it, `--reply`, then start `live-poll.mjs` again. Do **not** use `--stream` on Cursor: incremental stdout notify is slower in practice than exit-based notify (~5s vs sub-second in testing).
-- **Codex**: run the default one-shot poll in a **yielded foreground exec session**. Do not suffix it with `&`, use `--stream`, or leave Live without an active foreground poll. Handle every event in the main task; after each handler/reply, restart the foreground poll.
-- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
+- **Claude Code**: run the poll as a **background task** (no short timeout); the harness notifies you on completion. Do not block the shell.
+- **Cursor**: **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|manual_edit_apply|variant_mount_failed|prefetch|exit)"`; handle, `--reply`, restart the poll. Do **not** use `--stream` on Cursor (measured ~5s pickup vs sub-second one-shot).
+- **Codex**: default one-shot poll in a **yielded foreground exec session**. No `&`, no `--stream`, never leave Live without an active foreground poll. Starting the poll is not enough: SERVICE it (keep reading the exec session until it returns an event). Never announce "waiting for the user" and idle; a yielded poll nobody reads is a dead session, and the user's Go sits unanswered.
+- **Other harnesses**: one-shot foreground unless you know stdout reliably returns when a shell exits.
 
-Generation delivery policy:
-- **Default (Cursor and other harnesses):** keep the established atomic single-edit delivery. Do not switch a harness to progressive until its poll loop is known not to block on the extra publish calls. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
+Delivery policy: atomic single-edit delivery everywhere; do not switch a harness to progressive publishing unless its poll loop is known not to block on the extra calls.
 
 Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
 
-## Start
-
-```bash
-node .claude/skills/impeccable/scripts/live.mjs
-```
-
-Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md, DESIGN.md, and any surface brief already loaded by Setup in mind for variant generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** 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 requires the user's explicit redesign/replacement intent.
-
-`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).
-
-If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project hasn't been configured for live mode (or its config is stale). See **First-time setup** at the bottom.
-
 ## Poll loop
 
-**Default (portable, all harnesses):**
-
 ```
 LOOP:
   node .claude/skills/impeccable/scripts/live-poll.mjs   # default long timeout; no --timeout=
@@ -57,253 +40,143 @@ LOOP:
   "discard"   → Handle Discard; LOOP
   "prefetch"  → Handle Prefetch; LOOP
   "manual_edit_apply" → Handle Manual Edit Apply; reply done|partial|error; LOOP
+  "variant_mount_failed" → Fix the variant files; reply done --file <path>; LOOP
   "timeout"   → LOOP
   "exit"      → break → Cleanup
 ```
 
-**Stream mode (experimental, not for Cursor):**
+`variant_mount_failed` means the browser could not render what you published (`variant`, module `url`, `error`). The user sees a persistent error card, not variants. Fix the variant files, then `--reply EVENT_ID done --file <manifest or source path>`; the browser retries on its own.
 
-```
-node .claude/skills/impeccable/scripts/live-poll.mjs --stream   # stays running; one JSON line per event
-  Handle event; run --reply in a separate command
-  Repeat until "exit" line → Cleanup
+**Stream mode** (`--stream`, experimental, never on Cursor): one long-lived process, one JSON line per event, `--reply` from a separate command. Only for harnesses that read incremental stdout reliably.
+
+## Start
+
+```bash
+node .claude/skills/impeccable/scripts/live.mjs
 ```
 
-Stream keeps one process alive and waits for `--reply` ack before polling again. Useful only when the harness reads incremental stdout reliably and quickly. **Cursor is not one of those:** background pattern notify on a long-running shell was ~5s to pick up events vs sub-second for one-shot exit notify. Default to one-shot everywhere unless you have measured otherwise.
+Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `surface-brief.mjs` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent.
+
+`serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry.
+
+If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config.
 
 ## Recovery commands
 
-The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
-
-Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
+The append-only journal under `.impeccable/live/sessions/` is canonical durable state (not project source). When the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
 
 ```bash
-node .claude/skills/impeccable/scripts/live-status.mjs
-node .claude/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
-node .claude/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
+node .claude/skills/impeccable/scripts/live-status.mjs      # helper state, active sessions, queued events; works with the helper down
+node .claude/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID   # active snapshot, pending event, next safe action
+node .claude/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID # canonical manual final acknowledgement after verified cleanup
 ```
 
-- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
-- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
-- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
-
-Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
+Server restart rule: start `live-server.mjs` again, then poll; startup requeues unacknowledged events, so never ask the user to click Go again unless `live-resume.mjs` says no active session exists.
 
 ## Handle `generate`
 
 **Replace mode** (default): `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
 
-**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`. Requires a non-empty `freeformPrompt` **or** annotations. Screenshot is sent only when annotations exist (same rule as replace). Use `placeholder` dimensions as a soft size hint for net-new content.
+**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`; requires a non-empty `freeformPrompt` **or** annotations. `placeholder` is a soft size hint.
 
-Speed matters; the user is watching the selected element. Reuse server preflight metadata when available, minimize discovery calls, and follow the harness-specific delivery policy above.
+Speed matters; the user is watching the selected element. Reuse preflight metadata, minimize discovery calls.
 
 ### Insert mode branch
 
-When `event.mode === "insert"`:
-
-1. Read the screenshot if `event.screenshotPath` is present (annotations only).
-2. If `event.scaffold` is present, use it as the insert-helper result and do **not** run the helper again. Otherwise run the insert helper instead of wrap:
+1. Read the screenshot if present (annotations only).
+2. If `event.scaffold` is present, use it and do **not** run the helper again. Otherwise:
 
 ```bash
 node .claude/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
   --element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT"
 ```
 
-- `--position` ← `event.insert.position` (`before` | `after`)
-- Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
-
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
-
-For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
-
-For non-Svelte targets, on accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
+`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched.
 
 ### Replace mode (default)
 
 ### 1. Read the screenshot (if present)
 
-`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
+`event.screenshotPath` is sent **only when the user annotated before Go**; it is a PNG of the element with annotations baked in. Read it before planning. When absent, do not ask for one or screenshot the page yourself: without annotations a screenshot anchors you on the existing design and fights the three-distinct-directions brief; work from `element.outerHTML`, the computed styles, and the prompt.
 
-When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
-
-`event.comments` and `event.strokes` carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).
-
-Reading annotations precisely:
-
-- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
-- **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
-- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
-- **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
+Annotation semantics: a comment's `{x, y}` is element-local and binds the text to the child under that point (a comment near the title is about the title). Comments and strokes are independent unless clearly paired. Strokes read by shape: closed loop = "this thing" (emphasis, not a clipping region); arrow = direction or movement; cross/slash = delete; scribble = emphasis or delete by context. If a stroke's intent is genuinely ambiguous and it changes the brief, ask one short question before generating; otherwise state your reading in one sentence.
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the helper already found the source and computed the wrapper; treat it as the successful output and skip the command. `event.scaffoldAttempted` with `scaffoldError` means preflight could not finish; use the command below.
 
-**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper; it hands you `scaffold.wrapperBlock` plus the picked element's source range (`replaceStartLine`, `replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands and strands the browser at 0/N. (`replaceEndLine < replaceStartLine` means insert mode: insert, remove nothing.) The `svelte-component` path never sets `sourceWritten`.
 
 ```bash
 node .claude/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
 ```
 
-Flag mapping. Keep them separate, don't collapse into `--query`:
+Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow.
 
-- `--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.
+Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to.
 
-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.
+For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` holding the variant components, and `sourceFile` the real route. The scaffold is AST-based: control-flow blocks (`{#each}`, `{#if}`) survive intact and a free each-collection crosses the contract as ONE structured prop (kind `collection`). The payload includes `componentStubMarkup` (the prop-substituted markup already written into every stub), so do not read the manifest or stubs back. EDIT `v1.svelte`, `v2.svelte`, ... in place; never delete and recreate them; keep the stub's control flow and `propContract` prop names; never flatten a loop into literal items. The stub `<style>` arrives seeded with the source rules that currently style the selection; restyle or delete them freely. On accept, any seeded rule your variant does not re-declare is REMOVED from the source (the preview never applied it, so the user approved a design without it). Use semantic class selectors, no `@scope`, no `data-impeccable-*`. Reply with `--file` set to the manifest path; the browser mounts the compiled components so Svelte HMR does not reset page state. Accept merges the chosen component back mechanically (markup restored to route expressions, CSS reconciled, params baked, indentation preserved); you have no post-accept cleanup on this path. When the selection contains constructs a detached preview cannot support (component tags, `bind:`/`use:`, await blocks, inline scripts, spread attributes), wrap returns the normal source-preview wrapper with `previewFallback: { from: "svelte-component", reason }`; just follow the returned shape.
 
-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, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
-
-For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
-
-**Params on component-preview paths go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, and both Svelte/Vue previews mount without an HTML variant wrapper. Declare params in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
+**Params on component-preview paths go in a sidecar, never as an attribute** (Svelte parses `{` in attribute values as an expression). Declare them in `componentDir/params.json` keyed by variant number, using the schema from section 7:
 
 ```json
-{
-  "1": [
-    {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
-      {"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"},{"value":"packed","label":"Packed"}
-    ]}
-  ],
-  "2": [
-    {"id":"accent","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Accent"}
-  ]
-}
+{ "1": [ {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
+    {"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"} ]} ] }
 ```
 
-Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`; wrap those selectors in `:global(...)` so the knob values the runtime sets on the mounted root reach your rules. The browser reads `params.json`, docks the panel, and drives `--p-*` / `data-p-*` on the mounted component exactly as it does for the HTML/JSX path.
+Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`, wrapped in `:global(...)` so runtime knob values on the mounted root reach your rules.
 
-`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
-
-- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
-- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
-
-Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
-
-**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
-
-- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
-- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
-- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
-
-All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
+**Fallback errors.** Wrap refuses to write into non-source files (generated, untracked): accepting into one is silent data loss. Three shapes, all with `fallback: "agent-driven"` (see **Handle fallback**): `file_is_generated` (your `--file` points at a generated file), `element_not_in_source` with `generatedMatch` (element only exists generated), `element_not_found` (likely runtime-injected).
 
 ### 3. Load the action's reference
 
-If `event.action` is `impeccable` (the default freeform action), work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md), and decide the visitor mode from the selected surface. Do not load a sub-command reference. **Freeform is not a pass to skip parameters:** you still follow the composition budget and the freeform bias in **§7 Parameters** below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.
-
-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.
+`event.action` is `impeccable` (freeform): work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md); decide the visitor mode from the surface; do not load a sub-command reference. Freeform is not a pass to skip parameters: follow the budget and freeform bias in section 7. Any other action (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): read `reference/<action>.md` before planning; its MUST params layer on top of the section 7 budget.
 
 ### 4. Plan three variants: identity first, then mode, then axes
 
-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.
-
-Four phases. Do them in order.
+Live runs on an existing surface; the brand is already chosen. The job is variation **within identity**, not selection between identities. The worst failure is three off-brand variants the user cannot accept. Four phases, in order.
 
 #### Phase A: Extract the identity (non-skippable)
 
-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 name an aesthetic family in this sentence; that is a conclusion, not observed identity data. Letting conclusions into Phase A collapses the identity lock 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.
+Sources in priority order: DESIGN.md's visual system fields; CSS custom properties (de-facto tokens); computed styles on the picked element and parent; sibling components' visual rhetoric. Write ONE sentence recording what is actually on screen: dominant surface and accent color (real values, not "warm"), the loaded font pairing, layout topology (stacked / side-by-side / grid / asymmetric / overlay), surface treatment (corners, borders, shadows, decoration density), and the voice tone read off the copy. Be specific; skip an axis rather than fabricate; do not name an aesthetic family (a conclusion, not data). This sentence is the **identity lock**: every variant must read as the same brand side by side. Absence of DESIGN.md is never an excuse.
 
 #### 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 durable product and brand truth. Trigger only when the user explicitly asks for departure in the current request or freeform prompt ("redesign this", "rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different"). A stale page critique or an old task note is not replacement authorization.
-
-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.
+**Default** preserves the identity and varies expression within it; right for ~90% of sessions. **Departure** rejects the identity; trigger ONLY on the user's explicit ask in the current request or prompt ("redesign this", "rebuild from scratch", "something completely different"); a stale critique or old note is not authorization. Unsure means default: wrong-default costs "three on-brand variants with similar feel" (recoverable), wrong-departure costs three off-brand variants (unrecoverable).
 
 #### 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:
+**Default mode.** Each variant commits to a different **primary axis**, preserving the identity sentence. The six axes: 1 **Hierarchy** (which element commands the eye), 2 **Layout topology** (stacked / side-by-side / grid / asymmetric / overlay), 3 **Typographic system** (pairing logic, scale ratio, case/weight, *within the available faces*), 4 **Color strategy** (which existing palette role carries the surface: Restrained / Committed / Full palette / Drenched; existing tokens only), 5 **Density** (minimal / comfortable / dense), 6 **Structural decomposition** (merge, split, progressive disclosure). Three variants, three DIFFERENT axes: the same brand at three angles. New fonts, new hues, or new aesthetic-family signals belong to departure mode only.
 
-1. **Hierarchy**: which element commands the eye?
-2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
-3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
-4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
-5. **Density**: minimal / comfortable / dense
-6. **Structural decomposition**: merge, split, progressive disclosure
+**Departure mode.** Each variant anchors to a different aesthetic direction derived from the brand, never a fixed catalog: read PRODUCT.md's Brand Personality words; derive physical, spatial, or material experiences that embody them; from those, derive three directions genuinely different from each other AND from the current surface; reject reflex choices whose rationale would fit a neighboring product. Each direction must be one concrete sentence naming a real-world referent ("a museum exhibition label system", not "clean and minimal").
 
-Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
-
-**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
-
-**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from PRODUCT.md's audience world and voice plus the current DESIGN.md. Do not pick from a fixed catalog; derive directions from this product.
-
-Instead, work from the brand:
-
-1. Read PRODUCT.md's Brand Personality words. Derive physical, spatial, or material experiences that embody them without starting from a design style.
-2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
-3. Reject any direction chosen by reflex rather than derived from the brand. Start over from the personality words when the rationale could fit a neighboring product.
-4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
-5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
+**In both modes, name each variant's 2 or 3 parameter knobs while planning** (section 7 budget). Parameters are part of the design; deciding "what's tunable" during planning beats retrofitting.
 
 #### 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.
+**Default:** compare each variant against the Phase A lock; palette, type voice, or rhetoric drift means it crossed into departure by accident: rework. Then confirm three different primary axes; three "tighter density" variants is failure. **Departure:** two passes, family before sentence. Family pass (non-negotiable): label each variant with a concrete family of your own choosing; shared or interchangeable labels mean rework. Sentence pass: three one-line descriptions side by side; two that rhyme mean rework. When the primary axis is color or theme, the trio must not share theme + dominant hue: three color worlds, not three shades.
 
-**Departure mode squint.** Two passes, family before sentence:
+**Action-specific invocations** must vary along the action's dimension:
 
-1. **Family pass.** Give each variant a concrete family label of your own choosing. If two variants share a label, or a label fits another variant equally well, rework. Do not use a fixed vocabulary. *This pass is non-negotiable in departure mode and catches monoculture the sentence pass misses.*
-2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
-
-**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
-
-**For action-specific invocations**, each variant must vary along the dimension the action names:
-
-- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
+- `bolder`: amplify a different dimension per variant (scale / saturation / structural change).
 - `quieter`: pull back a different dimension (color / ornament / spacing).
 - `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
-- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
-- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
-- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
-- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
-- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
-- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
-- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
-- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
+- `polish`: a different refinement axis (rhythm / hierarchy / micro-details).
+- `typeset`: different pairing AND different scale ratio each.
+- `colorize`: different hue family each; vary chroma and contrast strategy.
+- `layout`: different structural arrangement, not spacing tweaks.
+- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data).
+- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax).
+- `delight`: different flavor of personality (micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic / easter egg).
+- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions); skip its "propose and ask" step, live is non-interactive.
 
 ### 5. Apply the freeform prompt (if present)
 
-`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. 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 conflicts with a confirmed binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes or replaces it. Task-local strategy from the matching surface brief may change when the user changes that surface's goal.
+`event.freeformPrompt` is the user's ceiling on direction: all variants honor it while exploring different interpretations within the Phase B mode. Default mode: the prompt narrows the axes, not the identity ("more confident" → one variant amplifies hierarchy, one commits the accent color, one tightens density). Departure mode: the prompt narrows the lanes, not the families ("newspaper front page" → broadsheet vs tabloid vs trade journal, then run the family pass). When the prompt conflicts with a binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes it.
 
 ### 6. Deliver variants
 
-Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
-
-Colocate preview CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and keeps each delivered state internally complete (no FOUC).
-
-**Atomic default:** write CSS + all variants + parameter manifests in one edit at `insertLine`, preserving the established behavior.
-
-Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
+Complete HTML replacement of the original element per variant, not a CSS-only patch. Colocate preview CSS as a `<style>` tag inside the wrapper. **Atomic default:** CSS + all variants + parameter manifests in one edit at `insertLine`.
 
 ```html
 <!-- Variants: insert below this line -->
@@ -314,92 +187,55 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
   <!-- variant 1: full element replacement (single top-level element) -->
 </div>
 <div data-impeccable-variant="2" style="display: none">
-  <!-- variant 2: full element replacement -->
+  <!-- variant 2 -->
 </div>
 <div data-impeccable-variant="3" style="display: none">
-  <!-- variant 3: full element replacement -->
+  <!-- variant 3 -->
 </div>
 ```
 
-**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
+Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected.
 
-The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
+For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template.
 
-The browser's MutationObserver accepts either delivery shape. On the transactional progressive path it shows arrived variants and pending dots immediately; Accept and Discard are available as soon as one variant exists. Accepting an arrived variant fences the worker before the browser releases the picker, so later publications are rejected.
-
-For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
-
-**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
+**JSX / TSX targets:** wrap `<style>` content in a template literal (CSS braces would parse as JSX), use `className=` / `style={{…}}`, keep `data-impeccable-*` attributes as 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.
+The wrap script provides a single-rooted JSX wrapper with the marker comments inside; drop the block at the marker and the source stays valid TSX.
 
-### 7. Parameters (composition-sized, 0–4 per variant)
+### 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.
+Each variant can expose **coarse** knobs; the browser docks one control per parameter with zero regeneration cost (knobs drive a CSS variable or data attribute your scoped CSS is authored against). Wire an axis as soon as the user could plausibly mutter "a bit tighter" or "a touch more accent" without wanting a regeneration; micro-margins and one-off nudges are not parameters. Freeform bias: you chose the axes, so expose them; a hero with 0 params is almost always a mistake, and 1 is underweight unless the design is a genuine fixed point.
 
-**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
+Budget scales with the element's VISUAL weight (count visual children, not DOM depth):
 
-**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
+- **Leaf / tiny** (button, icon, bare heading): **0 params.**
+- **Small composition** (simple card, labeled input, ≤ ~5 visual children): **0-1**.
+- **Medium composition** (section, nav cluster, 6-15 children): **target 2**; 1 if simple.
+- **Large composition** (hero, full region, 16+ children or sub-sections): **target 2-3, up to 4** when independent axes are all authored in CSS.
 
-**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
+**Hard cap: four** per variant. For named sub-commands, the action reference's MUST params are non-negotiable when expressible; respect the cap, no duplicate knobs.
 
-**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
-
-- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
-- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
-- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
-- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
-
-**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
-
-**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
-
-**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the `svelte-component` path, do not use this attribute.** Declare params in `componentDir/params.json` keyed by variant number instead (see the component-preview paragraphs in the wrap section). The param schema below is identical for every path.
+**Declare** on the HTML/JSX path as a wrapper attribute (component-preview paths use `componentDir/params.json` instead, same schema, keyed by variant number; see the wrap section):
 
 ```html
 <div data-impeccable-variant="1" data-impeccable-params='[
   {"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
-  {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
-    {"value":"airy","label":"Airy"},
-    {"value":"snug","label":"Snug"},
-    {"value":"packed","label":"Packed"}
-  ]},
   {"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
 ]'>
-  ...variant content...
-</div>
 ```
 
-**Three kinds:**
+Three kinds: `range` (slider; drives `--p-<id>`; author `var(--p-color-amount, 0.5)`; fields min/max/step/default/label), `steps` (segmented radio; drives `data-p-<id>`; author `:scope[data-p-density="airy"] .grid { ... }`; fields options/default/label), `toggle` (drives both `--p-<id>: 0|1` and attribute presence; fields default/label). Reset on variant switch is a known limitation: each variant starts at its declared defaults.
 
-- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
-- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
-- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
-
-**Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
-
-**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
-
-**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
-
-```html
-<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->
-```
-
-The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
+**On accept**, the browser sends current values and `live-accept.mjs` writes them as a sibling comment: `<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->`. Carbonize cleanup bakes them: keep only the matching `steps`/`toggle` branch, drop the others, collapse `:scope[data-p-…]` to semantic rules; substitute `range` literals or update the var's default.
 
 ### 8. Signal done
 
@@ -407,127 +243,56 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
 node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
 ```
 
-`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
-
-Then run `live-poll.mjs` again immediately.
+`RELATIVE_PATH` is relative to project root; the browser fetches source directly if the dev server lacks HMR. Then poll 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.
+If wrap or generation fails after the browser flipped to GENERATING, tell the **browser** so its bar resets: `node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` for this (pure file mutator, browser never sees it, bar sticks on dots); `--discard` is only source-side cleanup for a discard the browser itself initiated.
 
 ## Handle fallback
 
-When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
+When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it.
 
-The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
-
-### Step 1: Identify where the element actually lives
-
-Use the error payload:
-
-- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
-- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
-- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
-
-Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
-
-### Step 2: Show three variants in the DOM for preview
-
-The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
-
-1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
-2. Insert your three variant divs inside it, same shape as the deterministic path.
-3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
-
-This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
-
-### Step 3: On accept, write to true source
-
-When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
-
-- Structural change → edit the template / component source.
-- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
-- Dynamic from data → update the data source or the render logic.
-
-Then remove the temporary wrapper from the served file if it's still there.
-
-### Step 4: On discard, clean up the served file
-
-Remove the wrapper you inserted in Step 2. Nothing else to do.
+1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template.
+2. **Preview in the served file**: manually write the same wrapper scaffold `live-wrap.mjs` produces (`<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`) into the file the browser actually loaded, insert your variant divs, `--reply EVENT_ID done --file <served file>`. This edit is temporary; a regen wiping it is fine.
+3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file.
+4. **On discard**, just remove the temporary wrapper.
 
 ## Handle `accept`
 
-Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
+Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` deterministically and acknowledged delivery; the browser DOM is already updated.
 
 - The accept event includes `pageUrl`; the poll script must forward it to `live-accept.mjs --page-url PAGE_URL` so accept-time cleanup only scrubs staged copy edits for the current page.
-- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
-- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
-- `_acceptResult.handled: true` and `carbonize: true`: post-accept cleanup is required, but it must not stall Codex's control lane. See "Required after accept (carbonize)" below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and stderr banner all point at this required follow-up; none are decorative.
-- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
-- `_acceptResult.handled: false, mode: "error"`: the operation genuinely failed. **Do not hand-edit the file**; the source was not touched and editing it yourself would either double-apply or race whoever holds it.
-  - `error: "source_locked"`: a generation publish holds the file. Run the same `live-accept.mjs` command again; it is idempotent and will succeed once the publisher releases. Do not poll past it.
-  - `error: "accept_receipt_conflict"`: this session already resolved as `priorOperation` (on `priorVariantId` for an accept), so the request contradicts durable truth. Do not edit. Run `live-status.mjs` and tell the user what the session actually resolved to.
-  - anything else: report the error briefly and run `live-status.mjs` before continuing.
-- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
+- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, finish cleanup manually if needed, then `live-complete.mjs --id EVENT_ID`.
+- `handled: true, carbonize: false`: nothing to do; poll again.
+- `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it.
+- `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll.
+- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `live-accept.mjs` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `live-status.mjs` and tell the user. Anything else: report briefly, run `live-status.mjs` first.
+- `handled: false` without `mode`: manual cleanup: read file, find markers, edit.
 
 ### Required after accept (carbonize)
 
-When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
+`carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll:
 
-Do these five steps synchronously before the next poll. The source lock, generation epoch, and expected-source hash remain the final safety gates against a generator finishing concurrently with Accept.
+1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `<!-- impeccable-carbonize-start/end SESSION_ID -->` with a `<style data-impeccable-css>` element; read the `<!-- impeccable-param-values -->` comment first when present, it drives steps 3 and 4.
+2. **Move the CSS rules** into the project's real stylesheet (whichever already owns styling for the surrounding element).
+3. **Bake param values while rewriting selectors**: retarget `@scope ([data-impeccable-variant="N"])` to real semantic classes; keep only the `:scope[data-p-<id>="VALUE"]` branch matching the chosen value; substitute `var(--p-<id>)` literals or update the var's default.
+4. **Unwrap the accepted content**: delete the inner variant div (and on JSX the outer `data-impeccable-carbonize` div); drop `data-impeccable-params` and all `data-p-*` attributes.
+5. **Delete** the inline `<style>` block, the param-values comment, both carbonize markers, and any `@scope` rules for non-accepted variants.
 
-1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
-2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
-3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the inner `<div data-impeccable-variant="N" style="display: contents">` that wraps it. On JSX/TSX, also delete the outer `<div data-impeccable-carbonize="SESSION_ID" style={{ display: 'contents' }}>` wrapper if present (accept adds it so ternary/`return` slots keep a single root). Drop `data-impeccable-params` and any `data-p-*` attributes; those are live-mode plumbing, not source.
-5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
-
-After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. Poll again only after that verification.
+Then run `live-complete.mjs --id SESSION_ID` and verify `phase: "completed"` before polling again. The command is a gate, not a formality: it refuses with `error: "source_dirty"` plus findings while any live-mode leftover remains; fix and rerun (`--force` only for false positives).
 
 ## Handle `discard`
 
-Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
+Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original and acknowledged `discarded`. Nothing to do unless `_completionAck.ok !== true`; then `live-complete.mjs --id EVENT_ID --discarded` and poll again.
 
 ## Handle `steer`
 
-Event: `{id, message, pageUrl}`. The user typed or spoke into the global bar **Steer** control: page-level direction without picking an element or launching variant generation.
-
-The mic button uses the browser **Web Speech API** (MVP): click to start, speak, stop automatically when the utterance ends, then the transcript submits as a steer event. Click again while listening to cancel without submitting.
-
-This is lighter than `generate`: no screenshot, no element context, no variant cycling. Read `message` and inspect the live page or project files as needed, then either make edits or answer in prose.
-
-When finished:
-
-```bash
-node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short note for a browser toast"]
-```
-
-On failure:
-
-```bash
-node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
-```
-
-Then poll again immediately. Do not send a separate "picked up" reply. The Steer bar stays locked until `steer_done` or `error` arrives over SSE.
+Event: `{id, message, pageUrl}`: page-level direction from the global bar's Steer control (typed or spoken), no element context, no variant cycling. Read `message`, inspect the page or files as needed, make edits or answer in prose. Reply `node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short toast"]`, or on failure `--reply EVENT_ID error "Short reason"`, then poll immediately. No separate pickup reply; the Steer bar unlocks on `steer_done` or `error`.
 
 ## Handle `prefetch`
 
-Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
-
-Resolve `pageUrl` to the underlying file:
-
-- Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
-- Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
-
-Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
-
-Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
+Event: `{pageUrl}`: fired once per route on first selection; the user is likely about to Go on a page you have not read. Resolve the route to its file (root `/` is usually the boot's `pageFile`; multi-page sites often map `/foo` to `public/foo/index.html`; SPAs map everything to one entry), read it, poll again. No `--reply`. If you cannot resolve it confidently, skip and poll.
 
 ## Handle `manual_edit_apply`
 
@@ -543,12 +308,7 @@ After source edits finish, reply exactly once with `node .claude/skills/impeccab
 
 ## Exit
 
-The user can stop live mode by:
-- Saying "stop live mode" / "exit live" in chat
-- Closing the browser tab (SSE drops, poll returns `exit` after 8s)
-- The browser's exit button
-
-When the poll returns `exit`, proceed to cleanup. If the poll is still running as a background task, kill it first.
+The user stops live mode by saying so in chat, closing the tab (SSE drops; poll returns `exit` after 8s), or the browser's exit button. On `exit`, kill any still-running background poll, then clean up.
 
 ## Cleanup
 
@@ -556,175 +316,8 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
 node .claude/skills/impeccable/scripts/live-server.mjs stop
 ```
 
-Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
+Stops the helper and runs `live-inject.mjs --remove` to strip the injected script (use `stop --keep-inject` to keep it for a quick restart; `.impeccable/live/config.json` persists as project config). Then search for and remove any leftover `impeccable-variants-start` wrappers and `impeccable-carbonize-start` blocks.
 
-Then:
-- Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
-- Remove any leftover carbonize blocks (search for `impeccable-carbonize-start` markers).
+## First-time setup
 
-## First-time setup (config missing or invalid)
-
-If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
-
-Schema:
-
-```json
-{
-  "files": ["<path-or-glob>", "<path-or-glob>", ...],
-  "exclude": ["<optional-glob>", ...],
-  "insertBefore": "</body>",
-  "commentSyntax": "html",
-  "cspChecked": true
-}
-```
-
-`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
-
-`exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
-
-`cspChecked` tracks whether the CSP detection step below has already run. Absent on first setup; set to `true` after CSP is checked (whether patched, declined, or not needed).
-
-**Hard-excluded paths (cannot be overridden).** `**/node_modules/**` and `**/.git/**` are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.
-
-**Glob syntax.** `**` matches any number of path segments (including zero), `*` matches any characters except `/`, `?` matches a single character except `/`. Paths are always relative to the project root with forward slashes.
-
-| Framework | `files` | `insertBefore` | `commentSyntax` |
-|-----------|---------|----------------|-----------------|
-| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
-| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
-| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
-| Nuxt | `["app.vue"]` | `</body>` | `html` |
-| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
-| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
-| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
-| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
-| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
-
-Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
-
-**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
-
-For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
-
-For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
-
-### Drift-heal warning
-
-On every `live.mjs` boot, after inject, the project is scanned for HTML files under common page-source roots (`public/`, `src/`, `app/`, `pages/`). If any exist that aren't covered by the resolved `files` list, the output includes a `configDrift` field:
-
-```json
-{
-  "ok": true,
-  "serverPort": 8400,
-  "pageFiles": [ "..." ],
-  "configDrift": {
-    "orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
-    "orphanCount": 2,
-    "hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
-  }
-}
-```
-
-When `configDrift` is present, surface it to the user once per session before entering the poll loop:
-
-> Noticed N HTML file(s) in the project that aren't in `config.files`:
->
-> - `public/new-section/index.html`
-> - `public/docs/new-command.html`
->
-> Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
-
-Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
-
-### CSP detection (first-time only)
-
-If `config.cspChecked === true`, skip this entire section. You already asked this user once; the answer sticks.
-
-Otherwise, run the detection helper:
-
-```bash
-node .claude/skills/impeccable/scripts/detect-csp.mjs
-```
-
-Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
-
-- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
-- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
-  - Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
-  - SvelteKit `kit.csp.directives`
-  - Nuxt `nuxt-security` module's `contentSecurityPolicy`
-- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
-  - Inline `next.config.*` `headers()` with a CSP literal
-  - Nuxt `routeRules` / `nitro.routeRules` headers
-- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
-
-#### Consent prompt template
-
-Use this phrasing so the experience is consistent across agents:
-
-> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
->
-> ```diff
-> [file: <patchTarget>]
-> [exact diff, 2–5 lines]
-> ```
->
-> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
-
-On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write `cspChecked: true` (the question's been asked).
-
-On "yes": apply the Shape-specific patch below, then write `cspChecked: true`.
-
-#### append-arrays
-
-CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.
-
-**Declare near the top of the file that holds the CSP arrays:**
-
-```ts
-// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
-const __impeccableLiveDev =
-  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
-```
-
-**Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
-
-- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
-- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
-- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
-
-Reference outputs:
-- `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
-- `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js` (SvelteKit)
-
-Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is already applied; skip asking and just mark `cspChecked: true`.
-
-#### append-string
-
-CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the `script-src` and `connect-src` directives.
-
-```ts
-// Dev-only allowance so impeccable live mode can load.
-const __impeccableLiveDev =
-  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
-```
-
-Then in the CSP value string:
-- `script-src 'self' 'unsafe-inline'` → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
-- `connect-src 'self'` → `` `connect-src 'self'${__impeccableLiveDev}` ``
-
-(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
-
-Per-framework specifics:
-- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
-- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
-
-Reference outputs:
-- `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
-- `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts` (Nuxt)
-
-### Troubleshooting
-
-If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
-
-Then re-run `live.mjs`.
+Only when `live.mjs` reports `config_missing` / `config_invalid`, or `configDrift` needs explaining, or the config lacks `cspChecked`: read [live-setup.md](live-setup.md). It owns the config schema, the per-framework `files` table, injection adapters, drift healing, and the CSP detection and consent flow.

.claude/skills/impeccable/reference/new-work.md

@@ -36,21 +36,21 @@ Keep the visual system fixed. Derive five to seven materially different structur
 
 `node .claude/skills/impeccable/scripts/concept-seed.mjs --scope surface --mode <mode>`
 
-The script assigns which structure gets built: your top-ranked structure is what every run would ship, and a single ranking is deterministic, so the dice come from outside. Dress its staging challengers in the committed identity and weigh them against your list before building. Never run the script for a local extension or a precisely specified narrow request; shape those directly.
+The script assigns which structure gets built; your top-ranked structure is what every run would ship, so the dice come from outside. Never run the script for a local extension or a precisely specified narrow request; shape those directly.
 
 ### Create or replace the visual world
 
-1. Name the product's unique mechanism in one sentence, the audience's real scene, its cultural home, and what this first surface must prove. Note the page this category always ships and its predictable opposite; name both as the rut and keep them out of the seven-candidate list, so no die face is spent on the page the category already ships. A brief that paints its own picture, a product name, a titled artifact, a governing metaphor, adds its literal reading to the rut: spend at most one candidate on it and derive the rest from elsewhere in the audience's world.
-2. From that cultural world, list seven concrete visual systems, artifacts, places, or rituals the audience knows by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. The audience's world includes its graphic and screen traditions, the notation, publications, identity programs, data graphics, and interfaces it reads daily, not only its physical objects; a nameable abstract system (a school of poster, a documentation standard, a data-graphic tradition) is as concrete a candidate as any artifact. What would this thing look like as a physical object; what did its world look like before the web? Near-duplicates count once. When more than three of the seven share one material family, the derivation stopped at the subject's most obvious artifact; the audience's world is larger than that, so dig until the list spans at least three families.
+1. Name the product's unique mechanism in one sentence, the audience's real scene, its cultural home, and what this first surface must prove. Note the page this category always ships and its predictable opposite; name both as the rut and keep them out of the seven-candidate list. A brief that paints its own picture, a product name, a titled artifact, a governing metaphor, adds its literal reading to the rut: spend at most one candidate on it and derive the rest from elsewhere in the audience's world.
+2. From that cultural world, list seven concrete visual systems, artifacts, places, or rituals the audience knows by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. The audience's world includes its graphic and screen traditions, not only its physical objects: the notation, publications, identity programs, data graphics, and interfaces it reads daily; a nameable abstract system (a school of poster, a documentation standard) is as concrete a candidate as any artifact. What would this thing look like as a physical object; what did its world look like before the web? Near-duplicates count once. When more than three of the seven share one material family, the derivation stopped at the subject's most obvious artifact; dig until the list spans at least three families.
 3. Turn that material into complete directions: each joins a reusable visual world to a concrete first-surface experience.
-4. Run `node .claude/skills/impeccable/scripts/concept-seed.mjs --scope direction --mode <mode>` and follow what it prints. The script assigns which direction gets built and deals catalog challengers. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, and clarity wins conflicts. Weigh fused challengers against the assigned direction on exactly two axes, audience identification and product clarity; losing to strong grounded material is a valid outcome, and beating a thin or tool-monoculture list is the point.
-5. Present one direction, fully committed: its world, first viewport, visitor path, signature interaction, cross-surface reach, and honest risk. Alongside it, offer the hand's challengers as named alternates, the weighing's verdict written on each as its one-line case, an honest "fuses poorly because X" included; the weighing informs the user's choice, it never pre-empts it. A hand holds at most three challengers: when the roll deals more, the three strongest join the hand and the rest wait in the re-roll pool, noted in one line; dropping a challenger from the hand itself takes a named product-truth failure, disclosed. Add re-roll with an optional one-line steer. What you never present is a ranked menu of your own grounded candidates; a lineup of those invites the safest card, while dealt challengers carry no such rut. The two channels share this structure and differ only in richness: cards and boards on the decision page, names and one-liners through the structured tool; the structured tool's option list also carries the standing exit as its last option.
+4. Run `node .claude/skills/impeccable/scripts/concept-seed.mjs --scope direction --mode <mode>` and follow what it prints. This step has no substitute and no skip condition: on a new or replacement world, writing artifact code before this script has run and its assignment is acknowledged is a contract violation, whatever the harness, the model, or the time pressure, because the roll is the mechanism that keeps every run from converging on the category default. The script assigns which direction gets built and deals catalog challengers. Fuse each challenger before judging it: the challenger supplies the form and its system grammar, the product supplies every fact, and clarity wins conflicts. Weigh fused challengers against the assigned direction on exactly two axes, audience identification and product clarity; losing to strong grounded material is a valid outcome, and beating a thin or tool-monoculture list is the point.
+5. Present one direction, fully committed: its world, first viewport, visitor path, signature interaction, cross-surface reach, and honest risk. Alongside it, offer the hand's challengers as named alternates, the weighing's verdict written on each as its one-line case, an honest "fuses poorly because X" included; the weighing informs the user's choice, it never pre-empts it. A hand holds at most three challengers: when the roll deals more, the three strongest join the hand and the rest wait in the re-roll pool, noted in one line; dropping a challenger from the hand itself takes a named product-truth failure, disclosed. Add re-roll with an optional one-line steer. Never present a ranked menu of your own grounded candidates; a lineup of those invites the safest card. The two channels share this structure and differ only in richness: cards and boards on the decision page, names and one-liners through the structured tool; the structured tool's option list also carries the standing exit as its last option.
 
-The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Give every card the same anatomy, thesis, palette, materials, first viewport, honest risk, and the challengers' case lines (run the script with `--schema` for the exact shape); the page renders identity from these fields, so a grounded direction is never a wall of text against rendered art, and a challenger's catalog image rides as labeled inspiration, never as the promise of the build. Author `canonCard` too: the category standard as one honest card with the same anatomy; the page keeps it subordinate, and the counterweights still bind you, so it is never yours to recommend. Run `node .claude/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
+The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Give every card the same anatomy, thesis, palette, materials, first viewport, honest risk, and the challengers' case lines (run the script with `--schema` for the exact shape); the page renders identity from these fields, and a challenger's catalog image rides as labeled inspiration, never as the promise of the build. Author `canonCard` too: the category standard as one honest card with the same anatomy; the page keeps it subordinate, and the counterweights still bind you. Run `node .claude/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-When image generation exists, every card also declares a `sketch` path under `.impeccable/sketches/`, the canon card included. Serve the page first, then produce the sketches; the page shimmer-waits per slot and the user may answer before they land, so generation never delays the question. Render every sketch through one shared frame so the comparison stays about direction, never rendering luck: the requested surface's first viewport as a flat, matte design sketch in that card's own palette and type character, deliberately unfinished, no photorealism, no gloss, identical framing across cards; a candidate whose sketch looks more finished than the others has broken the comparison, not won it. The only legible text in a sketch is the product's real name and one real headline; every other text region is greeked, indistinct lines standing where copy will go, because a sketch that renders invented specs, prices, or dates puts claims in front of the user that PRODUCT.md never made. Produce in the order the user reads: the assigned card, then the hand, then canon, each file written the moment it is done. When the harness runs subagents in parallel, fan the set out as one agent per card: each spawn is the shipped asset producer with a single-sketch packet, that card's fields, PRODUCT.md, the shared frame, and the card's declared path, up to four in flight at once, so the whole set lands in roughly the time of one. A slot still empty when its agent returns is regenerated inline, and a slot still empty when the user answers is dropped without ceremony; no other supervision is owed. Without parallel subagents, generate in the main thread after serving, in the same reading order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. A sketch answers which world, never which composition: the comp round still renders its full set, and the chosen card's sketch seeds at most one probe. With no image generation, the cards carry their identity in palette chips and facts, and that page is complete, not a lesser version.
+When image generation exists, every card also declares a `sketch` path under `.impeccable/sketches/`, the canon card included. Where the harness sandboxes its shell, start the page through the least-sandboxed command path it offers: a sandboxed shell cannot bind the board's port, and the first-attempt failure costs a retry every session. Serve the page first, then produce the sketches; the page shimmer-waits per slot and the user may answer before they land. Render every sketch through one shared frame so the comparison stays about direction, never rendering luck: the requested surface's first viewport as a flat, matte design sketch in that card's own palette and type character, deliberately unfinished, no photorealism, no gloss, identical framing across cards; a candidate whose sketch looks more finished than the others has broken the comparison, not won it. The frame's aspect is the surface's own: a native app or mobile-first surface sketches portrait at its device viewport, a desktop web surface landscape, and the decision page adapts to either, so a phone screen sketched landscape is a broken frame, not a neutral default. The only legible text in a sketch is the product's real name and one real headline; every other text region is greeked, indistinct lines standing where copy will go, because a sketch that renders invented specs, prices, or dates puts claims in front of the user that PRODUCT.md never made. Produce in the order the user reads: the assigned card, then the hand, then canon, each file written the moment it is done. When the harness runs subagents in parallel, fan the set out as one agent per card: each spawn is the shipped asset producer with a single-sketch packet, that card's fields, PRODUCT.md, the shared frame, and the card's declared path, up to four in flight at once. A slot still empty when its agent returns is regenerated inline, and a slot still empty when the user answers is dropped without ceremony; no other supervision is owed. Without parallel subagents, generate in the main thread after serving, in the same reading order, and let the harness's own generation display carry the progress; the wait for the answer follows the last file. A sketch answers which world, never which composition: the comp round still renders its full set, and the chosen card's sketch seeds at most one probe. With no image generation, the cards carry their identity in palette chips and facts, and that page is complete, not a lesser version.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -62,15 +62,15 @@ Pick a color strategy before picking colors: Restrained (neutrals plus one accen
 
 Choose faces like objects from the subject's world, in the mode's register. Operate and Read surfaces are well served by system stacks and workhorse UI faces; Persuade and Experience surfaces want faces with a point of view, and these training-data defaults mean you stopped looking: Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter-as-display, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans. Naming one of these faces anyway requires a reason no other face could satisfy, and a subject association is never that reason: books wanting a serif, bookshops wanting hand-lettering, and tech wanting a mono are the associations the list exists to break.
 
-Calibration: AI-generated interfaces cluster around a few looks regardless of subject: warm cream ground, high-contrast serif display, and a terracotta or signal-red accent; near-black with one neon accent and glowing edges; broadsheet-editorial hairlines, italic display serif, and small tracked mono labels. All are legitimate when the brief calls for them; the brief always wins. Where the brief leaves the aesthetic free, landing in one of them means the self-check failed: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious. Energy is not the enemy of trust: a brief's negative constraints (no gamification, no hype) rule out those devices, not exuberance, and adjectives describing the product's behavior (quiet support, calm coaching) do not dictate the surface's energy. A bookish, warm, or child-facing subject does not soften the calibration: book cloth, thread, jackets, endpapers, and shelf ephemera span the whole saturated spectrum, and cream paper is the smallest corner of that world; landing on cream plus serif for a book subject is the default wearing the subject's clothes. A brief-pinned world pins the world, not its softest rendition: the pinned world's full material range stays in play, and a rendition that matches what any model ships for that world failed the self-check at execution rather than selection.
+Calibration: AI-generated interfaces cluster around a few looks regardless of subject: warm cream ground, high-contrast serif display, and a terracotta or signal-red accent; near-black with one neon accent and glowing edges; broadsheet-editorial hairlines, italic display serif, and small tracked mono labels. All are legitimate when the brief calls for them. Where the brief leaves the aesthetic free, landing in one means the self-check failed: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious. Energy is not the enemy of trust: a brief's negative constraints (no gamification, no hype) rule out those devices, not exuberance, and adjectives describing the product's behavior (quiet support, calm coaching) do not dictate the surface's energy. A bookish, warm, or child-facing subject does not soften the calibration: book cloth, thread, jackets, endpapers, and shelf ephemera span the whole saturated spectrum, and cream paper is the smallest corner of that world; landing on cream plus serif for a book subject is the default wearing the subject's clothes. A brief-pinned world pins the world, not its softest rendition: the pinned world's full material range stays in play, and a rendition that matches what any model ships for that world failed the self-check at execution rather than selection.
 
 Your measured rendition prior: warm, bookish, family, and child-facing subjects come out as cream grounds, serif display with italic accents, and lamplight, even when the assigned direction never asked for them. Treat that first palette as already spent. Before writing code, reread your OWN-WORLD block: when it says cream, paper, parchment, ivory, or lamplight for a Persuade surface the brief did not pin, the rendition failed and you rework it from the world's saturated materials first. The same subject renders as bookcloth, thread, jacket, and endpaper color on other models; nothing about the subject requires your default.
 
 ## 5. Record the decision
 
-Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment the compiler strips. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, the staging chosen for it, and the seed key the script printed; when the seed dealt stagings, choosing the world does not silently discharge the staging decision, so name the one you commit to. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract.
+Before code, state the chosen direction as a contract in the artifact's opening comment, five short blocks, 150 words at most, in a form that survives the production build: an HTML comment in the emitted markup, never only a templating-frontmatter comment, placed as the first child of the document's body in the root layout, never inside a slotted or child component (some compilers, Astro among them, strip a slot's leading comment while keeping deeper ones). After the first production build, grep the built output for the seed key; a contract the build erased is a contract nobody can audit. THESIS: the one idea this surface owns and the category-default arrangement it refuses. OWN-WORLD: the palette and component language, specific enough to be recognizable with all content removed. STORY: what the visitor understands, believes, and does. FIRST VIEWPORT: the exact composition, what is where and at what scale, and where the primary action sits. FORM: the chosen form, its position on your ordered list, and the seed key the script printed. Close the comment with one more line, FINISH: the run's exit condition, verbatim "unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md". The comment tops the artifact you re-open on every edit, the one reminder that survives a long build: a page that looks complete with the FINISH line undischarged is not done, it is abandoned at the finish line. If a block reads like a mood, the direction is not decided yet; the finishing review audits the render against this contract.
 
-On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and it hands the design-system detector an unstable target that buries the build in noise. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md.
+On a new or replacement world, DESIGN.md is written at finish, from the built world, by the shipped documenter (section 7); a rulebook written before the build gets defended against reality instead of describing it, and hands the design-system detector an unstable target. A new world shipped with no DESIGN.md is still an incomplete run. An ordinary extension does not rewrite DESIGN.md.
 
 If the work establishes durable strategy for a route or artifact, read its existing surface brief, then update it:
 
@@ -86,11 +86,14 @@ For `shape`, return the selected direction to [shape.md](shape.md) and stop befo
 
 ## 6. Build with full commitment
 
+When an approved comp exists, the comp is king, and the build happens in phases. Phase one is reproduction: rebuild the comp at its own breakpoint until a screenshot at the comp's width and height overlaps it near pixel-perfectly, materials, components, elevation, assets, and implied design language included. Exactly three concessions exist: fonts (the closest obtainable face), icons (exact match unless the user already chose an icon library), and genuine defects in the generated comp such as spelling errors. Everything else must match, and models systematically believe their HTML, CSS, and SVG recreation succeeded when it did not, so the overlap comparison is the authority, never your conviction: set the screenshot beside the freshly reopened comp image at identical dimensions after every region, never beside your memory of it, and when a region keeps losing that comparison, stop recreating it in code and produce it as a rendered asset composited into the page. The comp also outranks every written record of it: when the recorded brief or inventory commits to less than the comp shows, a softer texture, a sparser field, a sculpted plate reduced to flat CSS, correct the record upward to the comp; qualifiers like subtle, restrained, and low-contrast, and counts rounded down to a comfortable fraction, are how approved materials die between approval and build. A produced material must then survive to the screen: a texture buried under a nearly opaque color wash ships the wash, not the material, so judge every material by the screenshot beside the comp, never by the stylesheet. Only when reproduction holds does phase two begin: static regions that should live become animated or interactive, reveals and motion are added, then responsiveness across the surface's devices. Where the comp does not cover the whole surface, continue building the remainder inside the comp's recorded world and design language; a component the comp never shows inherits the recorded system's corner language, line weights, and materials, and may not introduce container styles, border weights, or chrome the comp never uses.
+
 Build the assigned direction, not a safer interpretation of it. The form supplies structure, reading order, component conventions, and native motion; the product supplies every fact. Commit every atom: nav, buttons, inputs, and links are rebuilt in the form's vocabulary, and a stock component inside a committed form is a lapse. Land the first build fully committed; committing is the hard part, and the passes that follow exist to make the committed thing clear and effective, never to dilute it. In unattended work, the safe rendition is the known risk.
 
 - **The first viewport is a thesis, not a header.** Demonstrate the mechanism immediately, at the scale the form has in life; do not trap the concept inside a standard hero or card shell. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood, the concept has not committed yet.
-- **Prove, don't claim.** Show the subject doing its job: the interface at work, the mechanism dramatized, specifics a competitor could not copy-paste. Sections that restate a claim in different words add length, not substance. Demonstration data is design material: author it at full fidelity and label it synthetic; never invent prices, customers, benchmarks, or capabilities.
-- **Author the assets; never substitute chrome.** Great surfaces live on carefully made content: names, entries, copy, covers, thumbnails, textures. In greenfield work every blank the ask round left open is yours to author at production fidelity; content is authorable, claims are labelable, no section is omittable. An unanswered commercial claim ships as a clearly marked placeholder on the user's replacement list. When image generation exists, producing the design's imagery is part of building, at the scale the composition needs: a viewport that wants atmosphere gets a full-bleed layered scene, and a library of small centered subjects standardized for tidiness forecloses that before a line of code exists. Gradients, glass, and generic icon tiles where an authored asset belongs are the gap wearing chrome; icons drawn in the world's own grammar are the remedy, not the target.
+- **Prove the hero before building past it.** When an approved comp exists, render the first viewport, capture it, and set it beside the comp's first viewport before any later section: the hero carries the run's ambition, and every following section inherits its shortfall. Judge scale and density as quantities, a field at a tenth of the comp's coverage or type at half its weight is a different design, and a five-minute retry here is what a rebuild verdict at the finish costs when this check is skipped.
+- **Prove, don't claim.** Show the subject doing its job: the interface at work, the mechanism dramatized, specifics a competitor could not copy-paste. Sections that restate a claim in different words add length, not substance. Demonstration data is design material: author it at full fidelity and label it synthetic; claims stay uninventable.
+- **Author the assets; never substitute chrome.** Great surfaces live on carefully made content: names, entries, copy, covers, thumbnails, textures. In greenfield work every blank the ask round left open is yours to author at production fidelity; content is authorable, claims are labelable, no section is omittable. An unanswered commercial claim ships as a clearly marked placeholder on the user's replacement list. When image generation exists, producing the design's imagery is part of building, at the scale the composition needs: a viewport that wants atmosphere gets a full-bleed layered scene, and a library of small centered subjects standardized for tidiness forecloses it. Gradients, glass, and generic icon tiles where an authored asset belongs are the gap wearing chrome; icons drawn in the world's own grammar are the remedy, not the target.
 - **Build the form's web leverage.** When the chosen world names a technique (canvas, WebGL, view transitions, generative motion), build the technique itself, not a static imitation of it; the graceful fallback serves constrained clients, it is not the default experience.
 - **Pace the scroll like a studio.** Vary density, scale, image, motion, and quiet inside one grammar; a dense passage earns a quiet one, and the page ends anchored by a real close. One spacing rhythm throughout, with more space above a heading than below it.
 - **Use real, verified imagery when the brief implies it.** Search for the subject's physical object rather than the category; one decisive photo beats five mediocre ones. Verify stock URLs resolve.
@@ -100,8 +103,8 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 ## 7. Inspect and finish
 
-Inspect desktop and mobile in one batched screenshot round, critique the render against the user's request and the direction contract, fix material gaps, and confirm with one final round; two rounds is the ceiling, and fixes batch between them rather than earning per-tweak screenshots. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary.
+Inspect desktop and mobile in one batched screenshot round, critique the render against the user's request and the direction contract, fix material gaps, and confirm with one final round; two rounds is the ceiling, and fixes batch between them rather than earning per-tweak screenshots. When an approved comp exists, the critique is a side-by-side: view the comp region and the build region together, the hero and each section as its own crop at legible scale, never one full-page thumbnail, which hides exactly the failures that matter, crude controls, wrong lettering character, flattened material, behind a superficially similar section order. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary.
 
-After the second inspection round the build thread's polishing is over: no further defect hunts, micro-edit scripts, or rebuilds here; whatever remains ships through the handoffs, where a fresh context does the finding better and cheaper. Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, and the QUALITY BAR card and approved comp paths. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, run from [degraded/finish-reviewer.md](degraded/finish-reviewer.md), and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. Apply the material fixes in one batch, rebuild once, and recapture the same viewports. A recapture measures positions, loading, and overflow; it cannot measure whether a fix reached the quality the finding named, so send the recaptured screenshots back to the same reviewer for a verdict scoring every material fix resolved, partial, or unresolved (through the harness's agent continuation; without one, run the scoring fresh from [degraded/finish-reviewer.md](degraded/finish-reviewer.md)'s Verdict Pass). Fixes scored partial or unresolved get exactly one more batch, recapture, and verdict; two correction rounds is the ceiling, the second verdict ends the work whatever it says, and the reviewer's findings are the only list you work from, never your own re-opened hunt. Report the final verdict table to the user as it stands, open items included: presenting mechanical confirmation as artistic success is how a failed build gets announced as a finished one. Do not run a second detector.
+After the second inspection round the build thread's polishing is over: no further defect hunts, micro-edit scripts, or rebuilds here; whatever remains ships through the handoffs, where a fresh context does the finding better and cheaper. Where this harness runs no design hook, run `node .claude/skills/impeccable/scripts/detect.mjs --json` on the changed targets once here, fix what is mechanical, and pass the remaining findings to the reviewer; a hookless build that skips this ships every tell the hook exists to catch. Capture desktop and mobile screenshots to files, then spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex; `/impeccable-finish-reviewer` in Cursor; on GitHub Copilot say "Use the impeccable-finish-reviewer agent"), with the original request, confirmed answers, the artifact path, the screenshot paths, its direction contract, existing hook findings, the QUALITY BAR card and approved comp paths, and the craft-floor reference path. The reviewer has no browser; screenshots you fail to pass are checks it cannot run. Never read the shipped agents' definition files before spawning; the harness loads them at spawn, and you owe only the input packet. Wait on any agent with one long timeout rather than a loop of short polls, and spend the wait on the next independent step. Verify its return carries the five contract sections; on an empty or thrashed return, respawn once with the same inputs before doing anything else. This review never runs inside the build thread and never inherits it: spawn the reviewer fresh, with no forked conversation history (`fork_turns: 0` in codex); a reviewer that inherits your transcript inherits your framing, your optimism, and your abstractions, and everything it needs travels in the inputs above. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, run from [degraded/finish-reviewer.md](degraded/finish-reviewer.md), and a substituted or failed-and-replaced review is disclosed in one line at finish, never silently. When the reviewer's first material fix is a rebuild directive, fidelity failed wholesale rather than in patches, so skip the fix batch and execute the rebuild immediately: re-derive the named regions, produce the named assets, and send the result back for a verdict, telling the user what is happening rather than asking permission to fix a failure. The user is consulted only when a second rebuild directive arrives, both verdicts on the table, or when rebuilding would discard content the user approved. Otherwise apply the material fixes in one batch, rebuild once, and recapture the same viewports. A recapture measures positions, loading, and overflow; it cannot measure whether a fix reached the quality the finding named, so send the recaptured screenshots back to the same reviewer for a verdict scoring every material fix resolved, partial, or unresolved (through the harness's agent continuation; without one, run the scoring fresh from [degraded/finish-reviewer.md](degraded/finish-reviewer.md)'s Verdict Pass). Fixes scored partial or unresolved get another batch, recapture, and verdict. Two rounds is the budget an unattended run ends at; an attended session's ceiling belongs to the user, so when the second verdict still lists open items, put the table in front of them and let them choose between shipping as it stands and funding another round. Whoever is deciding, stop the moment a round resolves nothing, and the reviewer's findings are the only list you work from, never your own re-opened hunt. Report the final verdict table to the user as it stands, open items included, under the reviewer's own disposition word: a table with open material findings is never announced as a pass, and never under a softer label than the reviewer wrote. Do not run a second detector.
 
 Then spawn the shipped documenter, `impeccable-documenter` (`impeccable_documenter` in codex), with the project root, the artifact path, the direction contract, PRODUCT.md, the [document.md](document.md) reference path, and the boundary to write at; it records DESIGN.md and the sidecar from the built world, ground truth over intention; without subagents the pass runs from [degraded/documenter.md](degraded/documenter.md). A clean detector pass is not finished; finished is the contract kept, the comp honored, the review closed, and the system recorded.

.claude/skills/impeccable/reference/visualize.md

@@ -6,8 +6,9 @@ The purpose of a probe is to test composition, narrative, hierarchy, density, fo
 
 ## Generate three compositional options
 
-Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session; record the approved comp's path in the surface brief. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
+Render three distinct high-fidelity north-star comps of the requested surface, with whatever generation capability exists, saved under `.impeccable/mocks/` so they survive the session. Comp at the surface's own viewport: portrait at device size for a native app or mobile-first surface, desktop landscape otherwise; a phone screen comped landscape misstates the composition before anything gets built against it. Comps are the build thread's own work, never delegated: the thread that writes the comp prompts holds the direction's full context, and it has already seen every comp when the build starts. Open every image you produce or reference by its workspace-relative path, never an absolute one: sandboxed viewers reject absolute paths, and everything under the project root has a relative path. Base them on the real content and the surface concepts already developed with the user. Three is the number: one comp invites rubber-stamping, and the spread between three is what surfaces the composition worth building. A decision-page sketch is not a probe: it chose the direction at deliberately unfinished fidelity, so the three comps render regardless, and the chosen card's sketch seeds at most one of them.
 
+- A comp is a designed surface, not a picture of the subject. Lead the generation prompt with the surface's own structure, whatever regions this design actually has, named in order with their scale relationships; a page with no navigation states that instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with the world's atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. Self-check every render: if it could hang as a poster, or reads as a photograph or scene with some text on it, it is not a comp; regenerate with the layout scaffold stated more literally.
 - When the user shortlisted multiple concepts, spread the three across them.
 - When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing.
 - Show enough beyond the opening moment to prove the concept can govern the whole requested surface.
@@ -21,18 +22,28 @@ Show the three together: in the harness when it can display images, otherwise on
 
 Do not begin code until the user approves a direction or explicitly delegates the choice. If they delegate, choose using the task brief, PRODUCT.md, and DESIGN.md, and state the evidence. Approval refines the task concept; it does not modify DESIGN.md.
 
-After approval, summarize the composition and the parts of the comp that must not be literalized. Return to new-work.md, record the direction contract from the approved surface concept, then build.
+This approval point has no substitute and no skip condition. When the structured question tool errors, fall back to the decision page; only after both fail may you treat the choice as delegated, and a delegated pick is still recorded exactly as an approval is and disclosed in your first reply, not your last. The finish reviewer treats a build with generated comps and no recorded approval as carrying a material finding.
+
+After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and the approved comp's `.json` prompt sidecar gains `"approved": true` (every comp generated through `generate-image.mjs` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief. Then summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved surface concept, and build.
 
 ## Inventory implementation fidelity
 
-Before building, inventory the approved comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. The same written inventory names the comp's compositional commitments: navigation items and icons, headline levels and their scale relationship, signature geometry such as seams, masks, and overlaps, and each section's arrangement and density. An element never written down is the element the build silently drops, and the direction contract's 150 words cannot carry this list, so this inventory is where it lives. Textures, portraits, and scenes are raster-by-default; a CSS gradient is not a texture medium. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped.
+Before building, read the approved comp as a design system and record it in the brief: component grammar, corner language, line weights, elevation treatment, and the type ramp, because everything the comp does not show gets built from this record, and without it the fallback is the model's stock kit of square boxes, 1px grids, bento cells, and hard shadows. Then inventory the comp's major visible ingredients in writing (a short table in the surface brief or working notes; the finish reviewer audits shipped assets against it) and choose an implementation medium for each: semantic HTML/CSS/SVG, existing project asset, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. The same written inventory names the comp's compositional commitments: navigation items and icons, headline levels and their scale relationship, signature geometry such as seams, masks, and overlaps, and each section's arrangement and density. The primary action gets its own row with its own medium: when the comp dissolves, stamps, erodes, or otherwise physically works the main CTA, that treatment is signature material on the page's most important element, and shrinking it to a border trick or a few decorative pixels is the compliance-token version of commitment. An element never written down is the element the build silently drops, and the direction contract's 150 words cannot carry this list, so this inventory is where it lives.
 
-Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies. If the concept depends on a photograph, architectural scene, product object, portrait, or other raster-native material, do not silently replace it with generic CSS scenery.
+The medium column is where an approved design most often dies, so it obeys a gate: the medium is decided by what the comp region shows, never by what feels buildable in the current stack. A human figure, a product object, machinery, or any material with lighting and depth is raster whatever the stack, and so is any texture by that name alone: woven cloth, paper grain, fabric, leather, brushed metal need no depth argument, because a CSS gradient or layered background is not a texture medium and "layered CSS textures" is not a medium at all. Writing "silhouette" for a photographic figure, or "CSS" for a sculpted panel's finish or a cotton field's weave, is not a medium choice, it is the quiet deletion of the approved design, and it is how a comp full of physical material becomes a flat page with the same section order. Style does not move this boundary: a comp region with perspective, shading, figure drawing, or dense mechanical detail is illustration however line-drawn it looks, and no build session can author illustration as vectors, so it regenerates as raster like any photograph. Authored SVG covers what a session can specify exactly, diagrams with countable elements, controls, flat shape systems, and it ends where drawing skill begins; an instruction-manual world does not convert its illustrations into diagrams, it makes them line-art illustrations. Produce such regions by regenerating them cleanly, with the approved comp and its embedded prompt as the reference for a fresh render at asset resolution; never crop pixels out of the comp itself, whose effective resolution sits far below asset grade. Dropping an image-native region instead of producing it is a scope decision the user makes at the approval point, never a silent flattening after it. Generated imagery is a material, not a claim: evidence rules bind assertions, specs, testimonials, and photographs presented as real, never render fidelity, so "no photography on hand" forbids fake proof, not an illustrated hero.
+
+The gate runs both ways: precise geometry, hard-edged shape systems, diagrams, expressive motion, shaders, and anything interactive are vector and GPU territory (SVG, canvas, WebGL), where a raster flattens what should move, scale, and respond, and code executed safely and professionally remains first-class there. A field or texture built from many small elements carries a quantity commitment either way: write down its approximate density and coverage ("thousands of glyphs over two-thirds of the fold, dense at the top fading into the path"), because a field rebuilt at a tenth of its density passes every checklist and still is not the design. TYPE rows carry the same discipline: name the face's compression class, and render one headline word against the comp before building on it; a visibly wider or lighter silhouette means the face is wrong, and every section built on it inherits the miss. Raster is for what the world paints; code is for what the world draws, animates, or reacts with, and choosing code there is ambition, not economy. Every `produce` entry is produced before the build ships, through the asset producer or in the current thread; an inventory with unproduced entries is an unfinished build, and this gate is where imagery-free pages come from when it is skipped.
+
+Pay special attention to the dominant composition, signature use, image-native content, second-fold system, and any interaction the still image only implies.
 
 Treat the comp as a north star, not something to trace, and know what that allows: translation into semantic, responsive, accessible code, never recomposition. Keeping the palette and mood while redrawing the topology is a second art direction, not an adaptation. Do not rasterize core UI text or controls. Do not substitute a different visual driver after approval without asking.
 
 ## Produce only the assets the build needs
 
-When clean raster ingredients are required and the harness runs subagents, use the shipped asset producer, `impeccable-asset-producer` (`impeccable_asset_producer` in codex): give it the approved comp, output paths, required dimensions and formats, transparency needs, crop notes, and what must remain semantic code. Otherwise produce the minimum required assets in the current thread by the book: load [degraded/asset-producer.md](degraded/asset-producer.md) and follow it inline, with whatever generation exists, the native tool or generate-image.mjs.
+Generation context is part of the asset: a build composed by a thread that never saw the prompts places assets it does not understand. So prefer generating build-critical imagery in the build thread when the budget allows, and when a subagent produces assets instead, every asset must carry its prompt, and the builder reads those prompts before composing a single one of them. The carrier is uniform across harnesses: after generating any image with any tool, native or `generate-image.mjs` (which does it automatically), run `node .claude/skills/impeccable/scripts/embed-prompt.mjs <image> --prompt "<the prompt used>"` so the intent lives inside the file itself and survives copies between machines and harnesses; `--read` recovers it from any impeccable-generated image.
+
+When the harness runs subagents, spawn the shipped asset producer every time, even when the inventory's produce bucket looks empty: its manifest is the independent second opinion on your media, and runs that skipped the spawn are the runs whose cotton became CSS. An honestly empty manifest costs one cheap spawn; a wrongly empty produce bucket costs the build its materials. Use the producer, `impeccable-asset-producer` (`impeccable_asset_producer` in codex; `/impeccable-asset-producer` in Cursor; on GitHub Copilot say "Use the impeccable-asset-producer agent"): give it the approved comp, output paths, required dimensions and formats, transparency needs, crop notes, and what must remain semantic code. Otherwise produce the minimum required assets in the current thread by the book: load [degraded/asset-producer.md](degraded/asset-producer.md) and follow it inline, with whatever generation exists, the native tool or generate-image.mjs.
+
+Convert images with a converter context.mjs reported at boot (the IMAGE_TOOLS line); probe only when it reported none, at most once per session, never per image.
 
 Return to [new-work.md](new-work.md) for the direction contract, implementation, and the finishing pass.

.claude/skills/impeccable/scripts/concept-seed.mjs

@@ -29,7 +29,7 @@
  *     win over thin categories, which is the intended shape.
  *   - RE-ROLL (--reroll <n>): round n of the same base key. The script
  *     recomputes what rounds 0..n-1 drew, excludes all of it, and rolls a
- *     fresh assigned index, challengers, and staging. One base key therefore
+ *     fresh assigned index, challengers, and compositions. One base key therefore
  *     reproduces the entire chain of rounds.
  *   - RATINGS: the reviewer's approval ratings weight the challenger draw
  *     (3-star doubles the odds, 1-star sits out); the approved pool itself
@@ -38,13 +38,26 @@
  * Usage:
  *   node scripts/concept-seed.mjs --scope direction --mode persuade
  *   node scripts/concept-seed.mjs --scope surface --mode operate --from <key>
+ *   node scripts/concept-seed.mjs --scope surface --mode operate --grain flow
  *   node scripts/concept-seed.mjs --scope direction --candidate-count 6
  *   node scripts/concept-seed.mjs --scope direction --mode persuade --from <key> --reroll 1
  *   node scripts/concept-seed.mjs --chosen <challenger-id> --from <key> --scope direction
  *
+ * --grain names how much of the product is in play: product, flow, view, or
+ * region. A docs site, an onboarding flow, a landing page and a data table are
+ * four different amounts of product and want different compositions. Grain is a
+ * preference: it deals matching compositions first and tops up from the rest of
+ * the register, and the rendered seed says how many actually matched so a
+ * borrowed structure is never mistaken for a supplied one.
+ *
+ * --platform names the delivery target (web, ios, android). Unlike grain this is
+ * a hard filter: a composition that needs hover or a pointer does not degrade on
+ * a phone, it stops working. --mode also gates which worlds are eligible, for
+ * worlds whose reviewer marked them as carrying only some modes.
+ *
  * --mode names the requested surface's mode (persuade, operate, read,
- * experience) so the appended staging matches its register of work; omitted,
- * the staging rolls from the full approved pool.
+ * experience) so the appended compositions match its register of work; omitted,
+ * they roll from the full approved pool.
  *
  * Challenger data resolves in order: a local catalog directory (the private
  * service repo, evals, and tests set IMPECCABLE_CATALOG_DIR), then the roll
@@ -64,12 +77,18 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   approvedPoolRevision,
-  deterministicRank,
   readConceptCatalog,
   validateConceptCatalog,
   WELL_TIERS,
 } from './lib/concept-catalog.mjs';
 import { readCompositionCatalog } from './lib/composition-catalog.mjs';
+import {
+  COMPOSITION_GRAINS,
+  COMPOSITION_PLATFORMS,
+  runSyncSelection,
+  selectApprovedChallengers as selectApprovedChallengersCore,
+  selectApprovedCompositions as selectApprovedCompositionsCore,
+} from './lib/roll-selection.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -123,9 +142,11 @@ function requireLocalConcepts() {
   return local;
 }
 
-async function fetchRoll({ scope, key, mode, reroll }) {
+async function fetchRoll({ scope, key, mode, grain, platform, reroll }) {
   const params = new URLSearchParams({ scope, key, reroll: String(reroll) });
   if (mode) params.set('mode', mode);
+  if (grain) params.set('grain', grain);
+  if (platform) params.set('platform', platform);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), apiBudgetMs());
   try {
@@ -187,151 +208,44 @@ ${system}
      QUALITY BAR: board ${board} · hero ${hero}`;
 }
 
-export function renderStaging(composition, index = null) {
+export function renderComposition(composition, index = null) {
   const grammar = composition.grammar.map(rule => `       - ${rule}`).join('\n');
   return `  ${index == null ? '' : `${index + 1}. `}${composition.form}
      SOURCE ID: ${composition.id}
      SPARK: ${composition.spark}
-     STAGING GRAMMAR:
+     COMPOSITION GRAMMAR:
 ${grammar}
      WEB LEVERAGE: ${composition.webLeverage}`;
 }
 
-// Three approved, identity-free staging inputs are rolled deterministically.
-// One input was too weak a counterweight to a model's habitual page skeleton:
-// it became a single optional flourish beside six identity challengers rather
-// than a real search over composition. Prefer distinct staging families so a
-// roll tests materially different hierarchy, sequence, and interaction laws.
-// Cross-mode fallback would make the input misleading, so an absent mode still
-// returns no staging. Re-rolls exclude every earlier set until the pool runs out.
-export function selectApprovedStagings({ scope, key, reroll = 0, mode = null, sourceCompositions = null, count = 3 }) {
-  const pool = sourceCompositions ?? requireLocalConcepts().compositions;
-  // Stagings honour the same breadth gate as worlds: a staging too specific to
-  // serve an arbitrary build stays approved for direct briefs and leaves the
-  // challenger pool. Falls back to the full approved set rather than returning
-  // nothing if every approved staging is marked niche.
-  let approved = pool.filter(composition => composition.status === 'approved');
-  const broad = approved.filter(composition => composition.review?.breadth !== 'niche');
-  if (broad.length > 0) approved = broad;
-  if (approved.length === 0) return [];
-  if (mode) {
-    const matching = approved.filter(composition => composition.surface === mode);
-    if (matching.length === 0) return [];
-    approved = matching;
-  }
-  const prior = new Set();
-  let picks = [];
-  for (let round = 0; round <= reroll; round += 1) {
-    const available = approved.filter(composition => !prior.has(composition.id));
-    const ranked = deterministicRank(
-      available.length >= Math.min(count, approved.length) ? available : approved,
-      round === 0 ? `${scope}:${key}:staging` : `${scope}:${key}:staging:reroll-${round}`
-    );
-    const families = new Set();
-    picks = [];
-    for (const composition of ranked) {
-      const family = composition.familyId ?? composition.id;
-      if (families.has(family)) continue;
-      picks.push(composition);
-      families.add(family);
-      if (picks.length >= count) break;
-    }
-    for (const composition of ranked) {
-      if (picks.length >= count) break;
-      if (!picks.some(pick => pick.id === composition.id)) picks.push(composition);
-    }
-    if (round < reroll) picks.forEach(composition => prior.add(composition.id));
-  }
-  return picks;
+// Selection itself lives in lib/roll-selection.mjs so this script and the roll
+// API run one algorithm rather than two that drifted. These wrappers add only
+// what is local to the skill: resolving the catalog when no pool is passed, and
+// driving the generator with Node's synchronous hash, which keeps a local render
+// synchronous for prepared eval sessions and tests.
+function driveSelection(generator) {
+  return runSyncSelection(generator, input => crypto.createHash('sha256').update(input).digest('hex'));
+}
+
+export function dealCompositions({ scope, key, reroll = 0, mode = null, grain = null, platform = null, sourceCompositions = null, count = 3 }) {
+  const compositions = sourceCompositions ?? requireLocalConcepts().compositions;
+  return driveSelection(selectApprovedCompositionsCore({ scope, key, reroll, mode, grain, platform, compositions, count }));
+}
+
+// Array-returning form, which is what every caller wanted before the match
+// report existed.
+export function selectApprovedCompositions(options) {
+  return dealCompositions(options).picks;
 }
 
 // Compatibility for callers that need a single smoke-test sample.
-export function selectApprovedStaging(options) {
-  return selectApprovedStagings({ ...options, count: 1 })[0] ?? null;
+export function selectApprovedComposition(options) {
+  return selectApprovedCompositions({ ...options, count: 1 })[0] ?? null;
 }
 
-export function selectApprovedChallengers({ scope, key, reroll = 0, sourceConcepts = null }) {
+export function selectApprovedChallengers({ scope, key, reroll = 0, mode = null, sourceConcepts = null }) {
   const source = sourceConcepts ?? requireLocalConcepts().concepts;
-  const approved = source.filter(concept => concept.status === 'approved');
-  // Direction chooses a durable identity, so it draws worlds; surface designs
-  // one page inside a committed identity, so it draws stagings. Duals serve
-  // both. A tier with no matching-strength approvals falls back to its full
-  // approved pool rather than starving the roll.
-  const wanted = scope === 'direction'
-    ? new Set(['world', 'dual'])
-    : new Set(['composition', 'dual']);
-  const approvedByTier = new Map();
-  for (const concept of approved) {
-    const tier = approvedByTier.get(concept.wellTier) || [];
-    tier.push(concept);
-    approvedByTier.set(concept.wellTier, tier);
-  }
-  if (WELL_TIERS.some(tier => !(approvedByTier.get(tier) || []).length)) {
-    throw new Error('concept-seed: every challenger tier needs at least one approved concept');
-  }
-  for (const [tier, pool] of approvedByTier) {
-    const matching = pool.filter(concept => wanted.has(concept.strength));
-    if (matching.length > 0) approvedByTier.set(tier, matching);
-  }
-  // Two challengers per tier, so every roll carries near-zero-translation
-  // graphic systems beside instrument languages and atmosphere worlds, with
-  // the second pick preferring a different family for diversity. Tier order
-  // in the rendered list is rolled too, to avoid positional bias.
-  // Two separate axes, and both can exclude. Rating grades quality: a 3-star
-  // earns a second ticket, a 1-star marginal keep leaves the pool. Breadth says
-  // whether a world can serve an arbitrary build at all, so a niche world
-  // leaves the pool however good it is. Breadth was split out of rating because
-  // the only way to hold a narrow world back used to be calling it marginal,
-  // which made "excellent but narrow" unrecordable and corrupted the ratings as
-  // a calibration signal for the next authoring round.
-  const ticketsFor = pool => pool.flatMap(concept => {
-    const rating = concept.review?.rating;
-    // Two independent exclusions: a marginal world is too weak to challenge,
-    // a niche world too narrow. Either one keeps its approval for direct
-    // briefs and leaves the pool.
-    if (rating === 1 || concept.review?.breadth === 'niche') return [];
-    return rating === 3
-      ? [{ concept, ticket: 0 }, { concept, ticket: 1 }]
-      : [{ concept, ticket: 0 }];
-  });
-  const pickRound = (round, excluded) => {
-    const salt = round === 0 ? '' : `:reroll-${round}`;
-    const tierOrder = deterministicRank(
-      WELL_TIERS.map(id => ({ id })),
-      `${scope}:${key}:tiers${salt}`
-    ).map(item => item.id);
-    return tierOrder.flatMap((tier, index) => {
-      let pool = approvedByTier.get(tier).filter(concept => !excluded.has(concept.id));
-      // A tier exhausted by prior rounds falls back to reuse over starvation.
-      if (pool.length === 0) pool = approvedByTier.get(tier);
-      let tickets = ticketsFor(pool);
-      if (tickets.length === 0) tickets = pool.map(concept => ({ concept, ticket: 0 }));
-      const ranked = deterministicRank(
-        tickets,
-        `${scope}:${key}:challenger-${index}${salt}`,
-        entry => `${entry.concept.id}#${entry.ticket}`
-      );
-      const order = [];
-      const seen = new Set();
-      for (const entry of ranked) {
-        if (seen.has(entry.concept.id)) continue;
-        seen.add(entry.concept.id);
-        order.push(entry.concept);
-      }
-      const first = order[0];
-      const second = order.find(concept => concept.familyId !== first.familyId)
-        || order.find(concept => concept.id !== first.id);
-      return second ? [first, second] : [first];
-    });
-  };
-  // Round n of a re-roll chain excludes everything rounds 0..n-1 drew, so the
-  // same base key reproduces the whole chain.
-  const excluded = new Set();
-  let picks = pickRound(0, excluded);
-  for (let round = 1; round <= reroll; round += 1) {
-    for (const pick of picks) excluded.add(pick.id);
-    picks = pickRound(round, excluded);
-  }
+  const { approved, picks } = driveSelection(selectApprovedChallengersCore({ scope, key, reroll, mode, concepts: source }));
   return {
     approved,
     picks,
@@ -347,6 +261,8 @@ export function renderConceptSeed({
   key = process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex'),
   reroll = 0,
   mode = null,
+  grain = null,
+  platform = null,
   candidateCount = 7,
   catalogDir = CATALOG_DIR,
   _resolvedData = undefined,
@@ -360,6 +276,14 @@ export function renderConceptSeed({
   if (mode !== null && !SEED_MODES.has(mode)) {
     throw new Error('concept-seed: --mode must be persuade, operate, read, or experience');
   }
+  // Grain needs no mode: how much of the product is in play is independent of
+  // which register of work it is.
+  if (grain !== null && !COMPOSITION_GRAINS.includes(grain)) {
+    throw new Error(`concept-seed: --grain must be one of ${COMPOSITION_GRAINS.join(', ')}`);
+  }
+  if (platform !== null && !COMPOSITION_PLATFORMS.includes(platform)) {
+    throw new Error(`concept-seed: --platform must be one of ${COMPOSITION_PLATFORMS.join(', ')}`);
+  }
   if (!Number.isInteger(candidateCount) || candidateCount < 5 || candidateCount > 7) {
     throw new Error('concept-seed: --candidate-count must be an integer from 5 to 7');
   }
@@ -381,6 +305,7 @@ export function renderConceptSeed({
         scope,
         key,
         reroll,
+        mode,
         sourceConcepts: local.concepts,
       });
       data = {
@@ -389,16 +314,21 @@ export function renderConceptSeed({
         approvedCount: approved.length,
         catalogCount,
         challengers: picks,
-        stagings: selectApprovedStagings({ scope, key, reroll, mode, sourceCompositions: local.compositions }),
+        ...(() => {
+          const dealt = dealCompositions({ scope, key, reroll, mode, grain, platform, sourceCompositions: local.compositions });
+          return { compositions: dealt.picks, compositionMatch: dealt.match };
+        })(),
       };
     } else {
       // Keep local renders synchronous for prepared eval sessions and tests;
       // installed skills without a bundled catalog resolve through the API.
-      return fetchRoll({ scope, key, mode, reroll }).then(roll => renderConceptSeed({
+      return fetchRoll({ scope, key, mode, grain, platform, reroll }).then(roll => renderConceptSeed({
         scope,
         key,
         reroll,
         mode,
+        grain,
+        platform,
         candidateCount,
         catalogDir,
         _resolvedData: roll ? {
@@ -407,7 +337,11 @@ export function renderConceptSeed({
           approvedCount: roll.approvedCount,
           catalogCount: roll.catalogCount,
           challengers: roll.challengers,
-          stagings: Array.isArray(roll.stagings) ? roll.stagings : roll.staging ? [roll.staging] : [],
+          compositions: Array.isArray(roll.compositions)
+            ? roll.compositions
+            : Array.isArray(roll.stagings)
+              ? roll.stagings
+              : roll.staging ? [roll.staging] : [],
         } : null,
       }));
     }
@@ -471,13 +405,18 @@ ASSIGNED INDEX: ${buildIndex}
   The assignment exists to refuse the model's ranking rut, never to outrank
   the user or the brief. Never expose assignment metadata in user-facing labels.
 No challengers this run: the roll service was unreachable and no local
-catalog exists. A sandboxed exec tool with no network access causes exactly
-this; before accepting degradation, rerun this command once through the
-harness's network-enabled command tool. A sandboxed shell without network egress is the most common
-cause: if this harness can rerun the command with network access granted,
-do that once before proceeding. Otherwise proceed with the grounded
-candidates alone; the assignment
-above still applies at full strength. Tell the user plainly that this roll
+catalog exists. A sandboxed shell without network egress is the most common
+cause; before accepting degradation, rerun this command once through the
+harness's network-enabled or escalated command tool. When that rerun needs
+an approval, state exactly what the approver must know: this script's only
+network contact is one GET to https://impeccable.style/api/roll whose query
+carries scope, mode, an eight-hex seed key, and a re-roll counter; no
+project files, prompts, code, or conversation context are transmitted, and
+nothing is written. An approval request naming that URL and payload judges
+the real action; a bare "run with network" invites rejection for contacting
+an unspecified domain. If the rerun is still refused, proceed with the
+grounded candidates alone; the assignment above still applies at full
+strength. Tell the user plainly that this roll
 ran degraded, with no challengers and no quality-bar boards; do not present
 the outcome as a full roll. A degraded roll changes the cards, not the
 channel: when a browser can open, present the direction on the decision page
@@ -490,15 +429,46 @@ ${buildIndex} of your own grounded list; seed key ${key}.
 `;
   }
 
-  const stagings = Array.isArray(data.stagings)
-    ? data.stagings
-    : data.staging ? [data.staging] : [];
-  const stagingBlock = stagings.length > 0
-    ? `\n${scope === 'direction' ? 'FIRST-SURFACE STAGING INPUTS (identity-free; test them with shortlisted worlds and keep world plus staging one decision):' : 'STAGING CHALLENGERS (identity-free; dress them in the committed visual identity before judging):'}
-${stagings.map((staging, index) => renderStaging(staging, index)).join('\n')}
-Stagings organize attention, sequence, and manipulation; they never bring a
-palette, typeface, or material. Use them as serious alternatives to the model's
-habitual composition, but keep only structures that strengthen this product.\n`
+  // Field order is the migration: `compositions` is current, `stagings` is what
+  // the API emitted while these were called stagings, and `staging` is the
+  // single-pick shape from before it dealt three. Older installs keep working.
+  // Compositions are pulled from the deal until the expanded catalog is
+  // ready for prime time: the current pool crowds the decision more than it
+  // widens it. IMPECCABLE_COMPOSITIONS=1 re-enables rendering for catalog
+  // development; the draw machinery, axes, and grain report stay intact.
+  const compositionsEnabled = process.env.IMPECCABLE_COMPOSITIONS === '1';
+  const compositions = !compositionsEnabled ? []
+    : Array.isArray(data.compositions)
+      ? data.compositions
+      : Array.isArray(data.stagings)
+        ? data.stagings
+        : data.staging ? [data.staging] : [];
+  // The grain report. A top-up keeps the deal at three, which is right, but it
+  // must not read as three on-target inputs: a flow request answered entirely by
+  // view-grain compositions means the model has to derive the flow's own
+  // structure and borrow only their sequence law. Silence here would reproduce
+  // the exact failure this axis exists to fix.
+  const match = data.compositionMatch ?? null;
+  const grainNote = (() => {
+    if (!match?.grain) return '';
+    if (match.grainAvailable === 0) {
+      return `\nNONE of these sit at the requested ${match.grain} grain, because the catalog holds no ${match.grain}-grain composition yet. Derive that structure yourself and borrow only their sequence and attention laws.`;
+    }
+    if (match.atGrain === 0) {
+      return `\nNONE of these sit at the requested ${match.grain} grain, though ${match.grainAvailable} exist; these were topped up from the rest of the register. Treat their structure as borrowed.`;
+    }
+    if (match.atGrain < compositions.length) {
+      return `\n${match.atGrain} of ${compositions.length} sit at the requested ${match.grain} grain; the rest were topped up from the register and their structure is borrowed.`;
+    }
+    return '';
+  })();
+  const compositionBlock = compositions.length > 0
+    ? `\n${scope === 'direction' ? 'FIRST-SURFACE COMPOSITION INPUTS (identity-free; test them with shortlisted worlds and keep world plus composition one decision):' : 'COMPOSITION CHALLENGERS (identity-free; dress them in the committed visual identity before judging):'}
+${compositions.map((composition, index) => renderComposition(composition, index)).join('\n')}
+Each one asks the same question of this build: what is the cleverest way to
+present, organize, or make interactive the problem in front of you? They carry
+structure only, never a palette, typeface, or material. Treat them as serious
+rivals to your habitual layout, and keep only what makes this product clearer.${grainNote}\n`
     : '';
   const rerollBlock = reroll > 0
     ? `RE-ROLL ROUND ${reroll}: every candidate presented in earlier rounds, grounded
@@ -519,7 +489,7 @@ ${rerollBlock}ASSIGNED INDEX: ${buildIndex}
   the user or the brief. Never expose assignment metadata in user-facing labels.
 CHALLENGERS:
 ${data.challengers.map(renderChallenger).join('\n')}
-${stagingBlock}${challengerInstruction}
+${compositionBlock}${challengerInstruction}
 When you can view images, open the QUALITY BAR board and hero for any
 challenger you weigh seriously and for the world you build. They exist as a
 craft bar, the finish level and commitment the build is expected to reach,
@@ -538,6 +508,8 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
   const scopeIdx = args.indexOf('--scope');
   const rerollIdx = args.indexOf('--reroll');
   const modeIdx = args.indexOf('--mode');
+  const grainIdx = args.indexOf('--grain');
+  const platformIdx = args.indexOf('--platform');
   const candidateCountIdx = args.indexOf('--candidate-count');
   const chosenIdx = args.indexOf('--chosen');
   try {
@@ -571,6 +543,8 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
           : (process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex')),
         reroll: rerollIdx !== -1 ? Number(args[rerollIdx + 1]) : 0,
         mode: modeIdx !== -1 ? args[modeIdx + 1] : null,
+        grain: grainIdx !== -1 ? args[grainIdx + 1] : null,
+        platform: platformIdx !== -1 ? args[platformIdx + 1] : null,
         candidateCount: candidateCountIdx !== -1 ? Number(args[candidateCountIdx + 1]) : 7,
       }));
     }

.claude/skills/impeccable/scripts/context-signals.mjs

@@ -22,7 +22,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { loadContext, extractPlatform } from './context.mjs';
-import { getCritiqueDir } from './lib/impeccable-paths.mjs';
+import { readLatestSnapshotAcrossTargets } from './critique-storage.mjs';
 
 /** Is there code here at all, or just context files / an empty repo? */
 function hasCode(cwd) {
@@ -34,23 +34,13 @@ function hasCode(cwd) {
 }
 
 /**
- * The most recent critique snapshot across all targets. Filenames are
- * timestamp-prefixed (`<iso>__<slug>.md`), so a lexical sort is chronological.
- * Parses the small frontmatter for score + P0/P1 counts.
+ * Summarize the most recent critique snapshot across all targets.
  */
 function latestCritique(cwd) {
   try {
-    const dir = getCritiqueDir(cwd);
-    if (!fs.existsSync(dir)) return null;
-    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
-    if (!files.length) return null;
-    const newest = files[files.length - 1];
-    const text = fs.readFileSync(path.join(dir, newest), 'utf-8');
-    const front = text.split('---')[1] || '';
-    const get = (k) => {
-      const m = front.match(new RegExp(`^${k}:\\s*(.+)$`, 'm'));
-      return m ? m[1].trim() : null;
-    };
+    const latest = readLatestSnapshotAcrossTargets({ cwd });
+    if (!latest) return null;
+    const get = (key) => latest.meta[key] ?? null;
     const num = (v) => {
       const n = Number(v);
       return Number.isFinite(n) ? n : null;
@@ -61,7 +51,7 @@ function latestCritique(cwd) {
       p0: num(get('p0')),
       p1: num(get('p1')),
       timestamp: get('timestamp'),
-      file: path.relative(cwd, path.join(dir, newest)),
+      file: path.relative(cwd, latest.path),
     };
   } catch {
     return null;

.claude/skills/impeccable/scripts/context.mjs

@@ -27,6 +27,7 @@
  * shape rather than the markdown block.
  */
 import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -1146,6 +1147,7 @@ async function cli() {
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
+    appendImageToolsDirective(parts);
     appendStalenessDirective(parts, ctx, cliOptions);
     if (updateDirective) parts.push(updateDirective);
     process.stdout.write(parts.join('\n\n---\n\n') + '\n');
@@ -1180,6 +1182,7 @@ async function cli() {
       `# NATIVE PLATFORM REFERENCE: ${reference.name.toUpperCase()} (reference/${reference.name}.md)\n\n${reference.content.trim()}`,
     );
   }
+  appendImageToolsDirective(parts);
   appendStalenessDirective(parts, ctx, cliOptions);
   if (!ctx.platform) {
     // A `## Platform` section that names something we don't recognize (a
@@ -1275,9 +1278,10 @@ function appendImageGenDirective(parts) {
   if (!process.env.OPENAI_API_KEY) return;
   const scriptsPath = path.dirname(fileURLToPath(import.meta.url));
   parts.push([
-    'IMAGE_GEN_AVAILABLE: An OpenAI key is present, so image generation works even without a harness-native image tool:',
-    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render).`,
-    'Prefer the harness-native image tool when one exists. Visualizing a direction before building it measurably strengthens the result.',
+    'IMAGE_GEN_AVAILABLE: your harness-native image tool is always the first choice for generation; use it whenever one exists.',
+    'This environment also carries an OpenAI key as the fallback for harnesses with no native tool:',
+    `\`node ${scriptsPath}/generate-image.mjs --prompt "..." --out <file>\` (gpt-image-2, billed to the user's key; say so before the first render, and never reach for it when a native tool exists).`,
+    'Visualizing a direction before building it measurably strengthens the result.',
   ].join(' '));
 }
 
@@ -1332,6 +1336,19 @@ function appendDetectorFallback(parts, ctx) {
 // markdown already in memory, a bounded set of stats, or one of the small JSON
 // files the boot reads regardless. The deep pass (git drift, token divergence,
 // cross-workspace sweep) belongs to the doctor command, not to every session.
+// One boot-time probe replaces every session re-deriving its image toolchain:
+// harnesses and OSes differ (cwebp, sips on macOS, magick, ffmpeg), and the
+// agent should read this line instead of running command -v per image.
+function appendImageToolsDirective(parts) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const found = ['cwebp', 'sips', 'magick', 'ffmpeg'].filter((tool) => {
+    try { return spawnSync(probe, [tool], { stdio: 'ignore' }).status === 0; } catch { return false; }
+  });
+  parts.push(found.length
+    ? `IMAGE_TOOLS: available image converters on this machine: ${found.join(', ')}. Use the first suitable one; never probe again this session.`
+    : 'IMAGE_TOOLS: no image converter found (cwebp, sips, magick, ffmpeg). Ship PNG output unconverted rather than probing per image.');
+}
+
 function appendStalenessDirective(parts, ctx, options) {
   const projectRoot = ctx.projectRoot || process.cwd();
   if (stalenessCheckDisabled([projectRoot, ctx.repoRoot])) return;