Initial plan

Review fallout from removing progressive publication.

The Live benchmark existed to compare atomic against progressive delivery:
compareModelBackedReports measures goToFirstVariantMs improvement of one
over the other. With progressive gone it measures nothing against nothing.
Worse, benchmark-live.mjs still passed `progressive` to bootFixtureSession,
which no longer accepts it, so `--delivery progressive` was silently
ignored and would have emitted reports labeled progressive that actually
ran atomic. Silent wrong data is worse than a crash. It was built for
progressive, so it goes with progressive: benchmark-live.mjs, its lib, its
test, and the bench:live script. If an atomic latency baseline is wanted
later, that is a smaller thing built on purpose.

live-wrap.mjs: sourceOriginalLines was assigned and never read.

Both found by review bots on #381 (Copilot).

Assisted-by: Claude (claude-halva-eap) via Claude Code

.agents/skills/impeccable/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
+version: 3.9.1
 ---
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
@@ -9,11 +10,12 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 You MUST do these steps before proceeding:
 
-1. Run `node .agents/skills/impeccable/scripts/context.mjs` once per session. If you've already seen its output in this conversation, do not re-run it. The script either prints the project's PRODUCT.md (and DESIGN.md when present) as a markdown block, or tells you it's missing. Follow whatever it prints. **If it reports `NO_PRODUCT_MD`, stop and follow `reference/init.md` before doing anything else.** If the output ends with an `UPDATE_AVAILABLE` directive, follow it (ask the user once about updating, then continue). It never blocks the current task.
-2. If the user invoked a sub-command (`craft`, `shape`, `audit`, `polish`, ...), you MUST read `reference/<command>.md` next. Non-optional. The reference defines the command's flow; without it you will skip steps the user expects.
+1. Run `node .agents/skills/impeccable/scripts/context.mjs` once per session; if the runtime shows this skill's loaded base directory, run `node <skill-base-dir>/scripts/context.mjs` instead. Keep cwd/workdir at the user's project, not the skill directory. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and append `--target <path>` to the same command. If you've already seen its output in this conversation, do not re-run it. The script either prints the project's PRODUCT.md (and DESIGN.md when present) as a markdown block, or tells you it's missing. Follow whatever it prints. **If it reports `NO_PRODUCT_MD`:** divert into `reference/init.md` first when the user invoked `init`, `teach`, `craft`, or `shape`, or when their wording clearly maps to one of those from-scratch build flows (for example: "build/create/make a landing page", "design a new app", or "shape a feature"). Captured product context is the point of those flows. For any other command, a scoped evaluate / refine / enhance / fix / iterate request against existing code, do **not** divert into init. The existing code is the context: proceed with the requested command, infer the register from the surface in focus (step 4), and offer `$impeccable init` once as a suggestion the user can take later. A missing PRODUCT.md must never block a scoped request. If the output ends with an `UPDATE_AVAILABLE` directive, follow it (ask the user once about updating, then continue). It never blocks the current task.
+2. If the user invoked a sub-command (`craft`, `shape`, `audit`, `polish`, ...), you MUST read the command's reference next: **`reference/<command>.md`, or the native variant from the Commands table** (e.g. `reference/audit.native.md`) **when the project platform is native** (`ios` / `android` / `adaptive`, per the `context.mjs` directive). One file, not both. Non-optional. The reference defines the command's flow; without it you will skip steps the user expects.
 3. Familiarize yourself with any existing design system, conventions, and components in the code. Read at least one project file (CSS / tokens / theme / a representative component or page). **Required even when you've loaded a sub-command reference in step 2.** Don't reinvent the wheel; use what's there when it works, branch out when the UX wins.
 4. Read the matching register reference. **This is non-optional; skipping it produces generic output.** If the project is marketing, a landing page, a campaign, long-form content, or a portfolio (design IS the product), read `reference/brand.md`. If it is app UI, admin, a dashboard, or a tool (design SERVES the product), read `reference/product.md`. Pick by first match: (1) task cue ("landing page" vs "dashboard"); (2) surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md.
-5. **If the project is brand-new (no existing CSS tokens / theme / committed brand colors found in step 3)**, run `node .agents/skills/impeccable/scripts/palette.mjs` to receive a brand seed color and composition guidance. This is the anchor for your primary brand color. Compose the rest of the palette (bg, surface, ink, accent, muted) around it per the script's instructions. Use OKLCH throughout. **Skip this step only if step 3 found committed brand colors in existing tokens; in that case identity-preservation wins.**
+5. **If PRODUCT.md's `## Platform` is `ios` or `android`**, also read `reference/<platform>.md` (HIG / Material 3 conventions). `adaptive` (cross-platform, ships both) reads both files. `web`, absent, or unrecognized: nothing extra to read. `context.mjs` prints the directive when one applies.
+6. **If the project is brand-new (no existing CSS tokens / theme / committed brand colors found in step 3)**, run `node .agents/skills/impeccable/scripts/palette.mjs` to receive a brand seed color and composition guidance. This is the anchor for your primary brand color. Compose the rest of the palette (bg, surface, ink, accent, muted) around it per the script's instructions. Use OKLCH throughout. **Skip this step only if step 3 found committed brand colors in existing tokens; in that case identity-preservation wins.**
 
 ## Design guidance
 
@@ -29,16 +31,12 @@ Produce ready-to-ship, production-grade code, not prototypes or starting points.
 #### Typography
 
 - Cap body line length at 65–75ch.
-- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
-- Cap font-family count at 3 (display + body + optional mono). More than 3 reads as indecision, not richness. One well-tuned family with weight contrast usually beats three competing typefaces.
 - Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights.
-- No all-caps body copy. Reserve uppercase for short labels (≤4 words), section eyebrows (used sparingly per the Absolute bans), and badges. Sentences in ALL CAPS are unreadable at body sizes.
 - Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing.
 - Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed".
 - Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans.
 
-Two hard typographic ceilings you currently miss:
-- Hero clamp() max ≤ 6rem. 8–11rem (128–176px) reads as comically loud, not bold.
+One hard typographic ceiling you currently miss:
 - Display letter-spacing ≥ -0.04em. Your default of -0.05 to -0.085em on display H1s makes the letters touch and reads as cramped. -0.02 to -0.03em is plenty for tight grotesque display; -0.04em is the floor.
 
 #### Layout
@@ -63,15 +61,6 @@ Two hard typographic ceilings you currently miss:
 
 - Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context.
 
-### Copy
-
-- Every word earns its place. No restated headings, no intros that repeat the title.
-- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
-- **No aphoristic-cadence body copy as a default voice.** Don't fall into the rhythm of "serious statement, then punchy short negation" as the page's recurring voice. If three or more section copy blocks on the page land on a short rebuttal-shaped sentence, rewrite. Specific, not aphoristic.
-- **No marketing buzzwords.** The streamline / empower / supercharge / leverage / unleash / transform / seamless / world-class / enterprise-grade / next-generation / cutting-edge / game-changer / mission-critical family of phrases. Pick a specific noun and a verb that describes what the product literally does.
-- Button labels: verb + object. "Save changes" beats "OK"; "Delete project" beats "Yes". The label should say what will happen.
-- Link text needs standalone meaning. "View pricing plans" beats "Click here"; screen readers announce links out of context.
-
 ### New projects only (when no prior work exists)
 
 #### Color & Theme
@@ -105,7 +94,8 @@ Match-and-refuse. If you're about to write any of these, rewrite the element wit
 - **`border-radius: 32px+` on cards / sections / inputs.** You over-round. Cards top out at 12–16px; full-pill is fine for tags/buttons. Picking 24/28/32/40px on a card is the codex tell; no brand wants "insanely rounded".
 - **Hand-drawn / sketchy SVG illustrations.** Class names like `loose-sketch`, `*-sketch`, `doodle`, `wavy`; `feTurbulence` / `feDisplacementMap` "paper grain" filters; 5-to-30 path crude scenes meant to depict a tangible subject (an otter, a table-and-fork, an album cover). All of these read as amateurish, not whimsical. If you can't render the scene with real assets, ship no illustration. Don't attempt sketchy SVG as a fallback.
 - **`repeating-linear-gradient(...)` stripe backgrounds.** Diagonal stripes in `body:before` or section backgrounds are pure codex decoration. Don't.
-- **"X theater" / "actually X" / "not just X, it's Y" copy.** "Productivity theater", "engagement theater", "growth theater": instant AI slop. Choose a specific noun, not a meta-criticism phrase.
+- **Decorative grid backgrounds.** Two-axis CSS grid overlays built from `linear-gradient(... 1px, transparent 1px)` plus `background-size` are a Codex tell unless the surface is an actual canvas, map, blueprint, or measurement tool. Use product structure, real artifacts, or a plain surface instead.
+- **Meta-criticism copy.** Naming a concept then layering an ironic modifier, or staging a strawman to "correct" it. Make the specific claim instead.
 
 ### The AI slop test
 
@@ -126,7 +116,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
 | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
 | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
-| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) · native: [reference/audit.native.md](reference/audit.native.md) |
 | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
 | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
 | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
@@ -140,34 +130,34 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
 | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
 | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
-| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) · native: [reference/adapt.native.md](reference/adapt.native.md) |
 | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
 | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
 
-Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
+Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
 
 ### Routing rules
 
-1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` you are already in init (setup), so finish that and skip this. Otherwise run `node .agents/skills/impeccable/scripts/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
+1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` the project has no captured context yet, so lead the menu with `$impeccable init` as the top recommendation (one line on why) and still show the rest below; don't silently jump into init. Otherwise run `node .agents/skills/impeccable/scripts/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
 
    Reason over the signals; there is no score to obey:
    - `setup.hasDesign` false while `setup.hasCode` true → `document` (capture the visual system).
    - `critique.latest` is `null` → the project has never been critiqued; for a set-up project with a real surface, offering `$impeccable critique <surface>` is a strong default.
    - `critique.latest` with a low `score` or non-zero `p0` / `p1` → `polish` (it reads that snapshot as its backlog), or re-run `critique` if the snapshot looks stale.
    - `git.changedFiles` pointing at one surface → scope `audit` or `polish` to those files specifically, naming them.
-   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`.
+   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`. **`live` and the bundled `detect.mjs` are web-only.** If `setup.platform` is `ios`, `android`, or `adaptive`, don't lead with either; the browser overlay and the HTML rule engine don't apply to native app code.
    - Otherwise group by intent exactly as init's "Recommend starting points" step does (build new / improve what's there / iterate visually), tailored to `setup.register`.
 
-   **If `scan.targets` is non-empty, run `node .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
+   **If `scan.targets` is non-empty and `setup.platform` is not `ios`/`android`/`adaptive`, run `node .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx; it reads HTML/CSS, so skip it for native projects). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
 
    Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
-2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
-3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
+2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file (on native platforms, the table's native variant; Setup step 2's one-file rule) and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference (same native-variant rule) and proceed as if invoked. If two commands could fit, ask once which.
 4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
 
-If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
+If the first word is `craft` or `shape`, or routing rule 3 clearly maps the user's intent to either command, setup still runs first, but the matching reference ([reference/craft.md](reference/craft.md) or [reference/shape.md](reference/shape.md)) owns the rest of the flow. Both are from-scratch build flows: if setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
 
 `teach` is a deprecated alias for `init`: if the user types it, load [reference/init.md](reference/init.md) and proceed as if they ran `init`.
 
@@ -179,4 +169,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
 node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
 ```
 
-Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+
+## Hooks
+
+`$impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `$impeccable hooks` with any argument.

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

@@ -2,6 +2,7 @@
 
 Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
+**Web only** (mobile web included). Native platforms (`ios` / `android` / `adaptive`) route to [adapt.native.md](adapt.native.md) instead; if the project is native, switch to it now.
 
 ---
 

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

@@ -0,0 +1,58 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+Adapt an existing **native** design (`ios` / `android` / `adaptive`) to a different context: another device class, orientation, platform, or origin. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context, inside the platform conventions of [ios.md](ios.md) / [android.md](android.md); read the target platform's reference before planning if Setup hasn't already.
+
+## Assess Adaptation Challenge
+
+1. **Source context**: what was it designed for, and what assumptions did it make? (Phone-only? Portrait-only? One platform's idioms? A website?)
+2. **Target context**: which device class (phone, tablet, foldable), orientation, platform, and usage posture (one-handed on the go vs two-handed at rest)?
+3. **What breaks**: navigation that doesn't fit the target, layouts that stretch instead of restructure, gestures or controls that don't exist there?
+
+## Adaptation Strategies
+
+### Phone → Tablet (iPad / large screens)
+
+- **Restructure, don't stretch.** A scaled-up phone UI on a tablet is the failure mode. Use size classes (iOS) / window size classes (Android) to switch structure.
+- **Navigation changes shape**: tab bar stays or becomes a sidebar on iPad; Android navigation bar becomes a rail or drawer on expanded width.
+- **Use the width**: split view / master-detail (list + detail side by side), multi-column grids, popovers where phones used sheets.
+- **Multitasking is a size, not an edge case**: iPad Split View and Android multi-window can hand you a phone-width window on a tablet; size-class-driven layout handles both for free.
+
+### Orientation & foldables
+
+- Landscape restructures (side-by-side panes, repositioned controls); never clip or letterbox. Lock orientation only when the task truly demands it.
+- Foldables (Android): react to posture and hinge via window size classes; test folded, unfolded, and tabletop.
+
+### Platform → platform (iOS ↔ Android)
+
+Translate idioms; never transplant them:
+
+| iOS | Android |
+|---|---|
+| Tab bar | Navigation bar / rail / drawer |
+| Edge-swipe back, back chevron | Predictive Back gesture / button |
+| Switch, segmented control, system pickers | Material switch, chips, Material pickers |
+| Action sheet | Bottom sheet / Material dialog |
+| SF Symbols, SF Pro, Dynamic Type | Material Symbols, Roboto, sp scaling |
+| Semantic system colors, materials | Material color roles, tonal elevation |
+| System push/sheet transitions | Container transform, shared-axis, fade-through |
+
+Rebuild navigation and controls in the target's vocabulary; carry over the brand's expressive layer (palette intent, type accent, motion personality) through the target's theming system.
+
+### Web → native (porting a website or web app)
+
+Reconform, don't reflow. Replace web navigation with the platform's model, HTML-shaped controls with platform controls, hover affordances with touch-first ones, and px-based type with Dynamic Type / sp. Then treat the result to the full platform reference; the slop test there is the acceptance bar.
+
+## Implement & Verify
+
+- Drive structure from **size classes / window size classes**, never from device-model checks.
+- Respect safe areas and window insets in every new configuration (notch, hinge, status bar, keyboard).
+- Test on simulators for breadth, then real hardware for truth: at least one phone and one tablet per shipped platform, both orientations, split-screen where supported.
+
+When the adaptation feels native to each context, hand off to `$impeccable polish` for the final pass.
+
+**NEVER**:
+- Ship a stretched phone layout on a tablet
+- Port one platform's controls or navigation onto the other
+- Hide core functionality on smaller devices (if it matters, make it work)
+- Lock orientation to dodge a layout bug
+- Trust simulators alone (posture, gestures, and performance need hardware)

.agents/skills/impeccable/reference/android.md

@@ -0,0 +1,40 @@
+# Android platform
+
+For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.
+
+On native, register narrows. Material Design 3 governs structure, navigation, and interaction whatever the register; brand expresses through Material's theming (color roles, type scale, shape, motion). A Material-everywhere cross-platform app that also ships to iPhone still owes iOS its OS guarantees on that hardware: safe-area insets, Reduce Motion, edge-swipe back.
+
+## The Android slop test
+
+Would a fluent Android user trust this app, or trip on off-spec components? The most common tell is an iOS app wearing Android's skin: a bottom-only navigation copied from iPhone, a back arrow that ignores the system Back gesture, Cupertino-shaped switches and dialogs. Material 3 is the rulebook; follow its components and theme the brand through it.
+
+## Layout & structure
+
+- **Material navigation, matched to size.** Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet.
+- **System Back always works.** Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture.
+- **Edge-to-edge with window insets.** Apply the status bar, navigation bar, display cutout, and IME insets so content never hides behind system bars or the keyboard.
+- **Top app bar for screen context**; pair with a FAB when the screen has a single primary action.
+
+## Touch targets
+
+- **48×48 dp minimum** for every touch target, with at least 8 dp between them.
+
+## Typography
+
+- **Material type scale.** Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen.
+- **Roboto is the system face**; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent.
+- **sp units, never fixed px**, so type follows the system font-size setting.
+
+## Color & theming
+
+- **Material color roles** (primary, on-primary, surface, surface-variant, secondary-container, outline, error). Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.
+- **Dynamic Color (Material You)** where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback.
+- **Dark theme is a first-class scheme.** Design and test it; never a quick invert.
+- **Tonal elevation.** Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows.
+
+## Components & motion
+
+- **Material components.** Buttons (filled / tonal / outlined / text), FAB, switches, chips, snackbars, bottom sheets, Material dialogs, navigation bar/rail/drawer. Never port iOS controls or invent equivalents.
+- **One FAB, one primary action.** Never stack FABs or spend one on a secondary task.
+- **Snackbars for transient feedback** (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt.
+- **Material motion patterns.** Container transform, shared-axis, fade-through, with standard easing and durations; honor the system Remove animations setting with a crossfade or instant cut.

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

@@ -10,6 +10,8 @@ Brand: motion is part of the voice; one well-rehearsed entrance beats scattered
 
 Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
+Native (`ios` / `android` / `adaptive`): implementation follows the Motion section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): system transitions and OS Reduce Motion, never the web tooling below.
+
 ---
 
 ## Assess Animation Opportunities

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

@@ -2,6 +2,8 @@ Run systematic **technical** quality checks and generate a comprehensive report.
 
 This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
 
+**Web only.** Native platforms (`ios` / `android` / `adaptive`) route to [audit.native.md](audit.native.md) instead; if the project is native, switch to it now.
+
 ## Diagnostic Scan
 
 Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.

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

@@ -0,0 +1,139 @@
+Run systematic **technical** quality checks on a native app (`ios` / `android` / `adaptive`) and generate a comprehensive report. Don't fix issues; document them for other commands to address.
+
+This is a code-level audit, not a design critique. Audit from source (SwiftUI / UIKit / Compose / React Native / Flutter); no browser tooling or `detect.mjs` applies. Score against the platform reference(s): [ios.md](ios.md) / [android.md](android.md), both for `adaptive`. Read them before scoring if Setup hasn't already. The report skeleton mirrors [audit.md](audit.md); keep the two in sync when changing it.
+
+## Diagnostic Scan
+
+Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
+
+### 1. Accessibility (VoiceOver / TalkBack)
+
+**Check for**:
+- **Missing labels**: interactive elements without accessibility labels, traits/roles, or state announcements
+- **Reading and focus order**: illogical traversal, unreachable controls, focus lost on navigation
+- **Text scaling**: fixed point sizes defeating Dynamic Type (iOS) or px instead of sp (Android); layouts that clip or overlap at large sizes
+- **Touch targets**: below 44 pt (iOS) / 48 dp (Android), or crammed without spacing
+- **Reduce Motion ignored**: parallax and large slides with no crossfade alternative
+- **Contrast**: text failing contrast in either appearance, light or dark
+
+**Score 0-4**: 0=Screen reader unusable, 1=Major gaps (unlabeled controls, no scaling), 2=Partial (labels exist, order or scaling breaks), 3=Good (minor gaps), 4=Excellent (labeled, ordered, scales cleanly, Reduce Motion honored)
+
+### 2. Performance
+
+**Check for**:
+- **Slow startup**: heavy work on launch before first frame
+- **Unvirtualized lists**: long content without FlatList / LazyColumn / List recycling
+- **Main-thread jank**: synchronous work in scroll or gesture paths, dropped frames on 60/120 Hz
+- **Wasted rendering**: unnecessary re-renders (React Native) or recompositions (Compose); missing memoization/keys
+- **Image handling**: full-size images decoded for thumbnails, no caching
+- **App weight**: bloated JS bundle or binary, unused dependencies
+
+**Score 0-4**: 0=Janky everywhere, 1=Major problems (unvirtualized lists, slow launch), 2=Partial, 3=Good (minor improvements possible), 4=Excellent (fast launch, smooth scroll, lean)
+
+### 3. Appearance & Theming
+
+**Check for**:
+- **Hard-coded colors**: raw hex instead of semantic system colors (iOS) / Material color roles (Android) / design tokens
+- **Broken dark appearance**: missing dark variants, poor contrast in dark, quick inverts
+- **Dynamic Color** (Android 12+): no static fallback scheme, or ignored where it fits
+- **Off-platform materials**: hand-rolled blur/glassmorphism instead of system materials or tonal elevation
+
+**Score 0-4**: 0=Hard-coded everything, 1=Minimal tokens, 2=Partial (tokens exist, inconsistently used), 3=Good (minor hard-coded values), 4=Excellent (semantic throughout, both appearances first-class)
+
+### 4. Platform Conformance (CRITICAL)
+
+Score against the loaded platform reference(s), including their slop tests. **Check for**:
+- **Broken system gestures**: edge-swipe back disabled (iOS), predictive Back hijacked (Android)
+- **Inset violations**: content under the notch, Dynamic Island, home indicator, status bar, or keyboard
+- **Off-platform navigation**: custom global nav, overloaded tab bars, iOS patterns on Android or vice versa
+- **Web-shaped controls**: HTML-style buttons, custom toggles, hover-dependent affordances
+- **Icon drift**: mixed icon sets instead of SF Symbols / Material Symbols
+- **AI tells**: the shared absolute bans still apply (AI palette, gradient text, hero metrics)
+
+**Score 0-4**: 0=Web port (nothing native), 1=Heavy violations (3-4 kinds), 2=Some (1-2 noticeable), 3=Mostly conformant (subtle issues), 4=Fully native (a fluent user trusts every screen)
+
+### 5. Adaptivity
+
+**Check for**:
+- **Stretched phone layouts**: tablet/iPad rendering a scaled-up phone UI instead of using size classes / window size classes
+- **Orientation breakage**: landscape clipping, ignored, or locked without reason
+- **Keyboard/IME handling**: inputs hidden behind the keyboard, no inset adjustment
+- **Multitasking**: iPad Split View / Android multi-window breaking layout
+- **Foldables**: hinge-unaware layouts on posture change (Android)
+
+**Score 0-4**: 0=One screen size only, 1=Major breakage (landscape or tablet broken), 2=Partial, 3=Good (minor edge cases), 4=Excellent (adapts across sizes, orientations, and windowing)
+
+## Generate Report
+
+### Audit Health Score
+
+| # | Dimension | Score | Key Finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | ? | [most critical issue or "--"] |
+| 2 | Performance | ? | |
+| 3 | Appearance & Theming | ? | |
+| 4 | Platform Conformance | ? | |
+| 5 | Adaptivity | ? | |
+| **Total** | | **??/20** | **[Rating band]** |
+
+**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
+
+### Platform Conformance Verdict
+**Start here.** Pass/fail: does this read as a native app or a ported website? List specific violations. Be brutally honest.
+
+### Executive Summary
+- Audit Health Score: **??/20** ([rating band])
+- Total issues found (count by severity: P0/P1/P2/P3)
+- Top 3-5 critical issues
+- Recommended next steps
+
+### Detailed Findings by Severity
+
+Tag every issue with **P0-P3 severity**:
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or platform-guideline violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
+
+For each issue, document:
+- **[P?] Issue name**
+- **Location**: Screen, file, line
+- **Category**: Accessibility / Performance / Theming / Conformance / Adaptivity
+- **Impact**: How it affects users
+- **Guideline**: The HIG / Material rule it violates (if applicable)
+- **Recommendation**: How to fix it
+- **Suggested command**: Which command to use (prefer: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
+
+### Patterns & Systemic Issues
+
+Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
+- "Hard-coded colors appear in 15+ screens, should use semantic colors"
+- "Touch targets consistently below 44 pt throughout the tab bar and list rows"
+
+### Positive Findings
+
+Note what's working well: good practices to maintain and replicate.
+
+## Recommended Actions
+
+List recommended commands in priority order (P0 first, then P1, then P2):
+
+1. **[P?] `$command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `$command-name`**: Brief description (specific context)
+
+**Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended.
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `$impeccable audit` after fixes to see your score improve.
+
+**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
+
+**NEVER**:
+- Report issues without explaining impact (why does this matter?)
+- Provide generic recommendations (be specific and actionable)
+- Skip positive findings (celebrate what works)
+- Forget to prioritize (everything can't be P0)
+- Report false positives without verification

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

@@ -1,12 +1,12 @@
-When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type.
+When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact by making the existing design language more decisive, specific, and committed.
 
 ---
 
 ## Register
 
-Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV.
+Brand: "bolder" means distinctive. Express a stronger point of view through hierarchy, pacing, proportion, copy, evidence, and one committed visual idea.
 
-Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
+Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, sharper information density, and more decisive prioritization. The amplification is in clarity, not drama.
 
 ---
 
@@ -15,98 +15,105 @@ Product: "bolder" rarely means theatrics; those undermine trust. It means strong
 Analyze what makes the design feel too safe or boring:
 
 1. **Identify weakness sources**:
-   - **Generic choices**: System fonts, basic colors, standard layouts
-   - **Timid scale**: Everything is medium-sized with no drama
-   - **Low contrast**: Everything has similar visual weight
-   - **Static**: No motion, no energy, no life
-   - **Predictable**: Standard patterns with no surprises
-   - **Flat hierarchy**: Nothing stands out or commands attention
+   - **Generic choices**: The page could belong to any product in the category.
+   - **Timid scale**: Everything is medium-sized with no clear lead.
+   - **Low contrast**: Important and supporting elements have similar visual weight.
+   - **Static**: The surface has no meaningful moment of emphasis.
+   - **Predictable**: The composition follows a default pattern without a point of view.
+   - **Flat hierarchy**: Nothing stands out or commands attention.
 
 2. **Understand the context**:
-   - What's the brand personality? (How far can we push?)
-   - What's the purpose? (Marketing can be bolder than financial dashboards)
-   - Who's the audience? (What will resonate?)
-   - What are the constraints? (Brand guidelines, accessibility, performance)
+   - What is the brand personality?
+   - What is the purpose of this surface?
+   - Who is the audience?
+   - What design system, tokens, components, and visual conventions already exist?
 
 If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
 
-**CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
+**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random noise.
 
 **WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
 
+## Design-System Lock
+
+If the project has `DESIGN.md`, tokens, theme variables, or established component styles, treat that system as the boundary. Make the existing language stronger before adding new language.
+
+Do not invent new colors, gradients, radii, shadows, fonts, decorative backgrounds, or effects just because the request says "bolder." A bolder pass should usually change emphasis, proportion, rhythm, density, contrast, copy, artifact specificity, and layout relationships while staying inside the documented system.
+
+If the existing system is genuinely too limited to express the bolder direction, stop and ask the user before expanding it. Name the exact additions, the role each would play, and why the current system cannot do the job. If the user approves expansion, update the design system or tokens alongside the implementation.
+
 ## Plan Amplification
 
 Create a strategy to increase impact while maintaining coherence:
 
-- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing)
-- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
-- **Risk budget**: How experimental can we be? Push boundaries within constraints.
-- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast)
+- **Focal point**: Pick one thing the viewer should remember, then make the rest support it.
+- **System levers**: Identify which existing tokens, components, layout patterns, and copy structures can carry more weight.
+- **Risk budget**: Decide how far the surface can push while still feeling like the same product or brand.
+- **Hierarchy amplification**: Increase contrast between primary, secondary, and tertiary content instead of making every element louder.
 
 **IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
 
 ## Amplify the Design
 
-Systematically increase impact across these dimensions:
+Systematically increase impact through intention, not a menu of effects:
 
 ### Typography Amplification
-- **Replace generic fonts**: Swap system fonts for distinctive choices (see the parent skill's typography guidelines and the [Reference Material section of typeset.md](typeset.md#reference-material) for inspiration)
-- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x)
-- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400
-- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default)
+- Strengthen the existing type hierarchy before changing typefaces.
+- Make important text meaningfully more dominant, and make supporting text quieter.
+- Use weight, measure, spacing, and line breaks to sharpen the point of view.
+- Add or replace fonts only after user-approved design-system expansion.
 
-### Color Intensification
-- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
-- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop
-- **Dominant color strategy**: Let one bold color own 60% of the design
-- **Sharp accents**: High-contrast accent colors that pop
-- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
-- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue)
+### Color Amplification
+- Use the existing palette more decisively before adding colors.
+- Shift the proportion, placement, and contrast of documented colors to clarify meaning.
+- Treat any new color, gradient, or tint ramp as a design-system expansion that requires user approval.
+- Keep color tied to hierarchy, state, or brand meaning; do not use it as surface decoration.
 
-### Spatial Drama
-- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings
-- **Break the grid**: Let hero elements escape containers and cross boundaries
-- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry
-- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px)
-- **Overlap**: Layer elements intentionally for depth
+### Spatial Amplification
+- Change proportion, density, alignment, and sequencing so the composition has a stronger point of view.
+- Create clearer contrast between dense evidence and open breathing room.
+- Let layout express priority and narrative order before adding ornament.
+- Preserve responsive behavior and avoid text overflow at every breakpoint.
 
-### Visual Effects
-- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
-- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
-- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop)
-- **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
-- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
+### Surface Amplification
+- Use existing surface, border, radius, and shadow rules more deliberately.
+- Remove timid half-measures: either give an element a clear role or simplify it.
+- Add texture, depth, illustration, or decorative treatments only when already established by the system or explicitly approved.
+- Make real product artifacts, imagery, data, or copy carry attention before reaching for effects.
 
 ### Motion & Animation
-- **Hero moment**: One signature entrance, once. Not on every visit and not on every section.
-- **Micro-interactions**: Satisfying hover effects, click feedback, state changes.
-- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect).
-- **Bolder ≠ scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
+- Design one meaningful moment of emphasis when motion genuinely supports the point.
+- Make interaction feedback feel more decisive without becoming distracting.
+- Keep transitions smooth and intentional.
+- **Bolder != scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
 
 ### Composition Boldness
-- **Hero moments**: Create clear focal points with dramatic treatment
-- **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements
-- **Full-bleed elements**: Use full viewport width/height for impact
-- **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits
+- Make the dominant idea unmistakable.
+- Use layout tension, sequencing, contrast, and restraint to create a stronger read.
+- Let the page's structure communicate priority before adding decorative layers.
+- If every element is louder, the composition is not bolder; it is flatter.
 
 **NEVER**:
-- Add effects randomly without purpose (chaos ≠ bold)
-- Sacrifice readability for aesthetics (body text must be readable)
-- Make everything bold (then nothing is bold; you need contrast)
-- Ignore accessibility (bold design must still meet WCAG standards)
-- Overwhelm with motion (animation fatigue is real)
-- Copy trendy aesthetics blindly (bold means distinctive, not derivative)
+- Add undocumented design-system primitives without user approval
+- Add effects randomly without purpose
+- Hide weak hierarchy behind decoration
+- Sacrifice readability for aesthetics
+- Make everything bold; contrast is the point
+- Ignore accessibility
+- Overwhelm with motion
+- Copy trendy aesthetics blindly
 
 ## Verify Quality
 
 Ensure amplification maintains usability and coherence:
 
+- **System-faithful**: Did the pass make the existing design language stronger before adding anything new?
+- **No undocumented drift**: Are new colors, gradients, shadows, radii, fonts, and effects either absent or explicitly approved and documented?
 - **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
 - **Still functional**: Can users accomplish tasks without distraction?
 - **Coherent**: Does everything feel intentional and unified?
-- **Memorable**: Will users remember this experience?
-- **Performant**: Do all these effects run smoothly?
-- **Accessible**: Does it still meet accessibility standards?
+- **Memorable**: Will users remember this experience for the intended reason?
+- **Performant and accessible**: Does the result stay fast, readable, responsive, and WCAG-conscious?
 
 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
 

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

@@ -60,7 +60,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg
 - Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
 - Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
 - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit.
-- Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not.
+- Don't converge across projects. Each brand surface differentiates from the last.
 - When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette.
 
 ## Layout
@@ -74,7 +74,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg
 
 Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
 
-**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
+**When the brief implies imagery, you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
 
 - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `<div>` placeholders.
 - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".

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

@@ -5,8 +5,9 @@ Resolve one stable target, run two independent assessments, synthesize a design
 ### Hard Invariants
 
 - Assessment A (design review) and Assessment B (detector/browser evidence) are both required.
+- Assessment A and B MUST run as two isolated sub-agents whenever a sub-agent/Task tool is exposed. Running them inline in this context is "possible" but is NOT permitted; it is a degraded run. Inline is allowed ONLY when no sub-agent tool exists (or the user declined, on harnesses that ask).
+- If you degrade for any reason, the report's first line MUST be a banner: `⚠️ DEGRADED: single-context (<reason>)`. A silent degraded critique is a failed critique.
 - Assessment A must finish before detector findings enter the parent synthesis context. Detector output is deterministic, but it still anchors judgment.
-- If sub-agents are unavailable, fall back sequentially: finish and record Assessment A first, then run Assessment B, then synthesize.
 - A skipped detector is a failed critique run unless `detect.mjs` is missing or crashes after a real attempt.
 - Viewable targets require browser inspection when available.
 - Any local server started only for critique visualization must run in the background, have a recorded stop method, and be stopped before final reporting unless the user asks to keep it.
@@ -27,14 +28,21 @@ Resolve one stable target, run two independent assessments, synthesize a design
 
 ### Assessment Orchestration
 
-Delegate Assessment A and Assessment B to separate sub-agents when possible. They must not see each other's output. Do not show findings to the user until synthesis.
+Delegate Assessment A and Assessment B to separate sub-agents. They must not see each other's output. Do not show findings to the user until synthesis.
 
-Codex sub-agent gate:
+Sub-agent gate (all harnesses):
+- Unless a harness-specific gate below overrides this, spawn A and B as two isolated, parallel sub-agents whenever a sub-agent/Task tool is exposed. This is the default and is mandatory; do not run them inline because it is faster.
+- "Unavailable" means exactly one thing: no sub-agent/Task tool is exposed in this session (or, on harnesses that ask, the user declined). It does not mean inconvenient.
+- If and only if sub-agents are unavailable, fall back sequentially: finish and record Assessment A, then run Assessment B, then synthesize, and emit the degraded banner.
+- Whichever path you take, declare it in the report header (see Report header provenance). Skipping sub-agents without the banner is the most common failure of this command.
+
+Codex sub-agent gate (overrides the default above; Codex's permission model requires asking before spawning):
+- Asking is the normal path, not a degradation. Approving and spawning is the dual-agent path; do not emit the degraded banner just for asking.
 - If `spawn_agent` is exposed and the user explicitly allowed sub-agents, delegation, or parallel agent work, spawn A and B immediately.
 - If `spawn_agent` is exposed but the user did not explicitly allow sub-agents, ask exactly once: "Impeccable critique is designed to run two independent sub-agents for an unanchored assessment. May I use sub-agents for this critique?" Then stop until the user answers.
-- If allowed, spawn A and B. If declined, run sequentially and report `Assessment independence: degraded (sub-agents declined by user)`.
-- If `spawn_agent` is not exposed, do not ask; run sequentially and report `Assessment independence: degraded (spawn_agent unavailable in this session)`.
-- If spawning fails after permission, run sequentially and report `Assessment independence: degraded (sub-agent spawn failed: <exact error>)`.
+- If allowed, spawn A and B. If declined, run sequentially and lead the report with `⚠️ DEGRADED: single-context (sub-agents declined by user)`.
+- If `spawn_agent` is not exposed, do not ask; run sequentially and lead with `⚠️ DEGRADED: single-context (spawn_agent unavailable in this session)`.
+- If spawning fails after permission, run sequentially and lead with `⚠️ DEGRADED: single-context (sub-agent spawn failed: <exact error>)`.
 Prefer `fork_context: false` with self-contained prompts containing cwd, target, live URL, references, product context, and output contract. If using `fork_context: true`, omit `agent_type`, `model`, and `reasoning_effort`.
 
 If browser automation is available, each assessment creates its own new tab. Never reuse an existing tab, even if it is already at the right URL.
@@ -69,7 +77,7 @@ node .agents/skills/impeccable/scripts/detect.mjs --json [target]
 
 Browser visualization is required for a viewable target when browser automation is available. Use a localhost dev/static URL for local files; avoid `file://` unless the available browser explicitly supports this workflow. Overlay flow:
 
-1. Create a fresh tab and navigate.
+1. Create a fresh tab and navigate. Prefer the harness's native/browser-canvas screenshot path before hand-rolling a Playwright/Puppeteer script; only fall back to a custom script when no native browser tool is exposed.
 2. Preflight mutable injection by setting `document.title` and appending a `<script>` tag. Read-only evaluate APIs do not count.
 3. If mutation is unavailable, skip live server, browser presentation, and injection; report fallback signal.
 4. If mutation is available, start `node .agents/skills/impeccable/scripts/live-server.mjs --background`, present the browser if supported, label `[Human]`, scroll top, inject `http://localhost:PORT/detect.js`, wait 2-3 seconds, read `impeccable` console messages, then stop the live server.
@@ -93,6 +101,12 @@ Codex final-answer note: `$impeccable critique` produces a report artifact, so t
 
 Structure your feedback as a design director would:
 
+#### Report header provenance
+
+The report's first line MUST declare how the assessments were run, so a degraded run is never silent:
+- Dual-agent: `Method: dual-agent (A: <agent-id> · B: <agent-id>)`
+- Degraded: `⚠️ DEGRADED: single-context (<reason, e.g. no sub-agent tool exposed>)`
+
 #### Design Health Score
 > *Consult the [Heuristics Scoring Guide](#heuristics-scoring-guide) section below.*
 

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

@@ -1,6 +1,6 @@
 Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
 
-DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): YAML frontmatter carrying machine-readable design tokens, followed by a markdown body with exactly six sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
+DESIGN.md follows the [official DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md): YAML frontmatter carrying machine-readable design tokens, followed by a markdown body with exactly six sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
 
 ## The frontmatter: token schema
 

.agents/skills/impeccable/reference/hooks.md

@@ -0,0 +1,92 @@
+# $impeccable hooks
+
+Manage the **design detector hook** for the current project.
+
+The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code, Codex, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
+
+This command toggles the hook **per project** by editing `.impeccable/config.json` (the unified Impeccable config; hook runtime settings live under its `hook` key, and shared detector ignores live under `detector`). Per-developer overrides, including the install consent decision (`hook.consent`) the CLI records, live in the gitignored `.impeccable/config.local.json`. Set `hook.enabled: false` to turn the hook off, `hook.quiet: true` to silence the clean/pending acks, or `hook.auditLog` to a file path for an NDJSON log. The legacy `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, and `IMPECCABLE_HOOK_LOG` env vars are still honored and override these config values when set.
+
+Declare server-side template extensions under **`detector.extensions`** when the project uses Blade, Twig, ERB, or Handlebars files; the hook skips them otherwise because they sit outside the built-in extension list. One entry per extension, `{ "ext": ".blade.php", "engine": "html" }`. `engine` picks the analyzer (`html` for markup templates, `text` for JS/TS/CSS-like files) and defaults to `html`. Match against the end of the filename, so double extensions like `.blade.php` and `.html.erb` work. Config only adds extensions; the built-in list always applies.
+
+Manual `npx impeccable detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `npx impeccable detect --no-config ...` for a raw detector run that ignores project config/context. Use `npx impeccable ignores ...` for direct CLI CRUD on the same detector ignores.
+
+Supported harnesses: Claude Code (`.claude/settings.local.json` in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared `settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project), Cursor (`.cursor/hooks.json` in the project), and GitHub Copilot (`.github/hooks/impeccable.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once `.github/hooks/impeccable.json` is committed to the repository's default branch.
+
+On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
+
+## Routing
+
+The first argument is the action. Defaults to `status`.
+
+| Action | What it does |
+|---|---|
+| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
+| `on` | Set `enabled: true` in `.impeccable/config.json`, record local hook consent as accepted, and install/repair provider hook manifests when the skill is installed. |
+| `off` | Set `enabled: false` in `.impeccable/config.json`. |
+| `ignore-rule <id>` | Append `<id>` to `detector.ignoreRules`; for `overused-font`, requires `--all-values`. |
+| `ignore-file <glob>` | Append `<glob>` to `detector.ignoreFiles`. |
+| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/config.json`. |
+| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/config.local.json`. |
+| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
+
+## Flow
+
+1. Resolve the action from the user's argument. If no action was given, default to `status`.
+2. Invoke the admin script and pass the user's output through verbatim:
+
+   ```bash
+   node .agents/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
+   ```
+
+3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `$impeccable hooks on`."
+4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
+5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/config.json`; add `--local` only when the user explicitly asks for a private exception.
+6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
+
+## Intentional findings
+
+The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
+
+Prefer the narrowest exception:
+
+- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/config.json` by default.
+- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` when the user confirms the specific value. Do not use `ignore-rule overused-font` for a specific font.
+- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
+- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
+- Prefer config ignores (the commands above) by default; they keep suppressions in one reviewable place. Reach for an inline comment only when the waiver must travel with a single file that leaves the repo (a generated/exported standalone document, an emailed HTML file). The supported marker is `impeccable-disable <rule>` (whole file) or `impeccable-disable-line` / `impeccable-disable-next-line` (one line), in any comment syntax, with an optional reason after `:` or `--`. The detector honors it by default; `--no-inline-ignores` or `--no-config` bypasses it.
+
+Example value-specific exception:
+
+```bash
+node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
+```
+
+Example intentional motion exception:
+
+```bash
+node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-value bounce-easing bounce-ball --shared --reason "User confirmed ball bounce animation is intentional"
+```
+
+Example whole-rule font exception:
+
+```bash
+node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
+```
+
+Example file-scoped exception:
+
+```bash
+node .agents/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
+```
+
+## Constraints
+
+- Never modify `.impeccable/config.json` or `.impeccable/config.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent. One exception: `detector.extensions` has no admin action, so when the user asks to cover a template stack, edit that one field in `.impeccable/config.json` directly and leave the rest of the file untouched.
+- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
+- Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
+- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, and `.github/hooks/impeccable.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/impeccable.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
+
+## Failure modes
+
+- If `.impeccable/config.json` or `.impeccable/config.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
+- If the user asks to "disable the hook" globally, lead with `$impeccable hooks off` (persistent for this project; writes `hook.enabled: false` to config). The legacy `IMPECCABLE_HOOK_DISABLED=1` env var also works as a one-shot override that follows the shell.

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

@@ -3,7 +3,7 @@
 The setup command for a project. One codebase crawl feeds everything it writes:
 
 - **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
-- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md). Answers "how it looks".
 - **`.impeccable/live/config.json`** (live mode): pre-configured so `$impeccable live` boots straight into variant mode with no first-time detour.
 
 It closes by pointing the user at the best command to run next. Every other impeccable command reads PRODUCT.md and DESIGN.md before doing any work.
@@ -16,6 +16,7 @@ Decision tree:
 - **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
 - **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `$impeccable document` for DESIGN.md.
 - **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
+- **PRODUCT.md exists but has no `## Platform` section (legacy)**: add it the same way, but only when the project is native (`ios` / `android` / `adaptive`) or the user wants it explicit; a missing field already means `web`.
 - **Both exist**: STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which file to refresh. Skip the one the user doesn't want changed.
 - **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
 
@@ -41,26 +42,34 @@ Also form a **register hypothesis** from what you find:
 
 Register is a hypothesis at this point, not a decision; Step 3 confirms it.
 
+Also form a **platform hypothesis**:
+
+- Native signals: React Native / Expo (`react-native`, `expo`), Flutter (`pubspec.yaml`, `flutter`), SwiftUI / UIKit (`.swift`, `.xcodeproj`, an `ios/` app target), Jetpack Compose / Android (`build.gradle`, an `android/` app module, `AndroidManifest.xml`). An `ios/` and/or `android/` directory that is a real app target, not just a Capacitor/Cordova wrapper around a website.
+- Web signals (the default): a web framework (Vite, Next, Nuxt, SvelteKit, Astro), an HTML entry, a CSS/Tailwind setup, no native app target.
+
+Values: `web` / `ios` / `android` / `adaptive` (one codebase, ships both, adapts per OS). Mobile web is still `web`. Like register, this is a hypothesis; Step 3 confirms it.
+
 Note what you've learned and what remains unclear. Also note any rough edges worth a follow-up command (thin hierarchy, flat or gray palette, missing error/empty states, dull copy); Step 7 turns these into concrete recommendations without re-analyzing.
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask only about what you couldn't infer from the codebase.
+STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask about anything the codebase doesn't answer with strong, explicit evidence.
 
 ### Interview mode, not confirmation mode
 
 If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
 
-- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
-- Ask **2-3 questions per round**, then wait for answers.
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop: one question at a time, with lettered options where the crawl suggests likely answers, waiting for each answer before the next.
+- Keep skill vocabulary (register, belief ladder, anti-references) out of question text; ask for the thing in words the user would use. For the brand register, ask like a magazine editor profiling the brand: curious and narrative, drawing out the story, the feel, and what a visitor should come to believe.
+- Ask in focused rounds and wait for answers between them. Keep **one topic per question**; add rounds rather than fold several topics into one either-or choice. Options obey the same rule: an option answers only the question asked; never write a compound option that bundles a feeling with a business outcome or names an additional audience.
 - Use inferred answers as hypotheses or options, not as finished facts.
 - Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
-- Round 1 should establish register, users/purpose, and desired outcome.
-- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+- Round 1 should establish register, platform, users, purpose, positioning, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs, plus conversion & proof for the brand register.
 
 ### Minimum viable interview
 
-Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
+Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, **platform confirmation** (`web` / `ios` / `android` / `adaptive`), users, purpose, positioning, brand personality, anti-references, and accessibility needs (plus conversion & proof for the brand register) unless each answer is directly discoverable from repo context. Never let the template's default `web` stand unconfirmed for a native or cross-platform repo. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
 
 ### Register (ask first; it shapes everything below)
 
@@ -68,20 +77,42 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
 
-If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default. Settle the default before drafting any register-dependent questions; never batch brand-only questions (Conversion & proof) into the same round as the question that decides the register.
+
+### Platform (ask right after register)
+
+Every project targets **web** (includes responsive mobile web), **ios**, **android**, or **adaptive** (one codebase, ships both, adapts per OS: Flutter, React Native, KMP). Platform picks the native rulebook: HIG for `ios`, Material 3 for `android`, both for `adaptive`, none for `web`.
+
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [web / ios / android / adaptive] project. Does that match?"* For cross-platform apps, decide by the **design language the app renders**, not the toolchain: one look on both platforms (Flutter's Material-everywhere default) takes that platform's value; genuine per-OS adaptation (Cupertino on iOS, Material on Android) is `adaptive`. When in doubt, `web`.
+
+A monorepo shipping both a website and a native app gets a PRODUCT.md per app, each with its own `## Platform`; the root PRODUCT.md carries the primary surface's platform.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
 - What job are they trying to get done?
-- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
+- What is this for? A purpose stated in README or docs is a hypothesis, not strong evidence; confirm it, don't transcribe it.
+- What does success look like?
+- If more than one kind of user is plausible, confirm a primary and secondary audience; don't manufacture a split that isn't there. An audience implied by another answer (a success metric, a CTA) is still unconfirmed; ask before writing it as secondary.
+- If the surface speaks to a different audience than the people who use the product, ask the user to name both.
+- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency) Ask this standalone; don't fold emotions into the success question.
 - For product: what workflow are they in? What's the primary task on any given screen?
 
+### Positioning
+- In one line, what does this do that nothing else does? The single strategic claim every screen reinforces.
+
 ### Brand & Personality
 - How would you describe the brand personality in 3 words?
 - Reference sites or apps that capture the right feel? What specifically about them?
   - Push for specific named references with the *specific* thing about them that fits this brand, not generic "modern" adjectives or category-bucket lanes.
 - What should this explicitly NOT look like? Any anti-references?
 
+### Conversion & proof (brand register only)
+- What's the primary CTA?
+- What's the secondary fallback, for visitors not ready for the primary?
+- The one line a visitor should remember after 10 seconds.
+- What must the visitor believe, in order, before taking the primary CTA? (The template's belief ladder.)
+- What proof is on hand? Ask the user to hand over any testimonials, case studies, press, or client/partner logos they already have. If you can receive files directly, collect them; otherwise create `.impeccable/assets/proof/` and ask the user to add files there. Reference supplied files by path; record text proof inline.
+
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
@@ -90,7 +121,7 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
-Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing. Confirmed means what the user actually said yes to; do not pad a confirmed answer with extras they never picked (additional anti-references, audiences, roadmap claims, a WCAG level), whether drawn from the crawl, another answer, or your own option text. If an extra belongs in the doc, ask about it first.
 
 Synthesize into a strategic document:
 
@@ -101,12 +132,26 @@ Synthesize into a strategic document:
 
 product
 
+## Platform
+
+web
+
 ## Users
-[Who they are, their context, the job to be done]
+[Who they are, their context, the job to be done. Primary audience; a secondary audience or a surface-vs-user split only when they apply.]
 
 ## Product Purpose
 [What this product does, why it exists, what success looks like]
 
+## Positioning
+[The single strategic claim every screen reinforces. Not a visual rule, not an anti-reference.]
+
+## Conversion & proof
+[Brand register only. Product register: omit this section entirely, heading included.]
+- Primary and secondary CTA: [...]
+- The line a visitor remembers after 10 seconds: [...]
+- Belief ladder: [...]
+- Proof on hand: [testimonials, case studies, press, or logos, referenced by path]
+
 ## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
@@ -120,7 +165,9 @@ product
 [WCAG level, known user needs, considerations]
 ```
 
-Register is either `brand` or `product` as a bare value. No prose, no commentary.
+Register is either `brand` or `product` as a bare value. No prose, no commentary. Platform is `web`, `ios`, `android`, or `adaptive`, also a bare value; omit the section only on legacy files you're leaving untouched, otherwise write `web` explicitly.
+
+Write fields as prose, and use bold sparingly: only where a word carries a decision, never as a label lead-in on every line.
 
 Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
 
@@ -137,6 +184,8 @@ If the user prefers to skip, mention they can run `$impeccable document` any tim
 
 ## Step 6: Configure live mode (when code exists)
 
+**Skip this step when the platform is native** (`ios` / `android` / `adaptive`): live mode drives a browser overlay. A hybrid wrapper or Expo web target serving HTML doesn't change that.
+
 If the project has code with HTML entries and a dev server (the same "code exists" condition that puts `$impeccable document` in scan mode), pre-configure live mode now. You already identified the framework and the served HTML entry in Step 2, so this is nearly free, and it spares the user the first-time setup detour when they later run `$impeccable live`.
 
 **Skip this step for empty / pre-implementation projects** (nothing to inject into yet). Tell the user live mode will configure itself the first time they run it once there's code.
@@ -154,16 +203,16 @@ Writing the config file is harmless and needs no consent; only the CSP **source-
 ## Step 7: Recommend starting points, then wrap up
 
 Summarize tersely:
-- Register captured (brand / product)
+- Register captured (brand / product) and platform captured (web / ios / android / adaptive)
 - What was written (PRODUCT.md, DESIGN.md, live config, or a subset)
 - The 3-5 strategic principles from PRODUCT.md that will guide future work
 - If DESIGN.md or live config is pending, one line on how to set it up later
 
-Then recommend the **best commands to run next**, drawn from what your Step 2 crawl already surfaced. Do not run a fresh analysis here; surface observations you already have. Tailor to register and to what you saw, offer the 2-4 most relevant (not a menu dump), and give the exact command to type. Group by intent:
+Then recommend the **best commands to run next**, drawn from what your Step 2 crawl already surfaced. Do not run a fresh analysis here; surface observations you already have. Tailor to register **and platform**, offer the 2-4 most relevant (not a menu dump), and give the exact command to type. Group by intent:
 
 - **Build something new**: `$impeccable craft <feature>` (shape, then build end-to-end) or `$impeccable shape <feature>` (plan first). Lead with this for empty or early-stage projects.
 - **Improve what's there**: name the specific surface. `$impeccable critique <page>` for a scored UX review; `$impeccable audit <area>` for a11y / perf / responsive checks; `$impeccable polish <component>` for a pre-ship pass. When the crawl flagged a specific weakness, point the matching command at it: thin hierarchy or spacing → `layout`, flat or gray palette → `colorize`, missing error / empty states → `harden` or `onboard`, dull or unclear copy → `clarify`.
-- **Iterate visually**: `$impeccable live` (configured in Step 6) to pick elements in the browser and generate variants in place.
+- **Iterate visually** (web only): `$impeccable live` (configured in Step 6) to pick elements in the browser and generate variants in place. **Skip this group for native platforms.**
 
 The full command menu is one bare `$impeccable` away; keep this list short and pointed.
 

.agents/skills/impeccable/reference/ios.md

@@ -0,0 +1,45 @@
+# iOS platform
+
+For native iOS / iPadOS apps: SwiftUI, UIKit, React Native, Expo, Flutter shipping to Apple hardware.
+
+On native, register narrows. HIG conformance governs structure, navigation, and interaction whatever the register; brand expresses through the expressive layer the platform provides (tint, type, motion, content). Calm, Duolingo, and Spotify carry strong identity entirely inside HIG conventions.
+
+## The iOS slop test
+
+Would a fluent iPhone user trust this app, or pause at off-spec controls? The tell is "ported from a website": reinvented navigation bars, custom back gestures, web-shaped buttons, hover-dependent affordances. Default to the platform's components; depart only for a reason the user would thank you for.
+
+## Layout & structure
+
+- **Safe area.** Lay out inside the safe-area insets. No controls under the notch, Dynamic Island, home indicator, or rounded corners.
+- **System navigation.** Tab bar for 2–5 top-level sections (sections, never actions), navigation stack for hierarchy, sheet for self-contained tasks. No custom global nav, no mixed metaphors.
+- **Edge-swipe back stays alive.** The left-edge back gesture is muscle memory; never disable or overlay it.
+- **Large titles** on top-level screens, collapsing to inline on scroll. Deep detail screens stay inline.
+
+## Touch targets
+
+- **44×44 pt minimum** for every tappable control, with breathing room between adjacent targets.
+
+## Typography
+
+- **Dynamic Type.** Use the system text styles (Large Title through Caption) so text follows the user's reading size. No hard-coded point sizes.
+- **San Francisco carries the UI.** Body, labels, and controls stay on SF Pro / SF Compact; a brand face may appear in display moments.
+- **11 pt floor**; Body is 17 pt.
+
+## Color & materials
+
+- **Semantic system colors** (label, secondaryLabel, systemBackground, separator, tint). They adapt to Dark Mode and increased contrast automatically; raw hex breaks there.
+- **Dark Mode is a first-class appearance.** Design and test both.
+- **One tint color** drives interactive elements; decoration is not its job.
+- **System materials** for blur and translucency behind bars and sheets; no hand-rolled glassmorphism.
+
+## Components & controls
+
+- **Platform controls.** Switch, segmented control, stepper, system pickers, action sheets, alerts, context menus, swipe actions. Reinventing these for flavor is the most common native slop.
+- **SF Symbols** for iconography: baseline-aligned, Dynamic Type-aware, weight and scale variants. Don't mix in a web icon set.
+- **Deliberate modality.** Sheet for a focused dismissible sub-task, full-screen cover for immersion. Clear Cancel/Done; honor swipe-to-dismiss unless data loss requires a guard.
+- **Grouped/inset lists** for settings-shaped content; no bespoke card stacks.
+
+## Motion
+
+- **System transitions.** Push slides, sheets rise, dismiss reverses the entrance. Custom transitions that fight the navigation model disorient.
+- **Honor Reduce Motion.** Crossfade instead of parallax and large slides.

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

@@ -8,11 +8,33 @@ Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-b
 
 Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
 
+Native (`ios` / `android` / `adaptive`): structure follows the Layout section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): platform navigation, insets, and touch targets, never the CSS tooling below.
+
+---
+
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the layout assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, documented spacing scale when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (layout assessment)**: give it the full [Assess Current Layout](#assess-current-layout) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to layout:
+
+```bash
+node .agents/skills/impeccable/scripts/detect.mjs --json --scope layout [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The detector abstains on arbitrary Tailwind spacing (`gap-[13px]`, `p-[7px]`) and ad-hoc `z-index` stacks, so when the project documents a spacing scale, also grep `gap-\[`, `p[trblxy]?-\[`, `m[trblxy]?-\[`, `z-\[` and judge those hits against it. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a monotone grid with uniform spacing passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
 ---
 
 ## Assess Current Layout
 
-Analyze what's weak about the current spatial design:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak about the current spatial design:
 
 1. **Spacing**:
    - Is spacing consistent or arbitrary? (Random padding/margin values)
@@ -138,6 +160,8 @@ Create a systematic plan:
 - **Consistency**: Is the spacing system applied uniformly?
 - **Responsiveness**: Does the layout adapt gracefully across screen sizes?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the rhythm and hierarchy land, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params

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

@@ -10,7 +10,7 @@ Codex: run live helper commands, the app dev server, and any dependency-installi
 
 Execute in order. No step skipped, no step reordered.
 
-1. `live.mjs`: boot.
+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`.
 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). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
 
@@ -113,7 +113,9 @@ node .agents/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 
 The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Load `brand.md` or `product.md` (freeform only, no action sub-command). Write all variants in one edit, then `--reply done`.
 
-On accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
+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.
 
 ### Replace mode (default)
 
@@ -151,6 +153,25 @@ If `--text` matches multiple candidates equally well, wrap exits with `{ error:
 
 Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
 
+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 the Svelte component path go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, so a `data-impeccable-params='[{…}]'` attribute on a component element fails to compile (`Expected token }`). Declare params for this path in `componentDir/params.json`, keyed by variant number, using the exact param 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"}
+  ]
+}
+```
+
+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.
+
 `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.
@@ -342,7 +363,7 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **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:
+**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the Svelte `svelte-component` path, do not use this attribute** (Svelte can't compile `{` inside an attribute value). Declare params in `componentDir/params.json` keyed by variant number instead (see the Svelte component paragraph in the wrap section). The param schema below is identical for both paths.
 
 ```html
 <div data-impeccable-variant="1" data-impeccable-params='[
@@ -456,7 +477,7 @@ Do these five steps in the current thread, synchronously, before the next poll.
 1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
 2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
 3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it; those are live-mode plumbing, not source.
+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, run `live-complete.mjs --id SESSION_ID`, verify it reports `phase: "completed"`, then poll again.

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

@@ -10,9 +10,29 @@ Product: system fonts and familiar sans stacks are legitimate here. One well-tun
 
 ---
 
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the typography assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, **DESIGN.md** content when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (typography assessment)**: give it the full [Assess Current Typography](#assess-current-typography) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to type:
+
+```bash
+node .agents/skills/impeccable/scripts/detect.mjs --json --scope type [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The scan checks literal font sizes against the **DESIGN.md** ramp but abstains on `em`, `%`, `clamp()`, and line-heights, so also grep `font-size\s*:`, `fontSize`, `text-\[`, `leading-\[` and judge those hits against the spec. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a generic font stack at a flat scale passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
+---
+
 ## Assess Current Typography
 
-Analyze what's weak or generic about the current type:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak or generic about the current type:
 
 1. **Font choices**:
    - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
@@ -109,6 +129,8 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the type carries the hierarchy on its own, hand off to `$impeccable polish` for the final pass.
 
 ## Live-mode signature params

.agents/skills/impeccable/scripts/cleanup-deprecated.mjs

@@ -1,284 +0,0 @@
-#!/usr/bin/env node
-/**
- * Cleans up deprecated Impeccable skill files, symlinks, and
- * skills-lock.json entries left over from previous versions.
- *
- * Safe to run repeatedly -- it is a no-op when nothing needs cleaning.
- *
- * Usage (from the project root):
- *   node {{scripts_path}}/cleanup-deprecated.mjs
- *
- * What it does:
- *   1. Finds every harness-specific skills directory (.claude/skills,
- *      .cursor/skills, .agents/skills, etc.).
- *   2. For each deprecated skill name (with and without i- prefix),
- *      checks if the directory exists and its SKILL.md mentions
- *      "impeccable" (to avoid deleting unrelated user skills).
- *   3. Deletes confirmed matches (files, directories, or symlinks).
- *   4. Removes the corresponding entries from skills-lock.json.
- */
-
-import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-// Skills that were renamed, merged, or folded in v2.0, v2.1, and v3.0.
-const DEPRECATED_NAMES = [
-  // v2.0 renames
-  'frontend-design',    // renamed to impeccable
-  'teach-impeccable',   // folded into /impeccable init
-  // v2.1 merges
-  'arrange',            // renamed to layout
-  'normalize',          // merged into polish
-  'onboard',            // merged into harden
-  'extract',            // merged into /impeccable extract
-  // v3.0 consolidation: all standalone skills -> /impeccable sub-commands
-  'adapt',
-  'animate',
-  'audit',
-  'bolder',
-  'clarify',
-  'colorize',
-  'critique',
-  'delight',
-  'distill',
-  'harden',
-  'layout',
-  'optimize',
-  'overdrive',
-  'polish',
-  'quieter',
-  'shape',
-  'typeset',
-];
-
-// All known harness directories that may contain a skills/ subfolder.
-const HARNESS_DIRS = [
-  '.claude', '.cursor', '.gemini', '.codex', '.agents',
-  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
-];
-
-// Per-skill fingerprints for SKILL.md bodies that never mentioned
-// "impeccable" in their v2.x source. Used as a last-resort match
-// when no skills-lock.json exists and the word heuristic fails.
-// The strings are lifted verbatim from the v2.x frontmatter
-// descriptions, so collisions with hand-written user skills are
-// vanishingly unlikely.
-const SKILL_FINGERPRINTS = {
-  harden: 'Make interfaces production-ready: error handling, empty states',
-  optimize: 'Diagnoses and fixes UI performance across loading speed',
-};
-
-/**
- * Walk up from startDir until we find a directory that looks like a
- * project root (has package.json, .git, or skills-lock.json).
- */
-export function findProjectRoot(startDir = process.cwd()) {
-  let dir = resolve(startDir);
-  const { root } = { root: '/' };
-  while (dir !== root) {
-    if (
-      existsSync(join(dir, 'package.json')) ||
-      existsSync(join(dir, '.git')) ||
-      existsSync(join(dir, 'skills-lock.json'))
-    ) {
-      return dir;
-    }
-    const parent = resolve(dir, '..');
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return resolve(startDir);
-}
-
-/**
- * Load skills-lock.json from the project root, or null if missing/unreadable.
- */
-export function loadLock(projectRoot) {
-  const lockPath = join(projectRoot, 'skills-lock.json');
-  if (!existsSync(lockPath)) return null;
-  try {
-    return JSON.parse(readFileSync(lockPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check whether a skill directory belongs to Impeccable. Three layered
- * signals, in order of reliability:
- *   1. Lock source equals "pbakaus/impeccable" (authoritative).
- *   2. SKILL.md body contains the word "impeccable".
- *   3. SKILL.md body contains a per-skill fingerprint (for harden and
- *      optimize, whose v2.x SKILL.md never mentioned the pack name).
- */
-export function isImpeccableSkill(skillDir, { skillName, lock } = {}) {
-  // 1. Authoritative: the lock file claims this skill is ours.
-  if (skillName && lock?.skills?.[skillName]?.source === 'pbakaus/impeccable') {
-    return true;
-  }
-  const skillMd = join(skillDir, 'SKILL.md');
-  if (!existsSync(skillMd)) return false;
-  let content;
-  try {
-    content = readFileSync(skillMd, 'utf-8');
-  } catch {
-    return false;
-  }
-  // 2. Word-level content heuristic.
-  if (/impeccable/i.test(content)) return true;
-  // 3. Per-skill fingerprint for old skills that never mentioned the pack.
-  //    Strip the i- prefix so both `harden` and `i-harden` resolve to the
-  //    same fingerprint entry.
-  const unprefixed = skillName?.startsWith('i-') ? skillName.slice(2) : skillName;
-  const fingerprint = unprefixed && SKILL_FINGERPRINTS[unprefixed];
-  if (fingerprint && content.includes(fingerprint)) return true;
-  return false;
-}
-
-/**
- * Build the full list of names to check: each deprecated name, plus
- * its i-prefixed variant.
- */
-export function buildTargetNames() {
-  const names = [];
-  for (const name of DEPRECATED_NAMES) {
-    names.push(name);
-    names.push(`i-${name}`);
-  }
-  return names;
-}
-
-/**
- * Find every skills directory across all harness dirs in the project.
- * Returns absolute paths that exist on disk.
- */
-export function findSkillsDirs(projectRoot) {
-  const dirs = [];
-  for (const harness of HARNESS_DIRS) {
-    const candidate = join(projectRoot, harness, 'skills');
-    if (existsSync(candidate)) {
-      dirs.push(candidate);
-    }
-  }
-  return dirs;
-}
-
-/**
- * Remove deprecated skill directories/symlinks from all harness dirs.
- * Reads skills-lock.json so the authoritative "source" field can
- * drive deletion even when SKILL.md never mentions impeccable.
- * Returns an array of paths that were deleted.
- */
-export function removeDeprecatedSkills(projectRoot, lock) {
-  if (lock === undefined) lock = loadLock(projectRoot);
-  const targets = buildTargetNames();
-  const skillsDirs = findSkillsDirs(projectRoot);
-  const deleted = [];
-
-  for (const skillsDir of skillsDirs) {
-    for (const name of targets) {
-      const skillPath = join(skillsDir, name);
-
-      // Use lstat to detect symlinks (existsSync follows symlinks and
-      // returns false for dangling ones).
-      let stat;
-      try {
-        stat = lstatSync(skillPath);
-      } catch {
-        continue; // does not exist at all
-      }
-
-      if (stat.isSymbolicLink()) {
-        // Symlink: check the target if it's alive, otherwise treat
-        // dangling symlinks to deprecated names as safe to remove.
-        const targetAlive = existsSync(skillPath);
-        const isMatch = targetAlive
-          ? isImpeccableSkill(skillPath, { skillName: name, lock })
-          : true;
-        if (isMatch) {
-          unlinkSync(skillPath);
-          deleted.push(skillPath);
-        }
-        continue;
-      }
-
-      // Regular directory -- verify it belongs to impeccable
-      if (isImpeccableSkill(skillPath, { skillName: name, lock })) {
-        rmSync(skillPath, { recursive: true, force: true });
-        deleted.push(skillPath);
-      }
-    }
-  }
-
-  return deleted;
-}
-
-/**
- * Remove deprecated entries from skills-lock.json.
- * Only removes entries whose source is "pbakaus/impeccable".
- * Returns the list of removed skill names.
- */
-export function cleanSkillsLock(projectRoot) {
-  const lockPath = join(projectRoot, 'skills-lock.json');
-  if (!existsSync(lockPath)) return [];
-
-  let lock;
-  try {
-    lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
-  } catch {
-    return [];
-  }
-
-  if (!lock.skills || typeof lock.skills !== 'object') return [];
-
-  const targets = buildTargetNames();
-  const removed = [];
-
-  for (const name of targets) {
-    const entry = lock.skills[name];
-    if (!entry) continue;
-    // Only remove if it belongs to impeccable
-    if (entry.source === 'pbakaus/impeccable') {
-      delete lock.skills[name];
-      removed.push(name);
-    }
-  }
-
-  if (removed.length > 0) {
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
-  }
-
-  return removed;
-}
-
-/**
- * Run the full cleanup. Returns a summary object.
- *
- * Order matters: read the lock and delete directories first, then
- * strip lock entries. Otherwise the authoritative signal is gone by
- * the time directory deletion runs.
- */
-export function cleanup(projectRoot) {
-  const root = projectRoot || findProjectRoot();
-  const lock = loadLock(root);
-  const deletedPaths = removeDeprecatedSkills(root, lock);
-  const removedLockEntries = cleanSkillsLock(root);
-  return { deletedPaths, removedLockEntries, projectRoot: root };
-}
-
-// CLI entry point
-if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
-  const result = cleanup();
-  if (result.deletedPaths.length === 0 && result.removedLockEntries.length === 0) {
-    console.log('No deprecated Impeccable skills found. Nothing to clean up.');
-  } else {
-    if (result.deletedPaths.length > 0) {
-      console.log(`Removed ${result.deletedPaths.length} deprecated skill(s):`);
-      for (const p of result.deletedPaths) console.log(`  - ${p}`);
-    }
-    if (result.removedLockEntries.length > 0) {
-      console.log(`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`);
-      for (const name of result.removedLockEntries) console.log(`  - ${name}`);
-    }
-  }
-}

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Context-signals gatherer for the bare `{{command_prefix}}impeccable`
+ * Context-signals gatherer for the bare Impeccable invocation
  * (no-argument) path. Collects cheap, deterministic signals about the current
  * project and emits them as JSON.
  *
@@ -21,8 +21,8 @@ import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { loadContext, extractRegister } from './context.mjs';
-import { getCritiqueDir } from './impeccable-paths.mjs';
+import { loadContext, extractRegister, extractPlatform } from './context.mjs';
+import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 /** Is there code here at all, or just context files / an empty repo? */
 function hasCode(cwd) {
@@ -197,6 +197,7 @@ export async function gatherSignals(cwd = process.cwd()) {
       designPath: ctx.designPath,
       hasCode: hasCode(cwd),
       register: extractRegister(ctx.product),
+      platform: extractPlatform(ctx.product),
     },
     critique: { latest: latestCritique(cwd) },
     git,

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

@@ -1,15 +1,18 @@
 /**
  * Context loader: prints PRODUCT.md (and DESIGN.md if present) as one
- * markdown block on stdout, or exits with empty stdout when no PRODUCT.md
- * is found anywhere. The skill keys off "empty stdout" to branch into the
- * init flow.
+ * markdown block on stdout, or prints a `NO_PRODUCT_MD:` message when no
+ * PRODUCT.md is found anywhere. The skill keys off that message to branch:
+ * from-scratch build commands (init / teach / craft / shape) and clear
+ * build/shape intent divert into the init flow, while scoped commands proceed
+ * using the existing code as context.
  *
  * Path resolution (first match wins):
- *   1. cwd, if PRODUCT.md or DESIGN.md is there
- *   2. .agents/context/ then docs/
- *   3. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
+ *   1. Active project root, if PRODUCT.md or DESIGN.md is there
+ *   2. Active project .agents/context/ then docs/
+ *   3. Monorepo root context, using the same order, as a per-file fallback
+ *   4. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
  *      escape hatch, only consulted when defaults are empty
- *   4. cwd as a "nothing found" default
+ *   5. Active project root as a "nothing found" default
  *
  * `resolveContextDir()` and `loadContext()` are also exported for the
  * server-side scripts (live.mjs, live-server.mjs) that need the structured
@@ -19,15 +22,31 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parseTargetOptions } from './lib/target-args.mjs';
+import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
 
 const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
 const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
 const FALLBACK_DIRS = ['.agents/context', 'docs'];
+const MONOREPO_MARKER_FILES = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json'];
+const MONOREPO_FALLBACK_PROJECT_DIRS = ['apps', 'packages'];
+const WORKSPACE_DISCOVERY_IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.turbo',
+  '.cache',
+  'coverage',
+]);
 
 // ─── Update check ──────────────────────────────────────────────────────────
 // Piggyback a lightweight skill-version check on the once-per-session boot.
 // When a newer skill ships, append an UPDATE_AVAILABLE directive so the agent
-// can offer `npx impeccable skills update`. Everything here is best-effort and
+// can offer `npx impeccable update`. Everything here is best-effort and
 // silent on failure: a network problem, sandbox, or missing cache must never
 // block context output or print an error.
 
@@ -38,41 +57,623 @@ const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // throttle the network poll to o
 const RENOTIFY_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // don't re-surface the same version for a week
 const FETCH_TIMEOUT_MS = 1200;
 
-export function resolveContextDir(cwd = process.cwd()) {
-  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-    return cwd;
-  }
-  for (const rel of FALLBACK_DIRS) {
-    const candidate = path.resolve(cwd, rel);
-    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-      return candidate;
-    }
-  }
-  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
-  if (envDir && envDir.trim()) {
-    const trimmed = envDir.trim();
-    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  }
-  return cwd;
+export function resolveContextDir(cwd = process.cwd(), options = {}) {
+  return resolveContext(cwd, options).contextDir;
 }
 
-export function loadContext(cwd = process.cwd()) {
-  const contextDir = resolveContextDir(cwd);
-  const productPath = firstExisting(contextDir, PRODUCT_NAMES);
-  const designPath = firstExisting(contextDir, DESIGN_NAMES);
+export function loadContext(cwd = process.cwd(), options = {}) {
+  const resolved = resolveContext(cwd, options);
+  const absCwd = path.resolve(cwd);
+  const productPath = resolved.productPath;
+  const designPath = resolved.designPath;
   const product = productPath ? safeRead(productPath) : null;
   const design = designPath ? safeRead(designPath) : null;
   return {
     hasProduct: !!product,
     product,
-    productPath: productPath ? path.relative(cwd, productPath) : null,
+    productPath: productPath ? path.relative(absCwd, productPath) : null,
     hasDesign: !!design,
     design,
-    designPath: designPath ? path.relative(cwd, designPath) : null,
-    contextDir,
+    designPath: designPath ? path.relative(absCwd, designPath) : null,
+    contextDir: resolved.contextDir,
+    productContextDir: productPath ? path.dirname(productPath) : null,
+    designContextDir: designPath ? path.dirname(designPath) : null,
+    projectRoot: resolved.projectRoot,
+    repoRoot: resolved.repoRoot,
+    isMonorepo: resolved.isMonorepo,
   };
 }
 
+function resolveContext(cwd = process.cwd(), options = {}) {
+  const absCwd = path.resolve(cwd);
+  const project = resolveProject(absCwd, options);
+  const projectContextDir = resolveLocalContextDir(project.projectRoot);
+  const rootContextDir = project.isMonorepo && project.repoRoot !== project.projectRoot
+    ? resolveLocalContextDir(project.repoRoot)
+    : null;
+
+  let productPath =
+    (projectContextDir ? firstExisting(projectContextDir, PRODUCT_NAMES) : null)
+    || (rootContextDir ? firstExisting(rootContextDir, PRODUCT_NAMES) : null);
+  let designPath =
+    (projectContextDir ? firstExisting(projectContextDir, DESIGN_NAMES) : null)
+    || (rootContextDir ? firstExisting(rootContextDir, DESIGN_NAMES) : null);
+
+  let envContextDir = null;
+  if (!productPath && !designPath) {
+    envContextDir = resolveEnvContextDir(absCwd);
+    if (envContextDir) {
+      productPath = firstExisting(envContextDir, PRODUCT_NAMES);
+      designPath = firstExisting(envContextDir, DESIGN_NAMES);
+    }
+  }
+
+  return {
+    contextDir: productPath
+      ? path.dirname(productPath)
+      : designPath
+        ? path.dirname(designPath)
+        : envContextDir || project.projectRoot,
+    productPath,
+    designPath,
+    projectRoot: project.projectRoot,
+    repoRoot: project.repoRoot,
+    isMonorepo: project.isMonorepo,
+    targetDir: project.targetDir,
+  };
+}
+
+export function resolveProjectRoot(cwd = process.cwd(), options = {}) {
+  return resolveProject(cwd, options).projectRoot;
+}
+
+export function resolveTargetSelection(cwd = process.cwd(), options = {}) {
+  if (hasTargetOption(options)) return null;
+  const project = resolveProject(cwd);
+  if (
+    !project.isMonorepo
+    || !project.projectRoot
+    || !project.repoRoot
+    || path.resolve(project.projectRoot) !== path.resolve(project.repoRoot)
+  ) {
+    return null;
+  }
+  const targetCandidates = discoverTargetCandidates(project.repoRoot);
+  // No discoverable child apps (e.g. `workspaces: ["."]`, a root-only workspace,
+  // or a marker file with no apps/packages children): there is nothing to choose,
+  // so treat the repo root as the active project rather than blocking on an empty
+  // selection prompt that the user cannot answer.
+  if (targetCandidates.length === 0) return null;
+  return {
+    targetPath: null,
+    projectRoot: project.projectRoot,
+    repoRoot: project.repoRoot,
+    targetCandidates,
+  };
+}
+
+function resolveProject(cwd = process.cwd(), options = {}) {
+  const absCwd = path.resolve(cwd);
+  const targetDir = resolveTargetDir(absCwd, options);
+  let repoRoot = findMonorepoRoot(targetDir);
+  if (!repoRoot && targetDir !== absCwd) {
+    const cwdRepoRoot = findMonorepoRoot(absCwd);
+    if (cwdRepoRoot && isPathInside(targetDir, cwdRepoRoot)) {
+      repoRoot = cwdRepoRoot;
+    }
+  }
+  if (!repoRoot) {
+    return {
+      targetDir,
+      projectRoot: absCwd,
+      repoRoot: absCwd,
+      isMonorepo: false,
+    };
+  }
+  return {
+    targetDir,
+    projectRoot: resolveWorkspaceProjectRoot(repoRoot, targetDir) || repoRoot,
+    repoRoot,
+    isMonorepo: true,
+  };
+}
+
+function isPathInside(candidate, root) {
+  const rel = path.relative(root, candidate);
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function resolveLocalContextDir(root) {
+  if (firstExisting(root, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+    return root;
+  }
+  for (const rel of FALLBACK_DIRS) {
+    const candidate = path.resolve(root, rel);
+    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function resolveEnvContextDir(cwd) {
+  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
+  if (!envDir || !envDir.trim()) return null;
+  const trimmed = envDir.trim();
+  return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+}
+
+function resolveTargetDir(cwd, options = {}) {
+  const targetPath = options && typeof options === 'object' ? options.targetPath : null;
+  if (!targetPath || !String(targetPath).trim()) return cwd;
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+  try {
+    const stat = fs.statSync(abs);
+    return stat.isDirectory() ? abs : path.dirname(abs);
+  } catch {
+    return path.extname(abs) ? path.dirname(abs) : abs;
+  }
+}
+
+function findMonorepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const homeDir = path.resolve(os.homedir());
+  while (true) {
+    if (dir === homeDir) return null;
+    // isMonorepoRoot is checked before hasGitBoundary on purpose: a workspace
+    // root that also carries its own .git is still recognized. The trade-off is
+    // deliberate — a directory with a monorepo *marker* but no workspace patterns
+    // and no apps/packages children is not a monorepo root, so its .git stops
+    // traversal and a further-up root is not searched. The nested .git is treated
+    // as an independent project boundary, which is the intended isolation.
+    if (isMonorepoRoot(dir)) return dir;
+    if (hasGitBoundary(dir)) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function isMonorepoRoot(dir) {
+  if (readWorkspacePatterns(dir).some((pattern) => !normalizeWorkspacePattern(pattern).startsWith('!'))) return true;
+  if (!MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(dir, file)))) return false;
+  return hasFallbackWorkspaceChildren(dir);
+}
+
+function hasGitBoundary(dir) {
+  return fs.existsSync(path.join(dir, '.git'));
+}
+
+function hasFallbackWorkspaceChildren(dir) {
+  for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
+    const base = path.join(dir, name);
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    if (entries.some((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))) return true;
+  }
+  return false;
+}
+
+function discoverTargetCandidates(repoRoot) {
+  const roots = new Map();
+  const patterns = readWorkspacePatterns(repoRoot);
+  for (const pattern of patterns) {
+    for (const root of discoverRootsForPattern(repoRoot, pattern)) {
+      roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
+    }
+  }
+  if (MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(repoRoot, file)))) {
+    for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
+      const base = path.join(repoRoot, name);
+      let entries;
+      try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+        const root = path.join(base, entry.name);
+        roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
+      }
+    }
+  }
+  return [...roots.entries()]
+    .filter(([rel]) => rel && !rel.startsWith('..'))
+    // Honor negated workspace patterns (e.g. "!packages/internal"). resolveWorkspaceProjectRoot
+    // sends an excluded package back to the repo root, so an excluded folder must not appear as a
+    // selectable target — choosing it would silently resolve to the root instead.
+    .filter(([rel]) => !isExcludedByWorkspacePattern(rel.split('/').filter(Boolean), patterns))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([rel, root]) => {
+      const targetExample = findTargetExample(repoRoot, root);
+      return {
+        name: path.basename(root),
+        path: rel,
+        targetExample,
+        ...resolveCandidateContextSummary(repoRoot, root, targetExample),
+      };
+    });
+}
+
+function resolveCandidateContextSummary(repoRoot, projectRoot, targetPath) {
+  const ctx = resolveContext(repoRoot, { targetPath });
+  return {
+    productStatus: contextSourceStatus(ctx.productPath, repoRoot, projectRoot),
+    productPath: contextSourcePath(ctx.productPath, repoRoot),
+    designStatus: contextSourceStatus(ctx.designPath, repoRoot, projectRoot),
+    designPath: contextSourcePath(ctx.designPath, repoRoot),
+  };
+}
+
+// Selection candidates surface one of four statuses: 'child' (a canonical
+// PRODUCT.md/DESIGN.md directly in the app root), 'inherited' (resolved from the
+// repo root in a monorepo), 'missing' (no file found), and 'fallback'. 'fallback'
+// intentionally covers two non-canonical locations: a file inside the project
+// root but in a subdirectory (FALLBACK_DIRS, e.g. `.agents/context/`), and a file
+// outside both the project and repo roots (IMPECCABLE_CONTEXT_DIR override).
+function contextSourceStatus(filePath, repoRoot, projectRoot) {
+  if (!filePath) return 'missing';
+  const absPath = path.resolve(filePath);
+  const absProjectRoot = path.resolve(projectRoot);
+  const absRepoRoot = path.resolve(repoRoot);
+  if (isPathInsideOrEqual(absPath, absProjectRoot)) {
+    return path.dirname(absPath) === absProjectRoot ? 'child' : 'fallback';
+  }
+  if (absProjectRoot !== absRepoRoot && isPathInsideOrEqual(absPath, absRepoRoot)) {
+    return 'inherited';
+  }
+  return 'fallback';
+}
+
+function contextSourcePath(filePath, repoRoot) {
+  if (!filePath) return null;
+  const rel = path.relative(repoRoot, filePath);
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+    return rel.split(path.sep).join('/');
+  }
+  return filePath;
+}
+
+function discoverRootsForPattern(repoRoot, rawPattern) {
+  const pattern = normalizeWorkspacePattern(rawPattern);
+  if (!pattern || pattern.startsWith('!')) return [];
+  const segments = pattern.split('/').filter(Boolean);
+  if (!segments.length) return [];
+  const firstGlobIndex = segments.findIndex((segment) => segment.includes('*'));
+  const literalPrefix = firstGlobIndex === -1 ? segments : segments.slice(0, firstGlobIndex);
+  const base = path.join(repoRoot, ...literalPrefix);
+  if (!fs.existsSync(base)) return [];
+  if (segments.includes('**')) {
+    const packageRoots = [];
+    walkDirs(base, (dir) => {
+      if (dir !== base && isCandidateProjectRoot(dir)) packageRoots.push(dir);
+    });
+    if (packageRoots.length) return packageRoots;
+    return directChildDirs(base);
+  }
+  return expandSimplePattern(repoRoot, segments);
+}
+
+function expandSimplePattern(repoRoot, patternSegments, index = 0, current = repoRoot) {
+  if (index >= patternSegments.length) return fs.existsSync(current) ? [current] : [];
+  const segment = patternSegments[index];
+  if (!segment.includes('*')) {
+    return expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, segment));
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const roots = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+    if (!segmentMatches(segment, entry.name)) continue;
+    roots.push(...expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, entry.name)));
+  }
+  return roots;
+}
+
+function directChildDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))
+      .map((entry) => path.join(dir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+function walkDirs(root, visit) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+    const dir = path.join(root, entry.name);
+    visit(dir);
+    walkDirs(dir, visit);
+  }
+}
+
+function isCandidateProjectRoot(dir) {
+  return !!(
+    fs.existsSync(path.join(dir, 'package.json'))
+    || firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
+    || fs.existsSync(path.join(dir, 'src'))
+    || fs.existsSync(path.join(dir, 'app'))
+    || fs.existsSync(path.join(dir, 'pages'))
+    || fs.existsSync(path.join(dir, 'public'))
+  );
+}
+
+function isIgnoredWorkspaceDiscoveryDir(name) {
+  return name.startsWith('.') || WORKSPACE_DISCOVERY_IGNORED_DIRS.has(name);
+}
+
+function findTargetExample(repoRoot, projectRoot) {
+  const examples = [
+    'src/App.jsx',
+    'src/App.tsx',
+    'src/main.jsx',
+    'src/main.tsx',
+    'src/index.jsx',
+    'src/index.ts',
+    'app/page.tsx',
+    'pages/index.tsx',
+    'public/index.html',
+  ];
+  for (const rel of examples) {
+    const abs = path.join(projectRoot, rel);
+    if (fs.existsSync(abs)) return path.relative(repoRoot, abs).split(path.sep).join('/');
+  }
+  return path.relative(repoRoot, projectRoot).split(path.sep).join('/');
+}
+
+function resolveWorkspaceProjectRoot(repoRoot, targetDir) {
+  const rel = path.relative(repoRoot, targetDir);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return repoRoot;
+  const relSegments = rel.split(path.sep).filter(Boolean);
+  const patterns = readWorkspacePatterns(repoRoot);
+  const excluded = isExcludedByWorkspacePattern(relSegments, patterns);
+  if (!excluded) {
+    for (const pattern of patterns) {
+      const projectRoot = projectRootFromWorkspacePattern(repoRoot, relSegments, pattern);
+      if (projectRoot) return projectRoot;
+    }
+  }
+  if (excluded) return repoRoot;
+  if (
+    relSegments.length >= 2
+    && MONOREPO_FALLBACK_PROJECT_DIRS.includes(relSegments[0])
+  ) {
+    return path.join(repoRoot, relSegments[0], relSegments[1]);
+  }
+  const nearest = nearestProjectLikeRoot(repoRoot, targetDir);
+  if (nearest) return nearest;
+  return repoRoot;
+}
+
+function isExcludedByWorkspacePattern(relSegments, patterns) {
+  return patterns.some((rawPattern) => {
+    const pattern = normalizeWorkspacePattern(rawPattern);
+    if (!pattern.startsWith('!')) return false;
+    return workspacePatternMatchesRel(pattern.slice(1), relSegments);
+  });
+}
+
+function nearestProjectLikeRoot(repoRoot, targetDir) {
+  let dir = path.resolve(targetDir);
+  const stop = path.resolve(repoRoot);
+  while (dir && dir !== stop) {
+    if (
+      firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
+      || fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function nearestPackageRootBetween(repoRoot, targetDir, stopDir) {
+  let dir = path.resolve(targetDir);
+  const stop = path.resolve(stopDir || repoRoot);
+  const root = path.resolve(repoRoot);
+  while (dir && dir !== stop && isPathInsideOrEqual(dir, root)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function isPathInsideOrEqual(candidate, root) {
+  return path.resolve(candidate) === path.resolve(root) || isPathInside(candidate, root);
+}
+
+function workspacePatternMatchesRel(pattern, relSegments) {
+  const patternSegments = normalizeWorkspacePattern(pattern).split('/').filter(Boolean);
+  if (!patternSegments.length) return false;
+  if (patternSegments.includes('**')) {
+    const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
+    const literalPrefix = firstGlobIndex === -1
+      ? patternSegments
+      : patternSegments.slice(0, firstGlobIndex);
+    if (relSegments.length < literalPrefix.length + 1) return false;
+    for (let i = 0; i < literalPrefix.length; i++) {
+      if (!segmentMatches(literalPrefix[i], relSegments[i])) return false;
+    }
+    return true;
+  }
+  if (relSegments.length < patternSegments.length) return false;
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!segmentMatches(patternSegments[i], relSegments[i])) return false;
+  }
+  return true;
+}
+
+function readWorkspacePatterns(repoRoot) {
+  return [
+    ...readPackageWorkspaces(repoRoot),
+    ...readPnpmWorkspaces(repoRoot),
+    ...readLernaWorkspaces(repoRoot),
+  ].filter(Boolean);
+}
+
+function readPackageWorkspaces(repoRoot) {
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const workspaces = pkg?.workspaces;
+  if (Array.isArray(workspaces)) return workspaces;
+  if (Array.isArray(workspaces?.packages)) return workspaces.packages;
+  return [];
+}
+
+function readLernaWorkspaces(repoRoot) {
+  const lerna = readJson(path.join(repoRoot, 'lerna.json'));
+  return Array.isArray(lerna?.packages) ? lerna.packages : [];
+}
+
+function readPnpmWorkspaces(repoRoot) {
+  try {
+    const body = fs.readFileSync(path.join(repoRoot, 'pnpm-workspace.yaml'), 'utf-8');
+    const patterns = [];
+    let inPackages = false;
+    for (const line of body.split(/\r?\n/)) {
+      const trimmed = stripYamlInlineComment(line).trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const flowMatch = trimmed.match(/^packages:\s*\[(.*)\]\s*$/);
+      if (flowMatch) {
+        patterns.push(...parseYamlFlowList(flowMatch[1]));
+        inPackages = false;
+        continue;
+      }
+      if (/^packages:\s*$/.test(trimmed)) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages && /^[A-Za-z0-9_-]+:\s*/.test(trimmed)) break;
+      if (inPackages) {
+        const match = trimmed.match(/^-\s*(.+)$/);
+        if (match) patterns.push(unquoteYamlValue(match[1]));
+      }
+    }
+    return patterns;
+  } catch {
+    return [];
+  }
+}
+
+function stripYamlInlineComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if ((ch === '"' || ch === "'") && line[i - 1] !== '\\') {
+      quote = quote === ch ? null : quote || ch;
+      continue;
+    }
+    if (ch === '#' && !quote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseYamlFlowList(body) {
+  const items = [];
+  let quote = null;
+  let current = '';
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if ((ch === '"' || ch === "'") && body[i - 1] !== '\\') {
+      quote = quote === ch ? null : quote || ch;
+      current += ch;
+      continue;
+    }
+    if (ch === ',' && !quote) {
+      const value = unquoteYamlValue(current);
+      if (value) items.push(value);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  const value = unquoteYamlValue(current);
+  if (value) items.push(value);
+  return items;
+}
+
+function unquoteYamlValue(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^['"]|['"]$/g, '');
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function projectRootFromWorkspacePattern(repoRoot, relSegments, rawPattern) {
+  const pattern = normalizeWorkspacePattern(rawPattern);
+  if (!pattern || pattern.startsWith('!')) return null;
+  const patternSegments = pattern.split('/').filter(Boolean);
+  if (!patternSegments.length) return null;
+  if (patternSegments.includes('**')) {
+    return projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments);
+  }
+  if (relSegments.length < patternSegments.length) return null;
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!segmentMatches(patternSegments[i], relSegments[i])) return null;
+  }
+  return path.join(repoRoot, ...relSegments.slice(0, patternSegments.length));
+}
+
+function projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments) {
+  const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
+  const literalPrefix = firstGlobIndex === -1
+    ? patternSegments
+    : patternSegments.slice(0, firstGlobIndex);
+  if (relSegments.length < literalPrefix.length + 1) return null;
+  for (let i = 0; i < literalPrefix.length; i++) {
+    if (!segmentMatches(literalPrefix[i], relSegments[i])) return null;
+  }
+  const prefixDir = path.join(repoRoot, ...literalPrefix);
+  const targetDir = path.join(repoRoot, ...relSegments);
+  const packageRoot = nearestPackageRootBetween(repoRoot, targetDir, prefixDir);
+  if (packageRoot) return packageRoot;
+  return path.join(repoRoot, ...relSegments.slice(0, literalPrefix.length + 1));
+}
+
+function normalizeWorkspacePattern(pattern) {
+  return String(pattern || '')
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
+function segmentMatches(patternSegment, relSegment) {
+  if (patternSegment === '*') return true;
+  if (!patternSegment.includes('*')) return patternSegment === relSegment;
+  const re = new RegExp(`^${escapeRegExp(patternSegment).replace(/\\\*/g, '[^/]*')}$`);
+  return re.test(relSegment);
+}
+
 function firstExisting(dir, names) {
   for (const name of names) {
     const abs = path.join(dir, name);
@@ -89,24 +690,64 @@ function safeRead(p) {
   }
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Read the first non-empty line under a bare `## <heading>` section of
+ * PRODUCT.md (e.g. `## Register`, `## Platform`). Returns null when the
+ * section is absent. The heading match is exact (`\s*$`) so near-miss
+ * headings like `## Register guidelines` don't shadow the real field.
+ */
+export function extractSectionValue(product, heading) {
+  if (!product) return null;
+  const headingRe = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'i');
+  const lines = product.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (headingRe.test(lines[i].trim())) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const next = lines[j].trim();
+        // A new heading before any value means the section is empty.
+        if (/^#{1,6}\s/.test(next)) return null;
+        if (next) return next;
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
  * for a `## Register` section and reading the first non-empty line that
  * follows it. Returns null when the file is legacy / register-less.
  */
 export function extractRegister(product) {
-  if (!product) return null;
-  const lines = product.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Register\b/i.test(lines[i].trim())) {
-      for (let j = i + 1; j < lines.length; j++) {
-        const next = lines[j].trim();
-        if (!next) continue;
-        const word = next.toLowerCase();
-        if (word === 'brand' || word === 'product') return word;
-        return null;
-      }
-    }
+  const word = (extractSectionValue(product, 'Register') || '').toLowerCase();
+  return word === 'brand' || word === 'product' ? word : null;
+}
+
+/**
+ * Pull the platform (`web`, `ios`, `android`, or `adaptive`) out of PRODUCT.md
+ * by looking for a `## Platform` section and reading the first non-empty line
+ * that follows it. `adaptive` is for cross-platform apps (Flutter, React
+ * Native) that ship both iOS and Android from one codebase; a line that names
+ * both targets (e.g. `ios, android`) is also read as `adaptive`. Returns null
+ * when the file is legacy / platform-less, which the skill treats as `web`
+ * (the default the general rules already assume).
+ */
+export function extractPlatform(product) {
+  const value = (extractSectionValue(product, 'Platform') || '').toLowerCase();
+  if (!value) return null;
+  if (value === 'web' || value === 'ios' || value === 'android' || value === 'adaptive') return value;
+  // A short list naming both native targets (`ios, android`, `ios and
+  // android`) = adaptive. Only list separators and the two platform words may
+  // appear; anything else (prose, negations) is unrecognized and falls
+  // through to the CLI's WARNING path.
+  const tokens = value.split(/[\s,+&/]+/).filter(t => t && t !== 'and');
+  if (tokens.length >= 2 && tokens.every(t => t === 'ios' || t === 'android')
+    && tokens.includes('ios') && tokens.includes('android')) {
+    return 'adaptive';
   }
   return null;
 }
@@ -172,8 +813,8 @@ function buildUpdateDirective(localVersion, latestVersion) {
     `UPDATE_AVAILABLE: A newer Impeccable skill is available ` +
     `(installed v${localVersion}, latest v${latestVersion}). ` +
     `Before continuing, ask the user once: "A newer Impeccable (v${latestVersion}) is available. ` +
-    `Update now? It runs \`npx impeccable skills update\`." ` +
-    `If they agree, run \`npx impeccable skills update\` (the update applies to the next session, not this one). ` +
+    `Update now? It runs \`npx impeccable update\`." ` +
+    `If they agree, run \`npx impeccable update\` (the update applies to the next session, not this one). ` +
     `Either way, continue the current task without waiting, and do not raise this again.`
   );
 }
@@ -184,9 +825,23 @@ function buildUpdateDirective(localVersion, latestVersion) {
  * the user's home dir) and re-surfaces a given version at most once per week so
  * the agent never nags. Opt out entirely with IMPECCABLE_NO_UPDATE_CHECK=1.
  */
+// Read the unified config's top-level `updateCheck` (local overrides shared).
+// Inlined rather than importing hook-lib so the boot path stays lightweight.
+function updateCheckDisabledByConfig(cwd = process.cwd()) {
+  let value;
+  for (const name of ['config.json', 'config.local.json']) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', name), 'utf-8'));
+      if (raw && typeof raw === 'object' && typeof raw.updateCheck === 'boolean') value = raw.updateCheck;
+    } catch { /* missing or malformed: ignore */ }
+  }
+  return value === false;
+}
+
 async function computeUpdateDirective(now = Date.now()) {
   try {
     if (process.env.IMPECCABLE_NO_UPDATE_CHECK) return null;
+    if (updateCheckDisabledByConfig()) return null;
     const localVersion = readLocalSkillVersion();
     if (!localVersion) return null;
 
@@ -219,7 +874,24 @@ async function computeUpdateDirective(now = Date.now()) {
 }
 
 async function cli() {
-  const ctx = loadContext(process.cwd());
+  let cliOptions;
+  try {
+    cliOptions = parseCliOptions(process.argv.slice(2));
+  } catch (err) {
+    if (err?.name === 'TargetArgError') {
+      process.stderr.write(`${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const targetProvided = hasTargetOption(cliOptions);
+  const targetExists = targetProvided ? pathExistsForTarget(process.cwd(), cliOptions.targetPath) : null;
+  const selection = resolveTargetSelection(process.cwd(), cliOptions);
+  if (selection) {
+    process.stdout.write(buildTargetSelectionDirective(selection) + '\n');
+    process.exit(0);
+  }
+  const ctx = loadContext(process.cwd(), cliOptions);
   const updateDirective = await computeUpdateDirective();
 
   if (!ctx.hasProduct) {
@@ -227,9 +899,16 @@ async function cli() {
     // — cheap models miss the empty case more often than the explicit one.
     const parts = [
       'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
-      'Stop the current task, load reference/init.md, and follow its ' +
-      'instructions to write PRODUCT.md before resuming.',
+      'Follow SKILL.md Setup step 1: for `init`, `teach`, `craft`, `shape`, ' +
+      'or wording that clearly maps to a from-scratch build/shape flow, load ' +
+      'reference/init.md and write PRODUCT.md first; for any other (scoped) ' +
+      'command against existing code, proceed using the code as context and ' +
+      `offer \`${IMPECCABLE_COMMAND} init\` as a suggestion (do not block).`,
     ];
+    parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
+    if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
+      parts.push(buildMissingTargetDirective());
+    }
     if (updateDirective) parts.push(updateDirective);
     process.stdout.write(parts.join('\n\n---\n\n') + '\n');
     process.exit(0);
@@ -238,15 +917,93 @@ async function cli() {
   if (ctx.hasDesign) {
     parts.push(`# DESIGN.md\n\n${ctx.design.trim()}`);
   }
+  parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
+  if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
+    parts.push(buildMissingTargetDirective());
+  }
   const register = extractRegister(ctx.product);
   const next = register
     ? `NEXT STEP: This project's register is \`${register}\`. You MUST now read \`reference/${register}.md\` before producing any design output.`
     : `NEXT STEP: You MUST now read the matching register reference (\`reference/brand.md\` or \`reference/product.md\`) before producing any design output. Pick based on PRODUCT.md above.`;
   parts.push(next);
+  const platform = extractPlatform(ctx.product);
+  const nativeRefs =
+    platform === 'adaptive' ? ['ios', 'android'] : platform === 'ios' || platform === 'android' ? [platform] : [];
+  if (nativeRefs.length) {
+    const refList = nativeRefs.map(p => `\`reference/${p}.md\``).join(' and ');
+    const label = platform === 'adaptive' ? '`adaptive` (both iOS and Android)' : `\`${platform}\``;
+    parts.push(
+      `NEXT STEP: This project targets ${label}. Also read ${refList} for native conventions, in addition to the register reference.`,
+    );
+  } else if (!platform) {
+    // A `## Platform` section that names something we don't recognize (a
+    // toolchain like `flutter`, a typo) would otherwise silently fall back to
+    // web — the wrong default exactly when the user tried to say "native".
+    const rawPlatform = extractSectionValue(ctx.product, 'Platform');
+    if (rawPlatform) {
+      parts.push(
+        `WARNING: PRODUCT.md's \`## Platform\` value \`${rawPlatform}\` is not recognized; treating the project as \`web\`. Valid values are \`web\`, \`ios\`, \`android\`, or \`adaptive\` (cross-platform, ships both). If this project is native, fix the field (name the design language the app renders, not the toolchain) and surface it to the user.`,
+      );
+    }
+  }
   if (updateDirective) parts.push(updateDirective);
   process.stdout.write(parts.join('\n\n---\n\n') + '\n');
 }
 
+function parseCliOptions(args) {
+  return parseTargetOptions(args, { strict: true });
+}
+
+function hasTargetOption(options) {
+  return !!(options && typeof options.targetPath === 'string' && options.targetPath.trim());
+}
+
+function pathExistsForTarget(cwd, targetPath) {
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+  return fs.existsSync(abs);
+}
+
+function buildResolvedContextDirective(ctx, options, { targetExists = null } = {}) {
+  const targetPath = hasTargetOption(options) ? options.targetPath : null;
+  return `RESOLVED_CONTEXT:\n${JSON.stringify({
+    targetPath,
+    ...(targetPath ? { targetExists } : {}),
+    projectRoot: ctx.projectRoot,
+    repoRoot: ctx.repoRoot,
+    productPath: ctx.productPath,
+    designPath: ctx.designPath,
+  }, null, 2)}`;
+}
+
+function shouldWarnMissingTarget(ctx, targetProvided, targetExists = null) {
+  if (ctx.isMonorepo && targetProvided && targetExists === false) return true;
+  return !!(
+    ctx.isMonorepo
+    && (!targetProvided || targetExists === false)
+    && ctx.projectRoot
+    && ctx.repoRoot
+    && path.resolve(ctx.projectRoot) === path.resolve(ctx.repoRoot)
+  );
+}
+
+function buildMissingTargetDirective() {
+  const script = process.argv[1] || 'context.mjs';
+  return (
+    'MONOREPO_TARGET_REQUIRED: This is a monorepo and context.mjs ran without --target. ' +
+    'If the user named a file, route, or child app, do not answer from this output. ' +
+    `Rerun \`node ${script} --target <path>\` and answer from that run's RESOLVED_CONTEXT fields.`
+  );
+}
+
+function buildTargetSelectionDirective(selection) {
+  return (
+    `TARGET_SELECTION_REQUIRED:\n${JSON.stringify(selection, null, 2)}\n\n` +
+    'Show each app with its productStatus/productPath and designStatus/designPath so the user can see child overrides, inherited root files, fallback files, or missing files before choosing. ' +
+    'Ask the user which app Impeccable should use, then rerun Impeccable helper commands from that child app cwd using this same scripts directory. ' +
+    'Use `--target <path>` only as a fallback when changing cwd is not possible, or when the user explicitly named a file/path.'
+  );
+}
+
 // Run cli() only when this module is the entry point. Compare realpaths
 // rather than endsWith(): a loose suffix match also fires for unrelated
 // scripts like `load-context.mjs`, and realpath tolerates symlinked

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

@@ -2,11 +2,11 @@
 /**
  * Critique persistence helper.
  *
- * Each run of /impeccable critique writes a per-target snapshot to
+ * Each critique run writes a per-target snapshot to
  *   .impeccable/critique/<timestamp>__<slug>.md
  * with a small YAML frontmatter carrying the score + P0/P1 counts.
  *
- * /impeccable polish reads the latest matching snapshot at start as its
+ * The polish workflow reads the latest matching snapshot at start as its
  * fix backlog. No other skill auto-reads critique output.
  *
  * The slug is derived mechanically from the *resolved* primary artifact
@@ -28,7 +28,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getCritiqueDir } from './impeccable-paths.mjs';
+import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 const SLUG_MAX = 50;
 

.agents/skills/impeccable/scripts/detector/browser/injected/index.mjs

@@ -660,6 +660,7 @@ if (IS_BROWSER) {
       if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
       if (el.closest('[id^="impeccable-live-"]')) continue;
       if (el === document.body || el === document.documentElement) continue;
+      if (!isRenderedForBrowserRule(el)) continue;
 
       const tag = el.tagName.toLowerCase();
       const style = getComputedStyle(el);
@@ -1091,6 +1092,7 @@ if (IS_BROWSER) {
       return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'stale selector' };
     }
     if (!el) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing element' };
+    if (!isRenderedForBrowserRule(el)) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'hidden element' };
 
     const blockingReason = (candidate.reasons || []).find(reason =>
       reason === 'background-clip text' ||
@@ -1222,6 +1224,7 @@ if (IS_BROWSER) {
           category: ap ? ap.category : 'quality',
           severity: ap?.severity || 'warning',
           detail: f.detail || f.snippet,
+          ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
           description: ap ? ap.description : '',
         };
@@ -1258,10 +1261,203 @@ if (IS_BROWSER) {
     return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
   }
 
+  const DESIGN_COLOR_TOLERANCE = 6;
+  const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
+  const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
+
+  function normalizeBrowserFontName(value) {
+    return String(value || '')
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .replace(/\+/g, ' ')
+      .replace(/\s+/g, ' ')
+      .toLowerCase();
+  }
+
+  function browserPrimaryFont(stack) {
+    if (!stack || /var\(/i.test(stack)) return '';
+    return String(stack || '')
+      .split(',')
+      .map(normalizeBrowserFontName)
+      .find(font => font && !GENERIC_FONTS.has(font)) || '';
+  }
+
+  function browserDesignSystemConfig() {
+    const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
+    if (!raw?.present) return null;
+    const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
+    const allowedColors = (raw.allowedColors || [])
+      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
+      .map(color => ({ r: color.r, g: color.g, b: color.b }));
+    const allowedRadii = (raw.allowedRadii || [])
+      .map(Number)
+      .filter(px => Number.isFinite(px));
+    return {
+      present: true,
+      hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
+      allowedFonts,
+      hasColors: raw.hasColors === true && allowedColors.length > 0,
+      allowedColors,
+      hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
+      allowedRadii,
+      hasPillRadius: raw.hasPillRadius === true,
+    };
+  }
+
+  function browserColorsClose(a, b) {
+    if (!a || !b) return false;
+    return Math.max(
+      Math.abs(a.r - b.r),
+      Math.abs(a.g - b.g),
+      Math.abs(a.b - b.b),
+    ) <= DESIGN_COLOR_TOLERANCE;
+  }
+
+  function isBrowserDesignColorAllowed(raw, designSystem) {
+    if (!designSystem?.hasColors) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
+    if (text.includes('var(')) return true;
+    const parsed = parseAnyColor(text);
+    if (!parsed) return true;
+    if ((parsed.a ?? 1) <= 0.05) return true;
+    return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
+  }
+
+  function isBrowserTransparentCss(value) {
+    const text = String(value || '').trim().toLowerCase();
+    if (!text || text === 'transparent') return true;
+    const parsed = parseAnyColor(text);
+    return parsed ? (parsed.a ?? 1) <= 0.05 : false;
+  }
+
+  function isBrowserDesignRadiusAllowed(raw, designSystem) {
+    if (!designSystem?.hasRadii) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
+    if (text.includes('var(') || text.includes('%')) return true;
+    const px = resolveLengthPx(text, 16);
+    if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
+    if (designSystem.hasPillRadius && px >= 99) return true;
+    return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
+  }
+
+  function browserRadiusTokens(value) {
+    return String(value || '')
+      .replace(/\s*\/\s*/g, ' ')
+      .split(/\s+/)
+      .map(token => token.trim())
+      .filter(Boolean);
+  }
+
+  function browserHasDirectText(el) {
+    return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
+  }
+
+  function browserSampleText(el) {
+    const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
+    return text ? ` "${text.slice(0, 40)}"` : '';
+  }
+
+  function shouldSkipDesignElement(el) {
+    const tag = el.tagName?.toLowerCase?.() || '';
+    return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
+  }
+
+  function checkElementDesignSystemDOM(el, designSystem, seen) {
+    if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
+    const findings = [];
+    const tag = el.tagName?.toLowerCase?.() || 'unknown';
+    const style = getComputedStyle(el);
+
+    if (designSystem.hasFonts && browserHasDirectText(el)) {
+      const font = browserPrimaryFont(style.fontFamily || '');
+      if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
+          ignoreValue: font,
+        });
+      }
+    }
+
+    if (designSystem.hasColors) {
+      const colorChecks = [];
+      if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
+      if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
+      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
+          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
+        }
+      }
+      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
+
+      for (const [kind, raw] of colorChecks) {
+        const label = String(raw || '').trim().replace(/\s+/g, ' ');
+        if (isBrowserDesignColorAllowed(label, designSystem)) continue;
+        const key = `${kind}:${label}`;
+        if (seen.colors.has(key)) continue;
+        seen.colors.add(key);
+        findings.push({
+          type: 'design-system-color',
+          detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
+          ignoreValue: label,
+        });
+      }
+    }
+
+    if (designSystem.hasRadii) {
+      for (const token of browserRadiusTokens(style.borderRadius || '')) {
+        if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
+        if (seen.radii.has(token)) continue;
+        seen.radii.add(token);
+        findings.push({
+          type: 'design-system-radius',
+          detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
+          ignoreValue: token,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  function decodeBrowserGoogleFamily(value) {
+    const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
+    try {
+      return decodeURIComponent(family);
+    } catch {
+      return family;
+    }
+  }
+
+  function checkBrowserDesignSystemSources(designSystem, seen) {
+    if (!designSystem?.hasFonts) return [];
+    const findings = [];
+    for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
+      const href = link.getAttribute('href') || '';
+      for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
+        const display = decodeBrowserGoogleFamily(match[1]);
+        const font = normalizeBrowserFontName(display);
+        if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
+          ignoreValue: display,
+        });
+      }
+    }
+    return findings;
+  }
+
   function collectBrowserFindings() {
     const groupMap = new Map();
     const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
     const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
+    const designSystem = browserDesignSystemConfig();
+    const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
     // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
     // real browser env (detector page, live overlay, extension) running every
     // check is free, so we always surface them; the gating is purely a CLI
@@ -1292,6 +1488,7 @@ if (IS_BROWSER) {
         ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementDesignSystemDOM(el, designSystem, designSeen),
       ].filter(f => _ruleOk(f.type));
 
       addBrowserFindings(groupMap, el, findings);
@@ -1308,6 +1505,13 @@ if (IS_BROWSER) {
 
     const pageLevelFindings = [];
 
+    const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
+      .filter(f => _ruleOk(f.type));
+    if (designSourceFindings.length > 0) {
+      pageLevelFindings.push(...designSourceFindings);
+      addBrowserFindings(groupMap, document.body, designSourceFindings);
+    }
+
     const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
     if (typoFindings.length > 0) {
       pageLevelFindings.push(...typoFindings);
@@ -1437,13 +1641,20 @@ if (IS_BROWSER) {
     return true;
   }
 
-  function postSerializedFindings(groupMap) {
+  function scanResultMeta(options = {}) {
+    const scanId = options.scanId;
+    if (typeof scanId !== 'string' && typeof scanId !== 'number') return {};
+    return { scanId: String(scanId) };
+  }
+
+  function postSerializedFindings(groupMap, options = {}) {
     if (!EXTENSION_MODE) return;
     const allFindings = browserFindingsFromMap(groupMap);
     window.postMessage({
       source: 'impeccable-results',
       findings: serializeFindings(allFindings),
       count: allFindings.length,
+      ...scanResultMeta(options),
     }, '*');
   }
 
@@ -1497,7 +1708,7 @@ if (IS_BROWSER) {
             rememberVisualContrastAnalysis(result);
             const added = addVisualContrastResult(groupMap, result, { decorate: true });
             if (added) {
-              postSerializedFindings(groupMap);
+              postSerializedFindings(groupMap, options);
               window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-resolved', {
                 detail: {
                   selector: result.selector,
@@ -1565,7 +1776,7 @@ if (IS_BROWSER) {
     overlayIndex = 0;
   }
 
-  function renderBrowserFindings(collected) {
+  function renderBrowserFindings(collected, options = {}) {
     const { allFindings, pageLevelFindings } = collected;
 
     for (const { el, findings } of allFindings) {
@@ -1585,6 +1796,7 @@ if (IS_BROWSER) {
         source: 'impeccable-results',
         findings: serializeFindings(allFindings),
         count: allFindings.length,
+        ...scanResultMeta(options),
       }, '*');
     }
 
@@ -1599,11 +1811,11 @@ if (IS_BROWSER) {
     clearOverlays();
     const generation = scanGeneration;
     const collected = collectBrowserFindings();
-    const allFindings = renderBrowserFindings(collected);
+    const allFindings = renderBrowserFindings(collected, options);
     if (shouldRunVisualContrast(options)) {
       addVisualContrastFindings(collected.groupMap, options, { decorate: true, generation })
         .then(() => {
-          if (generation === scanGeneration) postSerializedFindings(collected.groupMap);
+          if (generation === scanGeneration) postSerializedFindings(collected.groupMap, options);
         })
         .catch(err => {
           reportVisualContrastError(err);
@@ -1618,10 +1830,10 @@ if (IS_BROWSER) {
     if (shouldRunVisualContrast(options)) {
       const collected = await collectBrowserFindingsAsync(options, { generation, scheduleLazy: true });
       if (generation !== scanGeneration) return [];
-      return renderBrowserFindings(collected);
+      return renderBrowserFindings(collected, options);
     }
     lastVisualContrastAnalyses = [];
-    return renderBrowserFindings(collectBrowserFindings());
+    return renderBrowserFindings(collectBrowserFindings(), options);
   };
 
   const detect = function(options = {}) {

.agents/skills/impeccable/scripts/detector/cli/main.mjs

@@ -1,9 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { loadDesignSystemForCwd } from '../design-system.mjs';
+import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
 import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
 import { detectHtml } from '../engines/static-html/detect-html.mjs';
 import { detectText } from '../engines/regex/detect-text.mjs';
+import {
+  filterDetectionFindings,
+  readDetectionConfig,
+  shouldIgnoreDetectionFile,
+} from '../../lib/impeccable-config.mjs';
 import {
   HTML_EXTENSIONS,
   buildImportGraph,
@@ -16,6 +23,10 @@ import {
 // Output formatting
 // ---------------------------------------------------------------------------
 
+function formatFindingSummary(count) {
+  return `${count} anti-pattern${count === 1 ? '' : 's'} found.`;
+}
+
 function formatFindings(findings, jsonMode) {
   if (jsonMode) return JSON.stringify(findings, null, 2);
 
@@ -33,7 +44,7 @@ function formatFindings(findings, jsonMode) {
       out.push(`    → ${item.description}`);
     }
   }
-  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found.`);
+  out.push(`\n${formatFindingSummary(findings.length)}`);
   return out.join('\n');
 }
 
@@ -79,10 +90,30 @@ function printUsage() {
 Scan files or URLs for UI anti-patterns and design quality issues.
 
 Options:
-  --json    Output results as JSON
-  --gpt     Also report GPT-specific provider tells (off by default)
-  --gemini  Also report Gemini-specific provider tells (off by default)
-  --help    Show this help message
+  --json              Output results as JSON
+  --quiet             In text mode, only print the final findings count
+  --gpt               Also report GPT-specific provider tells (off by default)
+  --gemini            Also report Gemini-specific provider tells (off by default)
+  --scope <name>      Only report rules in the given design domain
+                      (type, layout). Comma-separated.
+  --no-config         Do not apply project config, detector ignores, inline
+                      ignore comments, or DESIGN.md
+  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
+  --no-design-system  Do not load local DESIGN.md / .impeccable/design.json context
+  --help              Show this help message
+
+Project config:
+  Respects .impeccable/config.json and .impeccable/config.local.json detector
+  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
+  and detector.designSystem.enabled.
+
+Inline ignores:
+  In-file comments waive a finding where it lives and travel with the file:
+    <!-- impeccable-disable overused-font -- exported brand doc -->
+    .brand { font-family: Inter } /* impeccable-disable-line overused-font */
+    // impeccable-disable-next-line bounce-easing: intentional bounce
+  impeccable-disable applies to the whole file; -line / -next-line are scoped.
+  List one or more rule ids (comma-separated), or omit them / use * for all.
 
 Detection modes:
   HTML files     Static HTML/CSS analysis (default, catches linked CSS)
@@ -93,7 +124,8 @@ Examples:
   impeccable detect src/
   impeccable detect index.html
   impeccable detect https://example.com
-  impeccable detect --json .`);
+  impeccable detect --json .
+  impeccable detect --no-config src/`);
 }
 
 async function detectCli() {
@@ -104,6 +136,7 @@ async function detectCli() {
   });
   if (args[0] === 'detect') args = args.slice(1);
   const jsonMode = args.includes('--json');
+  const quietMode = args.includes('--quiet');
   const helpMode = args.includes('--help');
   // --fast (regex-only) is deprecated: since the jsdom removal, the static
   // HTML/CSS analysis is fast and covers every rule, so the regex-only path
@@ -114,10 +147,48 @@ async function detectCli() {
       'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
     );
   }
+  const configEnabled = !args.includes('--no-config');
+  const detectionConfig = configEnabled
+    ? readDetectionConfig(process.cwd())
+    : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
   const providers = [];
   if (args.includes('--gpt')) providers.push('gpt');
   if (args.includes('--gemini')) providers.push('gemini');
-  const scanOptions = { providers };
+  const scopes = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
+    const inline = args[i].startsWith('--scope=');
+    const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
+    const parsed = (value && !value.startsWith('--'))
+      ? value.split(',').map(s => s.trim()).filter(Boolean)
+      : [];
+    // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
+    // fail loudly so a mistyped pre-scan never runs the wrong rule set.
+    if (parsed.length === 0) {
+      process.stderr.write(
+        `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+      );
+      process.exit(1);
+    }
+    scopes.push(...parsed);
+    args.splice(i, inline ? 1 : 2);
+    i -= 1;
+  }
+  const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
+  if (unknownScopes.length > 0) {
+    process.stderr.write(
+      `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
+    );
+    process.exit(1);
+  }
+  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
+  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
+  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
+  // apply by default. `--no-config` (raw scan) and the dedicated
+  // `--no-inline-ignores` both turn them off.
+  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
+  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
+  if (designSystem) scanOptions.designSystem = designSystem;
   const targets = args.filter(a => !a.startsWith('--'));
 
   if (helpMode) { printUsage(); process.exit(0); }
@@ -149,8 +220,8 @@ async function detectCli() {
         catch { process.stderr.write(`Warning: cannot access ${target}\n`); continue; }
 
         if (stat.isDirectory()) {
-          // Check for framework dev server config (skip in JSON mode to avoid polluting output)
-          if (!jsonMode) {
+          // Check for framework dev server config (skip in JSON/quiet modes to avoid polluting output)
+          if (!jsonMode && !quietMode) {
             const fwConfig = detectFrameworkConfig(resolved);
             if (fwConfig) {
               const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint);
@@ -175,11 +246,12 @@ async function detectCli() {
             }
           }
 
-          const files = walkDir(resolved);
+          const files = walkDir(resolved)
+            .filter(file => !shouldIgnoreDetectionFile(file, process.cwd(), detectionConfig));
           const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;
 
           // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
-          if (files.length > 50 && process.stdin.isTTY && !jsonMode) {
+          if (files.length > 50 && process.stdin.isTTY && !jsonMode && !quietMode) {
             process.stderr.write(
               `\nFound ${files.length} files (${htmlCount} HTML) in ${target}.\n` +
               `Scanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\n` +
@@ -219,6 +291,7 @@ async function detectCli() {
             allFindings.push(...fileFindings);
           }
         } else if (stat.isFile()) {
+          if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
           const ext = path.extname(resolved).toLowerCase();
           if (HTML_EXTENSIONS.has(ext)) {
             allFindings.push(...await detectHtml(resolved, scanOptions));
@@ -232,8 +305,12 @@ async function detectCli() {
     }
   }
 
+  allFindings = filterDetectionFindings(allFindings, detectionConfig);
+  allFindings = filterByScopes(allFindings, scopes);
+
   if (allFindings.length > 0) {
     if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
+    else if (quietMode) process.stderr.write(formatFindingSummary(allFindings.length) + '\n');
     else process.stderr.write(formatFindings(allFindings, false) + '\n');
     process.exit(2);
   }

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

@@ -0,0 +1,814 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { finding } from './findings.mjs';
+import { GENERIC_FONTS } from './shared/constants.mjs';
+import { parseAnyColor, resolveLengthPx } from './rules/checks.mjs';
+
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const FALLBACK_DIRS = ['.agents/context', 'docs'];
+const COLOR_CHANNEL_TOLERANCE = 6;
+const RADIUS_TOLERANCE_PX = 0.5;
+const FONT_SIZE_TOLERANCE_PX = 0.5;
+const FONT_SIZE_LITERAL_RE = /^-?[\d.]+(?:px|rem)$/;
+
+const CSS_COLOR_RE = /#[0-9a-f]{3,8}\b|rgba?\([^)]+\)|oklch\([^)]+\)|hsla?\([^)]+\)/gi;
+const FONT_DECL_RE = /font-family\s*:\s*([^;}\n]+)/gi;
+const FONT_JS_RE = /fontFamily\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
+const GOOGLE_FONT_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
+const BORDER_RADIUS_RE = /border-radius\s*:\s*([^;}\n]+)/gi;
+const BORDER_RADIUS_JS_RE = /borderRadius\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
+const FONT_SIZE_DECL_RE = /font-size\s*:\s*([^;}\n]+)/gi;
+const FONT_SIZE_JS_RE = /fontSize\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
+const TAILWIND_FONT_SIZE_RE = /\btext-\[(-?[\d.]+(?:px|rem))\]/g;
+const STATIC_DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
+
+function firstExisting(dir, names) {
+  for (const name of names) {
+    const abs = path.join(dir, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function resolveDesignMdPath(cwd = process.cwd()) {
+  const root = firstExisting(cwd, DESIGN_NAMES);
+  if (root) return { path: root, contextDir: cwd };
+
+  for (const rel of FALLBACK_DIRS) {
+    const dir = path.resolve(cwd, rel);
+    const found = firstExisting(dir, DESIGN_NAMES);
+    if (found) return { path: found, contextDir: dir };
+  }
+
+  return null;
+}
+
+function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd) {
+  const candidates = [
+    path.join(cwd, '.impeccable', 'design.json'),
+    path.join(cwd, 'DESIGN.json'),
+    path.join(contextDir, 'DESIGN.json'),
+  ];
+  return candidates.find((candidate, index) =>
+    candidates.indexOf(candidate) === index && fs.existsSync(candidate)
+  ) || null;
+}
+
+function parseFrontmatter(md) {
+  const lines = String(md || '').split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') return null;
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) return null;
+  try {
+    return parseYamlSubset(lines.slice(1, end).join('\n'));
+  } catch {
+    return null;
+  }
+}
+
+function parseYamlSubset(yaml) {
+  const root = {};
+  const stack = [{ indent: -1, obj: root }];
+
+  for (const raw of String(yaml || '').split(/\r?\n/)) {
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+    const indent = raw.match(/^\s*/)[0].length;
+    const content = raw.slice(indent);
+    const colonIdx = findTopLevelColon(content);
+    if (colonIdx === -1) continue;
+
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
+
+    const key = unquoteYamlKey(content.slice(0, colonIdx).trim());
+    const rest = stripInlineYamlComment(content.slice(colonIdx + 1).trim());
+    const parent = stack[stack.length - 1].obj;
+
+    if (rest === '') {
+      const obj = {};
+      parent[key] = obj;
+      stack.push({ indent, obj });
+    } else {
+      parent[key] = parseScalar(rest);
+    }
+  }
+
+  return root;
+}
+
+function findTopLevelColon(s) {
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inQuote) {
+      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ':') {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function unquoteYamlKey(key) {
+  if ((key.startsWith('"') && key.endsWith('"')) || (key.startsWith("'") && key.endsWith("'"))) {
+    return key.slice(1, -1);
+  }
+  return key;
+}
+
+function stripInlineYamlComment(s) {
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inQuote) {
+      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === '#' && i > 0 && /\s/.test(s[i - 1])) {
+      return s.slice(0, i).trimEnd();
+    }
+  }
+  return s;
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === 'null' || s === '~') return null;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (/^-?\d*\.\d+$/.test(s)) return Number(s);
+  return s;
+}
+
+function safeReadJson(filePath) {
+  if (!filePath) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeFontName(value) {
+  return String(value || '')
+    .trim()
+    .replace(/\s*!important\s*$/i, '')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+function splitFontStack(stack) {
+  return String(stack || '')
+    .replace(/\s*!important\s*$/i, '')
+    .split(',')
+    .map(normalizeFontName)
+    .filter(Boolean);
+}
+
+function primaryFont(stack) {
+  if (!stack || /var\(/i.test(stack) || !isLiteralFontStack(stack)) return '';
+  return splitFontStack(stack).find(font => !GENERIC_FONTS.has(font)) || '';
+}
+
+function isLiteralFontStack(stack) {
+  const text = String(stack || '');
+  return !/[$`{}]|\s\+\s|\|\|/.test(text);
+}
+
+function cssColorLabel(raw) {
+  return String(raw || '').trim().replace(/\s+/g, ' ');
+}
+
+function colorKey(color) {
+  if (!color) return '';
+  return `${color.r},${color.g},${color.b}`;
+}
+
+function colorsClose(a, b) {
+  if (!a || !b) return false;
+  return Math.max(
+    Math.abs(a.r - b.r),
+    Math.abs(a.g - b.g),
+    Math.abs(a.b - b.b),
+  ) <= COLOR_CHANNEL_TOLERANCE;
+}
+
+function hslToRgb(H, S, L, alpha = 1) {
+  const h = (((H % 360) + 360) % 360) / 360;
+  const s = Math.max(0, Math.min(1, S));
+  const l = Math.max(0, Math.min(1, L));
+  const hue2rgb = (p, q, t) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  return {
+    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),
+    g: Math.round(hue2rgb(p, q, h) * 255),
+    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),
+    a: alpha,
+  };
+}
+
+function parseDesignColor(value) {
+  const text = String(value || '').trim();
+  const parsed = parseAnyColor(text);
+  if (parsed) return parsed;
+  const hsl = text.match(/hsla?\(\s*([-\d.]+)(?:deg)?\s*,?\s*([\d.]+)%\s*,?\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+))?\s*\)/i);
+  if (hsl) {
+    return hslToRgb(
+      parseFloat(hsl[1]),
+      parseFloat(hsl[2]) / 100,
+      parseFloat(hsl[3]) / 100,
+      hsl[4] !== undefined ? parseFloat(hsl[4]) : 1,
+    );
+  }
+  return null;
+}
+
+function addDesignColor(out, value, label) {
+  const parsed = parseDesignColor(value);
+  if (!parsed) return;
+  const key = colorKey(parsed);
+  if (!out.allowedColorKeys.has(key)) {
+    out.allowedColorKeys.set(key, { color: parsed, labels: [] });
+  }
+  out.allowedColorKeys.get(key).labels.push(label || cssColorLabel(value));
+}
+
+function addColorObject(out, colors, prefix = 'colors') {
+  if (!colors || typeof colors !== 'object') return;
+  for (const [name, value] of Object.entries(colors)) {
+    if (typeof value === 'string') {
+      addDesignColor(out, value, `${prefix}.${name}`);
+    }
+  }
+}
+
+function addSidecarColors(out, sidecar) {
+  const colorMeta = sidecar?.extensions?.colorMeta;
+  if (!colorMeta || typeof colorMeta !== 'object') return;
+
+  for (const [name, meta] of Object.entries(colorMeta)) {
+    if (!meta || typeof meta !== 'object') continue;
+    if (typeof meta.canonical === 'string') addDesignColor(out, meta.canonical, `sidecar.${name}`);
+    if (Array.isArray(meta.tonalRamp)) {
+      for (const [index, value] of meta.tonalRamp.entries()) {
+        if (typeof value === 'string') addDesignColor(out, value, `sidecar.${name}.tonalRamp[${index}]`);
+      }
+    }
+  }
+}
+
+function addTypographyFonts(out, typography) {
+  if (!typography || typeof typography !== 'object') return;
+  for (const role of Object.values(typography)) {
+    if (!role || typeof role !== 'object') continue;
+    if (typeof role.fontFamily !== 'string') continue;
+    for (const font of splitFontStack(role.fontFamily)) {
+      if (!GENERIC_FONTS.has(font)) out.allowedFonts.add(font);
+    }
+  }
+}
+
+function addTypographySizes(out, typography) {
+  if (!typography || typeof typography !== 'object') return;
+  for (const role of Object.values(typography)) {
+    if (!role || typeof role !== 'object') continue;
+    const raw = String(role.fontSize ?? '').trim().toLowerCase();
+    if (!FONT_SIZE_LITERAL_RE.test(raw)) continue;
+    const px = resolveLengthPx(raw, 16);
+    if (px == null || !Number.isFinite(px) || px <= 0) continue;
+    out.allowedFontSizes.push({ value: raw, px });
+  }
+}
+
+function addRoundedScale(out, rounded) {
+  if (!rounded || typeof rounded !== 'object') return;
+  for (const [rawName, value] of Object.entries(rounded)) {
+    const name = unquoteYamlKey(rawName).toLowerCase();
+    addRoundedToken(out, name, value);
+  }
+}
+
+function addRoundedToken(out, name, value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return;
+  const raw = String(value).trim();
+  if (!raw || /var\(/i.test(raw) || raw.includes('%')) return;
+  const px = resolveLengthPx(raw, 16);
+  if (px == null || !Number.isFinite(px)) return;
+  out.allowedRadii.push({ name, value: raw, px });
+  if (/(^|\.)(full|pill|round|rounded-full)$/.test(name)) out.hasPillRadius = true;
+}
+
+function addSidecarRadii(out, sidecar) {
+  const roundedMeta = sidecar?.extensions?.roundedMeta;
+  if (!roundedMeta || typeof roundedMeta !== 'object') return;
+
+  for (const [rawName, meta] of Object.entries(roundedMeta)) {
+    const name = unquoteYamlKey(rawName).toLowerCase();
+    if (typeof meta === 'string' || typeof meta === 'number') {
+      addRoundedToken(out, `sidecar.${name}`, meta);
+      continue;
+    }
+    if (!meta || typeof meta !== 'object') continue;
+    for (const key of ['canonical', 'value']) {
+      if (typeof meta[key] === 'string' || typeof meta[key] === 'number') {
+        addRoundedToken(out, `sidecar.${name}.${key}`, meta[key]);
+      }
+    }
+    for (const key of ['values', 'aliases']) {
+      if (!Array.isArray(meta[key])) continue;
+      for (const [index, value] of meta[key].entries()) {
+        addRoundedToken(out, `sidecar.${name}.${key}[${index}]`, value);
+      }
+    }
+    if (/^(full|pill|round|rounded-full)$/.test(name) || /^(full|pill|round)$/i.test(String(meta.role || ''))) {
+      out.hasPillRadius = true;
+    }
+  }
+}
+
+function normalizeDesignSystem(input = {}) {
+  const frontmatter = input.frontmatter || {};
+  const sidecar = input.sidecar || null;
+  const out = {
+    present: true,
+    sourcePath: input.sourcePath || null,
+    sidecarPath: input.sidecarPath || null,
+    mdNewerThanJson: input.mdNewerThanJson === true,
+    allowedFonts: new Set(),
+    allowedColorKeys: new Map(),
+    allowedRadii: [],
+    allowedFontSizes: [],
+    hasPillRadius: false,
+  };
+
+  addTypographyFonts(out, frontmatter.typography);
+  addTypographySizes(out, frontmatter.typography);
+  addColorObject(out, frontmatter.colors);
+  addSidecarColors(out, sidecar);
+  addRoundedScale(out, frontmatter.rounded);
+  addSidecarRadii(out, sidecar);
+
+  out.hasFonts = out.allowedFonts.size > 0;
+  out.hasColors = out.allowedColorKeys.size > 0;
+  out.hasRadii = out.allowedRadii.length > 0;
+  out.hasFontSizes = out.allowedFontSizes.length > 0;
+  return out;
+}
+
+function loadDesignSystemForCwd(cwd = process.cwd()) {
+  const md = resolveDesignMdPath(cwd);
+  if (!md) return null;
+
+  let frontmatter = null;
+  let mdStat = null;
+  try {
+    mdStat = fs.statSync(md.path);
+    frontmatter = parseFrontmatter(fs.readFileSync(md.path, 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!frontmatter || typeof frontmatter !== 'object') return null;
+
+  const sidecarPath = resolveDesignSidecarPath(cwd, md.contextDir);
+  const sidecar = safeReadJson(sidecarPath);
+  let sidecarStat = null;
+  try {
+    if (sidecarPath) sidecarStat = fs.statSync(sidecarPath);
+  } catch {
+    sidecarStat = null;
+  }
+
+  return normalizeDesignSystem({
+    frontmatter,
+    sidecar,
+    sourcePath: md.path,
+    sidecarPath,
+    mdNewerThanJson: !!(mdStat && sidecarStat && mdStat.mtimeMs > sidecarStat.mtimeMs + 1000),
+  });
+}
+
+function isAllowedFont(font, designSystem) {
+  if (!font || GENERIC_FONTS.has(font)) return true;
+  if (!designSystem?.hasFonts) return true;
+  return designSystem.allowedFonts.has(font);
+}
+
+function isAllowedColorRaw(raw, designSystem) {
+  if (!designSystem?.hasColors) return true;
+  const text = String(raw || '').trim().toLowerCase();
+  if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
+  if (text.includes('var(')) return true;
+  const parsed = parseDesignColor(text);
+  if (!parsed) return true;
+  if ((parsed.a ?? 1) <= 0.05) return true;
+  for (const entry of designSystem.allowedColorKeys.values()) {
+    if (colorsClose(parsed, entry.color)) return true;
+  }
+  return false;
+}
+
+function isAllowedRadiusRaw(raw, designSystem) {
+  if (!designSystem?.hasRadii) return true;
+  const text = String(raw || '').trim().toLowerCase();
+  if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
+  if (text.includes('var(') || text.includes('%')) return true;
+  const px = resolveLengthPx(text, 16);
+  if (px == null || !Number.isFinite(px) || px <= RADIUS_TOLERANCE_PX) return true;
+  if (designSystem.hasPillRadius && px >= 99) return true;
+  return designSystem.allowedRadii.some(entry => Math.abs(entry.px - px) <= RADIUS_TOLERANCE_PX);
+}
+
+function isAllowedFontSizeRaw(raw, designSystem) {
+  if (!designSystem?.hasFontSizes) return true;
+  const text = String(raw || '').trim().toLowerCase().replace(/\s*!important\s*$/, '');
+  if (!FONT_SIZE_LITERAL_RE.test(text)) return true;
+  const px = resolveLengthPx(text, 16);
+  if (px == null || !Number.isFinite(px) || px <= 0) return true;
+  return designSystem.allowedFontSizes.some(
+    entry => Math.abs(entry.px - px) <= FONT_SIZE_TOLERANCE_PX,
+  );
+}
+
+function lineLooksCommented(line) {
+  const trimmed = String(line || '').trim();
+  return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('<!--');
+}
+
+function isProbablyColorLiteral(line, match) {
+  const raw = match?.[0] || '';
+  const index = match.index ?? -1;
+  if (index < 0) return false;
+  if (isInsideCssAttributeSelector(line, index)) return false;
+
+  const before = line.slice(0, index);
+  const after = line.slice(index + raw.length);
+
+  if (raw.startsWith('#')) {
+    if (before.endsWith('&')) return false; // HTML numeric entity, e.g. &#8596;
+
+    const prevNonSpace = before.match(/\S(?=\s*$)/)?.[0] || '';
+    const nextNonSpace = after.match(/^\s*(\S)/)?.[1] || '';
+    if (prevNonSpace === '>' && nextNonSpace === '<') return false; // plain text, e.g. PR #155
+  }
+
+  const styleContext = /(?:^|[{\s;"'`(,])(?:color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left))?(?:-color)?|outline(?:-color)?|box-shadow|text-shadow|fill|stroke)\s*:\s*[^;{}"'`]*/i.test(before);
+  const cssFunctionContext = /(?:linear-gradient|radial-gradient|conic-gradient|color-mix)\([^)]*$/i.test(before);
+  const jsColorKeyContext = /(?:^|[,{]\s*)(?:color|background|backgroundColor|borderColor|outlineColor|fill|stroke|boxShadow|textShadow)\s*[:=]\s*["'`]?[^"'`,}]*/i.test(before);
+
+  return styleContext || cssFunctionContext || jsColorKeyContext;
+}
+
+function isInsideCssAttributeSelector(line, index) {
+  if (index < 0) return false;
+  const before = line.slice(0, index);
+  const lastOpen = before.lastIndexOf('[');
+  if (lastOpen === -1) return false;
+  const lastClose = before.lastIndexOf(']');
+  if (lastClose > lastOpen) return false;
+  const after = line.slice(index);
+  const close = after.indexOf(']');
+  const block = after.indexOf('{');
+  return close !== -1 && (block === -1 || close < block);
+}
+
+function makeDesignFinding(id, filePath, snippet, line = 0, extras = {}) {
+  return { ...finding(id, filePath, snippet, line), ...extras };
+}
+
+function decodeGoogleFamily(value) {
+  const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
+  try {
+    return decodeURIComponent(family);
+  } catch {
+    return family;
+  }
+}
+
+function checkFontStack(stack, filePath, line, designSystem, context) {
+  const primary = primaryFont(stack);
+  if (!primary || isAllowedFont(primary, designSystem)) return [];
+  const display = primary.replace(/\b\w/g, ch => ch.toUpperCase());
+  return [makeDesignFinding(
+    'design-system-font',
+    filePath,
+    `${context}: ${display} is not declared in DESIGN.md typography`,
+    line,
+    { ignoreValue: display },
+  )];
+}
+
+function extractRadiusTokens(value) {
+  return String(value || '')
+    .replace(/\s*\/\s*/g, ' ')
+    .split(/\s+/)
+    .map(token => token.trim())
+    .filter(Boolean);
+}
+
+function checkRadiusValue(value, filePath, line, designSystem, context) {
+  const findings = [];
+  for (const token of extractRadiusTokens(value)) {
+    if (isAllowedRadiusRaw(token, designSystem)) continue;
+    findings.push(makeDesignFinding(
+      'design-system-radius',
+      filePath,
+      `${context}: ${token} is outside the DESIGN.md rounded scale`,
+      line,
+      { ignoreValue: token },
+    ));
+  }
+  return findings;
+}
+
+function checkFontSizeValue(value, filePath, line, designSystem, context) {
+  const token = String(value || '').trim();
+  if (isAllowedFontSizeRaw(token, designSystem)) return [];
+  return [makeDesignFinding(
+    'design-system-font-size',
+    filePath,
+    `${context}: ${token} is off the DESIGN.md type ramp`,
+    line,
+    { ignoreValue: token },
+  )];
+}
+
+function checkSourceDesignSystem(content, filePath, options = {}) {
+  const designSystem = options.designSystem;
+  if (!designSystem?.present) return [];
+
+  const findings = [];
+  const lines = String(content || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+    if (lineLooksCommented(line)) continue;
+
+    if (designSystem.hasFonts) {
+      for (const match of line.matchAll(FONT_DECL_RE)) {
+        findings.push(...checkFontStack(match[1], filePath, lineNum, designSystem, 'font-family'));
+      }
+      for (const match of line.matchAll(FONT_JS_RE)) {
+        findings.push(...checkFontStack(match[1], filePath, lineNum, designSystem, 'fontFamily'));
+      }
+      for (const match of line.matchAll(GOOGLE_FONT_RE)) {
+        const url = match[0];
+        for (const familyMatch of url.matchAll(/[?&]family=([^&]+)/g)) {
+          const font = normalizeFontName(decodeGoogleFamily(familyMatch[1]));
+          if (!font || isAllowedFont(font, designSystem)) continue;
+          const display = decodeGoogleFamily(familyMatch[1]);
+          findings.push(makeDesignFinding(
+            'design-system-font',
+            filePath,
+            `Google Fonts: ${display} is not declared in DESIGN.md typography`,
+            lineNum,
+            { ignoreValue: display },
+          ));
+        }
+      }
+    }
+
+    if (designSystem.hasColors) {
+      for (const match of line.matchAll(CSS_COLOR_RE)) {
+        if (!isProbablyColorLiteral(line, match)) continue;
+        const raw = cssColorLabel(match[0]);
+        if (isAllowedColorRaw(raw, designSystem)) continue;
+        findings.push(makeDesignFinding(
+          'design-system-color',
+          filePath,
+          `Undocumented color ${raw} is outside DESIGN.md colors`,
+          lineNum,
+          { ignoreValue: raw },
+        ));
+      }
+    }
+
+    if (designSystem.hasRadii) {
+      for (const match of line.matchAll(BORDER_RADIUS_RE)) {
+        findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'border-radius'));
+      }
+      for (const match of line.matchAll(BORDER_RADIUS_JS_RE)) {
+        findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'borderRadius'));
+      }
+    }
+
+    if (designSystem.hasFontSizes) {
+      for (const match of line.matchAll(FONT_SIZE_DECL_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'font-size'));
+      }
+      for (const match of line.matchAll(FONT_SIZE_JS_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'fontSize'));
+      }
+      for (const match of line.matchAll(TAILWIND_FONT_SIZE_RE)) {
+        findings.push(...checkFontSizeValue(match[1], filePath, lineNum, designSystem, 'text-[…] class'));
+      }
+    }
+  }
+
+  return dedupeDesignFindings(findings);
+}
+
+function hasDirectText(el) {
+  return Array.from(el.childNodes || []).some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
+}
+
+function sampleText(el) {
+  const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
+  return text ? ` "${text.slice(0, 40)}"` : '';
+}
+
+// Font-size design-system checks are source-scan-only (see checkSourceDesignSystem).
+// Computed font-size cascades and clamp() ramps resolve to off-ramp px in the browser.
+function collectStaticDesignSystemFindings(document, window, filePath, designSystem) {
+  if (!designSystem?.present) return [];
+  const findings = [];
+  const seenFonts = new Set();
+  const seenColors = new Set();
+  const seenRadii = new Set();
+
+  for (const el of document.querySelectorAll('*')) {
+    if (shouldSkipStaticDesignElement(el, window)) continue;
+    const tag = el.tagName?.toLowerCase?.() || 'unknown';
+    const style = window.getComputedStyle(el);
+
+    if (designSystem.hasFonts && hasDirectText(el)) {
+      const font = primaryFont(style.fontFamily || '');
+      if (font && !seenFonts.has(font) && !isAllowedFont(font, designSystem)) {
+        seenFonts.add(font);
+        findings.push(makeDesignFinding(
+          'design-system-font',
+          filePath,
+          `${tag}${sampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
+          0,
+          { ignoreValue: font },
+        ));
+      }
+    }
+
+    if (designSystem.hasColors) {
+      const colorChecks = [];
+      if (hasDirectText(el)) colorChecks.push(['text color', style.color]);
+      if (!isTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
+      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
+          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
+        }
+      }
+      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
+
+      for (const [kind, raw] of colorChecks) {
+        const label = cssColorLabel(raw);
+        if (isAllowedColorRaw(label, designSystem)) continue;
+        const key = `${kind}:${label}`;
+        if (seenColors.has(key)) continue;
+        seenColors.add(key);
+        findings.push(makeDesignFinding(
+          'design-system-color',
+          filePath,
+          `${kind} ${label} on ${tag}${sampleText(el)} is outside DESIGN.md colors`,
+          0,
+          { ignoreValue: label },
+        ));
+      }
+    }
+
+    if (designSystem.hasRadii) {
+      const rawRadius = String(style.borderRadius || '').trim();
+      if (!rawRadius) continue;
+      for (const token of extractRadiusTokens(rawRadius)) {
+        if (isAllowedRadiusRaw(token, designSystem)) continue;
+        if (seenRadii.has(token)) continue;
+        seenRadii.add(token);
+        findings.push(makeDesignFinding(
+          'design-system-radius',
+          filePath,
+          `border-radius ${token} on ${tag}${sampleText(el)} is outside the DESIGN.md rounded scale`,
+          0,
+          { ignoreValue: token },
+        ));
+      }
+    }
+  }
+
+  return findings;
+}
+
+function shouldSkipStaticDesignElement(el, window) {
+  const tag = el.tagName?.toLowerCase?.() || '';
+  if (STATIC_DESIGN_SKIP_TAGS.has(tag)) return true;
+
+  let current = el;
+  while (current) {
+    if (current.getAttribute?.('hidden') !== null || current.getAttribute?.('aria-hidden') === 'true') return true;
+    const style = window.getComputedStyle(current);
+    const display = String(style.display || '').toLowerCase();
+    const visibility = String(style.visibility || '').toLowerCase();
+    if (display === 'none' || visibility === 'hidden' || visibility === 'collapse') return true;
+    current = current.parentElement;
+  }
+  return false;
+}
+
+function isTransparentCss(value) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text || text === 'transparent') return true;
+  const parsed = parseDesignColor(text);
+  return parsed ? (parsed.a ?? 1) <= 0.05 : false;
+}
+
+function canonicalDesignFindingKey(item) {
+  if (!item?.antipattern?.startsWith?.('design-system-')) return null;
+  const value = item.ignoreValue || item.value || '';
+  if (item.antipattern === 'design-system-font') {
+    const context = /google fonts/i.test(item.snippet || '') ? 'google-font' : 'font';
+    const font = normalizeFontName(value);
+    return font ? `${item.antipattern}:${context}:${font}` : null;
+  }
+  if (item.antipattern === 'design-system-color') {
+    const parsed = parseDesignColor(value);
+    if (parsed) return `${item.antipattern}:color:${colorKey(parsed)}`;
+    const label = cssColorLabel(value).toLowerCase();
+    return label ? `${item.antipattern}:color:${label}` : null;
+  }
+  if (item.antipattern === 'design-system-radius') {
+    const px = resolveLengthPx(String(value || '').trim(), 16);
+    if (px != null && Number.isFinite(px)) return `${item.antipattern}:radius:${Math.round(px * 100) / 100}`;
+    const label = String(value || '').trim().toLowerCase();
+    return label ? `${item.antipattern}:radius:${label}` : null;
+  }
+  if (item.antipattern === 'design-system-font-size') {
+    const px = resolveLengthPx(String(value || '').trim(), 16);
+    if (px != null && Number.isFinite(px)) return `${item.antipattern}:font-size:${Math.round(px * 100) / 100}`;
+    const label = String(value || '').trim().toLowerCase();
+    return label ? `${item.antipattern}:font-size:${label}` : null;
+  }
+  return null;
+}
+
+function mergeDesignSystemFindings(...groups) {
+  const out = [];
+  const seen = new Map();
+  for (const group of groups) {
+    for (const item of group || []) {
+      const key = canonicalDesignFindingKey(item);
+      if (key) {
+        if (seen.has(key)) {
+          const existing = out[seen.get(key)];
+          if ((existing.line || 0) <= 0 && (item.line || 0) > 0) existing.line = item.line;
+          continue;
+        }
+        seen.set(key, out.length);
+      }
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+function dedupeDesignFindings(findings) {
+  const out = [];
+  const seen = new Set();
+  for (const item of findings) {
+    const key = [
+      item.antipattern,
+      item.line || 0,
+      normalizeFontName(item.ignoreValue || item.snippet || ''),
+    ].join('\0');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+export {
+  parseFrontmatter,
+  normalizeDesignSystem,
+  loadDesignSystemForCwd,
+  isAllowedFont,
+  isAllowedColorRaw,
+  isAllowedRadiusRaw,
+  isAllowedFontSizeRaw,
+  checkSourceDesignSystem,
+  collectStaticDesignSystemFindings,
+  mergeDesignSystemFindings,
+};

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

@@ -23,6 +23,13 @@ export {
   checkHtmlPatterns,
 } from './rules/checks.mjs';
 export { createDetectorProfile, summarizeDetectorProfile } from './profile/profiler.mjs';
+export {
+  parseFrontmatter as parseDesignFrontmatter,
+  normalizeDesignSystem,
+  loadDesignSystemForCwd,
+  checkSourceDesignSystem,
+  collectStaticDesignSystemFindings,
+} from './design-system.mjs';
 export { detectHtml } from './engines/static-html/detect-html.mjs';
 export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs';
 export { detectText, extractStyleBlocks, extractCSSinJS } from './engines/regex/detect-text.mjs';

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

@@ -7,6 +7,25 @@ import { filterByProviders } from '../../registry/antipatterns.mjs';
 import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
 import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
 
+function serializeDesignSystemForBrowser(designSystem) {
+  if (!designSystem?.present) return null;
+  return {
+    present: true,
+    hasFonts: designSystem.hasFonts === true,
+    allowedFonts: Array.from(designSystem.allowedFonts || []),
+    hasColors: designSystem.hasColors === true,
+    allowedColors: Array.from(designSystem.allowedColorKeys?.values?.() || [])
+      .map(entry => entry?.color)
+      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
+      .map(color => ({ r: color.r, g: color.g, b: color.b })),
+    hasRadii: designSystem.hasRadii === true,
+    allowedRadii: (designSystem.allowedRadii || [])
+      .map(entry => Number(entry?.px))
+      .filter(px => Number.isFinite(px)),
+    hasPillRadius: designSystem.hasPillRadius === true,
+  };
+}
+
 async function runVisualContrastFallback(page, serializedGroups, options, profile, target) {
   if (options?.visualContrast === false) return [];
   const maxCandidates = Number.isFinite(options?.visualContrastMaxCandidates)
@@ -163,17 +182,19 @@ async function detectUrl(url, options = {}) {
     }
 
     // Inject the browser detection script and collect results
+    const browserDesignSystem = serializeDesignSystemForBrowser(options?.designSystem);
     await profileStepAsync(profile, {
       engine: 'browser',
       phase: 'scan',
       ruleId: 'configure-pure-detect',
       target: url,
-    }, () => page.evaluate(() => {
+    }, () => page.evaluate((designSystem) => {
       window.__IMPECCABLE_CONFIG__ = {
         ...(window.__IMPECCABLE_CONFIG__ || {}),
         autoScan: false,
+        ...(designSystem ? { designSystem } : {}),
       };
-    }));
+    }, browserDesignSystem));
     await profileStepAsync(profile, {
       engine: 'browser',
       phase: 'scan',
@@ -192,7 +213,7 @@ async function detectUrl(url, options = {}) {
         return window.impeccableDetect({ decorate: false, serialize: true });
       });
       return serializedGroups.flatMap(({ findings }) =>
-        findings.map(f => ({ id: f.type, snippet: f.detail }))
+        findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '' }))
       );
     });
     const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
@@ -213,7 +234,11 @@ async function detectUrl(url, options = {}) {
       }, () => browser.close());
     }
   }
-  return filterByProviders(results.map(f => finding(f.id, url, f.snippet)), options.providers);
+  return filterByProviders(results.map(f => {
+    const item = finding(f.id, url, f.snippet);
+    if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
+    return item;
+  }), options.providers);
 }
 
 async function createBrowserDetector(options = {}) {

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

@@ -1,5 +1,9 @@
-import { GENERIC_FONTS } from '../../shared/constants.mjs';
+import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
+import { isNeutralColor } from '../../shared/color.mjs';
+import { extractGoogleFontFamilies } from '../../shared/fonts.mjs';
+import { checkSourceDesignSystem } from '../../design-system.mjs';
 import { isFullPage } from '../../shared/page.mjs';
+import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
 import { finding } from '../../findings.mjs';
 import { filterByProviders } from '../../registry/antipatterns.mjs';
 import { profileFindings, profileStep } from '../../profile/profiler.mjs';
@@ -23,11 +27,28 @@ function stripHtmlToText(html) {
     .replace(/\s+/g, ' ');
 }
 
+const PAGE_ANALYZER_EXTS = new Set(['.html', '.htm', '.astro', '.vue', '.svelte']);
+
+function extFromFilePath(filePath) {
+  return filePath ? (filePath.match(/\.\w+$/)?.[0] || '').toLowerCase() : '';
+}
+
+function shouldRunPageAnalyzers(content, filePath) {
+  if (!isFullPage(content)) return false;
+  const ext = extFromFilePath(filePath);
+  return !ext || PAGE_ANALYZER_EXTS.has(ext);
+}
+
+function firstOverusedGoogleFont(text) {
+  return extractGoogleFontFamilies(text).find(f => OVERUSED_FONTS.has(f)) || '';
+}
+
 function isNeutralBorderColor(str) {
-  const m = str.match(/solid\s+(#[0-9a-f]{3,8}|rgba?\([^)]+\)|\w+)/i);
+  const m = str.match(/solid\s+((?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color)\([^)]*\)|#[0-9a-f]{3,8}\b|[a-z]+)/i);
   if (!m) return false;
   const c = m[1].toLowerCase();
   if (['gray', 'grey', 'silver', 'white', 'black', 'transparent', 'currentcolor'].includes(c)) return true;
+  if (/^(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\(/i.test(c)) return isNeutralColor(c);
   const hex = c.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/);
   if (hex) {
     const [r, g, b] = [parseInt(hex[1], 16), parseInt(hex[2], 16), parseInt(hex[3], 16)];
@@ -44,10 +65,10 @@ function isNeutralBorderColor(str) {
 const REGEX_MATCHERS = [
   // --- Side-tab ---
   { id: 'side-tab', regex: /\bborder-[lrse]-(\d+)\b/g,
-    test: (m, line) => { const n = +m[1]; return hasRounded(line) ? n >= 1 : n >= 4; },
+    test: (m, line) => { const n = +m[1]; return hasRounded(line) ? n >= 2 : n >= 4; },
     fmt: (m) => m[0] },
   { id: 'side-tab', regex: /border-(?:left|right)\s*:\s*(\d+)px\s+solid[^;]*/gi,
-    test: (m, line) => { if (isSafeElement(line)) return false; if (isNeutralBorderColor(m[0])) return false; const n = +m[1]; return hasBorderRadius(line) ? n >= 1 : n >= 3; },
+    test: (m, line) => { if (isSafeElement(line)) return false; if (isNeutralBorderColor(m[0])) return false; const n = +m[1]; return hasBorderRadius(line) ? n >= 2 : n >= 3; },
     fmt: (m) => m[0].replace(/\s*;?\s*$/, '') },
   { id: 'side-tab', regex: /border-(?:left|right)-width\s*:\s*(\d+)px/gi,
     test: (m, line) => !isSafeElement(line) && +m[1] >= 3,
@@ -72,9 +93,12 @@ const REGEX_MATCHERS = [
   { id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica|Fraunces|Geist Sans|Geist Mono|Geist|Mona Sans|Plus Jakarta Sans|Space Grotesk|Recoleta|Instrument Sans|Instrument Serif)\b/gi,
     test: () => true,
     fmt: (m) => m[0] },
-  { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat|Fraunces|Plus\+Jakarta\+Sans|Space\+Grotesk|Instrument\+Sans|Instrument\+Serif|Mona\+Sans|Geist)\b/gi,
-    test: () => true,
-    fmt: (m) => `Google Fonts: ${m[1].replace(/\+/g, ' ')}` },
+  { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi,
+    test: (m) => {
+      m.overusedGoogleFont = firstOverusedGoogleFont(m[0]);
+      return Boolean(m.overusedGoogleFont);
+    },
+    fmt: (m) => `Google Fonts: ${m.overusedGoogleFont || firstOverusedGoogleFont(m[0])}` },
   // --- Gradient text ---
   { id: 'gradient-text', regex: /background-clip\s*:\s*text|-webkit-background-clip\s*:\s*text/gi,
     test: (m, line) => /gradient/i.test(line),
@@ -98,9 +122,14 @@ const REGEX_MATCHERS = [
   { id: 'bounce-easing', regex: /\banimate-bounce\b/g,
     test: () => true,
     fmt: () => 'animate-bounce (Tailwind)' },
-  { id: 'bounce-easing', regex: /animation(?:-name)?\s*:\s*[^;]*\b(bounce|elastic|wobble|jiggle|spring)\b/gi,
+  { id: 'bounce-easing', regex: /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi,
     test: () => true,
-    fmt: (m) => m[0] },
+    fmt: (m) => {
+      const token = m[1]
+        .split(/[,\s]+/)
+        .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
+      return `animation: ${token || m[1].trim()}`;
+    } },
   { id: 'bounce-easing', regex: /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g,
     test: (m) => {
       const y1 = parseFloat(m[2]), y2 = parseFloat(m[4]);
@@ -149,10 +178,7 @@ const REGEX_ANALYZERS = [
         if (f && !GENERIC_FONTS.has(f)) fonts.add(f);
       }
     }
-    const gfRe = /fonts\.googleapis\.com\/css2?\?family=([^&"'\s]+)/gi;
-    while ((m = gfRe.exec(content)) !== null) {
-      for (const f of m[1].split('|').map(f => f.split(':')[0].replace(/\+/g, ' ').toLowerCase())) 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');
@@ -422,7 +448,7 @@ const TEXT_CONTENT_ANALYZER_IDS = [
 
 function runTextContentAnalyzers(content, filePath, options = {}) {
   const profile = options?.profile;
-  if (!isFullPage(content)) return [];
+  if (!shouldRunPageAnalyzers(content, filePath)) return [];
   // The 4 text-content analyzers are at indices 3-6 in REGEX_ANALYZERS.
   const findings = [];
   for (let i = 0; i < TEXT_CONTENT_ANALYZER_IDS.length; i++) {
@@ -442,11 +468,11 @@ function detectText(content, filePath, options = {}) {
   const profile = options?.profile;
   const findings = [];
   const lines = content.split('\n');
-  const ext = filePath ? (filePath.match(/\.\w+$/)?.[0] || '').toLowerCase() : '';
+  const ext = extFromFilePath(filePath);
 
   // 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
-  const cssLike = new Set(['.css', '.scss', '.less']);
+  const cssLike = new Set(['.css', '.scss', '.sass', '.less']);
   findings.push(...runRegexMatchers(lines, filePath, 0, cssLike.has(ext) || null, {
     profile,
     phase: 'source',
@@ -486,6 +512,15 @@ function detectText(content, filePath, options = {}) {
     }));
   }
 
+  if (options?.designSystem) {
+    findings.push(...profileFindings(profile, {
+      engine: 'regex',
+      phase: 'source',
+      ruleId: 'design-system',
+      target: filePath,
+    }, () => checkSourceDesignSystem(content, filePath, { designSystem: options.designSystem })));
+  }
+
   // Deduplicate findings (same antipattern + similar snippet, within 2 lines)
   const deduped = [];
   for (const f of findings) {
@@ -498,7 +533,7 @@ function detectText(content, filePath, options = {}) {
   }
 
   // Page-level analyzers only run on full pages
-  if (isFullPage(content)) {
+  if (shouldRunPageAnalyzers(content, filePath)) {
     const analyzerIds = [
       'single-font',
       'flat-type-hierarchy',
@@ -520,7 +555,10 @@ function detectText(content, filePath, options = {}) {
     }
   }
 
-  return filterByProviders(deduped, options?.providers);
+  const byProvider = filterByProviders(deduped, options?.providers);
+  // Inline `impeccable-disable*` waivers travel with the file; honor them unless
+  // explicitly bypassed (`--no-config` / `--no-inline-ignores`).
+  return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, content);
 }
 
 export {

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

@@ -267,7 +267,17 @@ const STATIC_DEFAULT_STYLE = {
   paddingRight: '0px',
   paddingBottom: '0px',
   paddingLeft: '0px',
+  marginTop: '0px',
+  marginRight: '0px',
+  marginBottom: '0px',
+  marginLeft: '0px',
   position: 'static',
+  visibility: 'visible',
+  top: 'auto',
+  right: 'auto',
+  bottom: 'auto',
+  left: 'auto',
+  inset: '',
   display: '',
   overflow: 'visible',
   overflowX: 'visible',
@@ -312,7 +322,17 @@ const STATIC_PROP_MAP = {
   'padding-right': 'paddingRight',
   'padding-bottom': 'paddingBottom',
   'padding-left': 'paddingLeft',
+  'margin-top': 'marginTop',
+  'margin-right': 'marginRight',
+  'margin-bottom': 'marginBottom',
+  'margin-left': 'marginLeft',
   'position': 'position',
+  'visibility': 'visibility',
+  'top': 'top',
+  'right': 'right',
+  'bottom': 'bottom',
+  'left': 'left',
+  'inset': 'inset',
   'display': 'display',
   'overflow': 'overflow',
   'overflow-x': 'overflowX',
@@ -579,6 +599,15 @@ function expandStaticDeclaration(prop, value) {
       ['paddingLeft', vals[3]],
     ];
   }
+  if (p === 'margin') {
+    const vals = expandStaticBoxValues(splitCssTokens(v));
+    return [
+      ['marginTop', vals[0]],
+      ['marginRight', vals[1]],
+      ['marginBottom', vals[2]],
+      ['marginLeft', vals[3]],
+    ];
+  }
   if (p === 'font') return parseStaticFont(v);
   if (p === 'transition') {
     const parsed = parseStaticTransition(v);

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

@@ -2,7 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
+import {
+  checkSourceDesignSystem,
+  collectStaticDesignSystemFindings,
+  mergeDesignSystemFindings,
+} from '../../design-system.mjs';
 import { isFullPage } from '../../shared/page.mjs';
+import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
 import { finding } from '../../findings.mjs';
 import { profileFindings, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
 import {
@@ -168,6 +174,22 @@ async function detectHtml(filePath, options = {}) {
     }
   }
 
+  if (options?.designSystem) {
+    const sourceDesignFindings = profileFindings(profile, {
+      engine: 'static-html',
+      phase: 'source',
+      ruleId: 'design-system',
+      target: filePath,
+    }, () => checkSourceDesignSystem(html, filePath, { designSystem: options.designSystem }));
+    const staticDesignFindings = profileFindings(profile, {
+      engine: 'static-html',
+      phase: 'page',
+      ruleId: 'design-system',
+      target: filePath,
+    }, () => collectStaticDesignSystemFindings(document, window, filePath, options.designSystem));
+    findings.push(...mergeDesignSystemFindings(staticDesignFindings, sourceDesignFindings));
+  }
+
   if (isFullPage(html)) {
     const runPageCheck = (ruleId, callback) => profile
       ? profileFindings(profile, { engine: 'static-html', phase: 'page', ruleId, target: filePath }, callback)
@@ -202,7 +224,11 @@ async function detectHtml(filePath, options = {}) {
     }
   }
 
-  return filterByProviders(findings, options.providers);
+  const byProvider = filterByProviders(findings, options.providers);
+  // Static-HTML findings carry no line number, so only whole-file
+  // `impeccable-disable` directives apply here — exactly the standalone-document
+  // waiver this primitive targets. Bypassed by `--no-config` / `--no-inline-ignores`.
+  return options?.inlineIgnores === false ? byProvider : applyInlineIgnores(byProvider, html);
 }
 
 export { checkStaticPageTypography, STATIC_ELEMENT_RULES, detectHtml };

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

@@ -11,7 +11,7 @@ const SKIP_DIRS = new Set([
 ]);
 
 const SCANNABLE_EXTENSIONS = new Set([
-  '.html', '.htm', '.css', '.scss', '.less',
+  '.html', '.htm', '.css', '.scss', '.sass', '.less',
   '.jsx', '.tsx', '.js', '.ts',
   '.vue', '.svelte', '.astro',
 ]);

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

@@ -21,6 +21,7 @@ const ANTIPATTERNS = [
   {
     id: 'overused-font',
     category: 'slop',
+    scopes: ['type'],
     name: 'Overused font',
     description:
       'Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, and Space Grotesk are used on so many sites they no longer feel distinctive. Each new wave of AI-generated UIs converges on the same handful of faces. Choose a face that gives your interface personality.',
@@ -30,6 +31,7 @@ const ANTIPATTERNS = [
   {
     id: 'single-font',
     category: 'slop',
+    scopes: ['type'],
     name: 'Single font for everything',
     description:
       'Only one font family is used for the entire page. Pair a distinctive display font with a refined body font to create typographic hierarchy.',
@@ -39,6 +41,7 @@ const ANTIPATTERNS = [
   {
     id: 'flat-type-hierarchy',
     category: 'slop',
+    scopes: ['type'],
     name: 'Flat type hierarchy',
     description:
       'Font sizes are too close together — no clear visual hierarchy. Use fewer sizes with more contrast (aim for at least a 1.25 ratio between steps).',
@@ -75,6 +78,7 @@ const ANTIPATTERNS = [
   {
     id: 'nested-cards',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Nested cards',
     description:
       'Cards inside cards create visual noise and excessive depth. Flatten the hierarchy — use spacing, typography, and dividers instead of nesting containers.',
@@ -84,6 +88,7 @@ const ANTIPATTERNS = [
   {
     id: 'monotonous-spacing',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Monotonous spacing',
     description:
       'The same spacing value used everywhere — no rhythm, no variation. Use tight groupings for related items and generous separations between sections.',
@@ -111,6 +116,7 @@ const ANTIPATTERNS = [
   {
     id: 'icon-tile-stack',
     category: 'slop',
+    scopes: ['layout'],
     name: 'Icon tile stacked above heading',
     description:
       'A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container.',
@@ -120,6 +126,7 @@ const ANTIPATTERNS = [
   {
     id: 'italic-serif-display',
     category: 'slop',
+    scopes: ['type'],
     name: 'Italic serif display headline',
     description:
       'Oversized italic serif (Fraunces, Recoleta, Playfair, Newsreader-italic) as the primary hero headline reads as taste in isolation but has become the universal AI-startup landing page hero. Set roman, or move to a non-serif display face. Editorial / magazine register may legitimately want this — judge by context.',
@@ -129,6 +136,7 @@ const ANTIPATTERNS = [
   {
     id: 'hero-eyebrow-chip',
     category: 'slop',
+    scopes: ['type'],
     name: 'Hero eyebrow / pill chip',
     description:
       'A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero. Drop the eyebrow, integrate the kicker into the headline, or run it as a navigation breadcrumb instead.',
@@ -138,6 +146,7 @@ const ANTIPATTERNS = [
   {
     id: 'repeated-section-kickers',
     category: 'slop',
+    scopes: ['type'],
     severity: 'advisory',
     name: 'Repeated section kicker labels',
     description:
@@ -148,6 +157,7 @@ const ANTIPATTERNS = [
   {
     id: 'numbered-section-markers',
     category: 'slop',
+    scopes: ['layout'],
     severity: 'advisory',
     name: 'Numbered section markers (01 / 02 / 03)',
     description:
@@ -185,6 +195,7 @@ const ANTIPATTERNS = [
   {
     id: 'oversized-h1',
     category: 'slop',
+    scopes: ['type'],
     name: 'Oversized hero headline',
     description:
       'A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy.',
@@ -194,6 +205,7 @@ const ANTIPATTERNS = [
   {
     id: 'extreme-negative-tracking',
     category: 'slop',
+    scopes: ['type'],
     name: 'Crushed letter spacing',
     description:
       'Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively.',
@@ -239,6 +251,7 @@ const ANTIPATTERNS = [
   {
     id: 'line-length',
     category: 'quality',
+    scopes: ['type', 'layout'],
     name: 'Line length too long',
     description:
       'Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.',
@@ -248,6 +261,7 @@ const ANTIPATTERNS = [
   {
     id: 'cramped-padding',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Cramped padding',
     description:
       'Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.',
@@ -257,6 +271,7 @@ const ANTIPATTERNS = [
   {
     id: 'body-text-viewport-edge',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Body text touching viewport edge',
     description:
       'Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto.',
@@ -264,6 +279,7 @@ const ANTIPATTERNS = [
   {
     id: 'tight-leading',
     category: 'quality',
+    scopes: ['type'],
     name: 'Tight line height',
     description:
       'Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.',
@@ -271,6 +287,7 @@ const ANTIPATTERNS = [
   {
     id: 'skipped-heading',
     category: 'quality',
+    scopes: ['type'],
     name: 'Skipped heading level',
     description:
       'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
@@ -278,6 +295,7 @@ const ANTIPATTERNS = [
   {
     id: 'justified-text',
     category: 'quality',
+    scopes: ['type'],
     name: 'Justified text',
     description:
       'Justified text without hyphenation creates uneven word spacing ("rivers of white"). Use text-align: left for body text, or enable hyphens: auto if you must justify.',
@@ -285,6 +303,7 @@ const ANTIPATTERNS = [
   {
     id: 'tiny-text',
     category: 'quality',
+    scopes: ['type'],
     name: 'Tiny body text',
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
@@ -292,6 +311,7 @@ const ANTIPATTERNS = [
   {
     id: 'all-caps-body',
     category: 'quality',
+    scopes: ['type'],
     name: 'All-caps body text',
     description:
       'Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.',
@@ -301,6 +321,7 @@ const ANTIPATTERNS = [
   {
     id: 'wide-tracking',
     category: 'quality',
+    scopes: ['type'],
     name: 'Wide letter spacing on body text',
     description:
       'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
@@ -308,6 +329,7 @@ const ANTIPATTERNS = [
   {
     id: 'text-overflow',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Content overflowing its container',
     description:
       'Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance.',
@@ -317,12 +339,54 @@ const ANTIPATTERNS = [
   {
     id: 'clipped-overflow-container',
     category: 'quality',
+    scopes: ['layout'],
     name: 'Positioned child clipped by overflow container',
     description:
       'A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip.',
     skillSection: 'Layout & Space',
     skillGuideline: 'overflow container clipping positioned children',
   },
+  {
+    id: 'design-system-font',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Font outside DESIGN.md',
+    description:
+      'A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition.',
+    skillSection: 'Typography',
+    skillGuideline: 'font family outside the project design system',
+  },
+  {
+    id: 'design-system-color',
+    category: 'quality',
+    severity: 'advisory',
+    name: 'Color outside DESIGN.md',
+    description:
+      'A literal color is outside the DESIGN.md palette and sidecar tonal ramps. This may be legitimate, but it should be an intentional design-system addition rather than drift.',
+    skillSection: 'Color & Contrast',
+    skillGuideline: 'literal color outside the project design system',
+  },
+  {
+    id: 'design-system-radius',
+    category: 'quality',
+    severity: 'advisory',
+    name: 'Radius outside DESIGN.md',
+    description:
+      'A border-radius value is outside the DESIGN.md rounded scale. Use a documented radius token or update the design system if the new shape is intentional.',
+    skillSection: 'Visual Details',
+    skillGuideline: 'border radius outside the project design system',
+  },
+  {
+    id: 'design-system-font-size',
+    category: 'quality',
+    severity: 'advisory',
+    scopes: ['type'],
+    name: 'Font size outside DESIGN.md',
+    description:
+      'A literal font-size is off the type ramp documented in DESIGN.md typography. Use a documented size step or update the design system if the new step is intentional.',
+    skillSection: 'Typography',
+    skillGuideline: 'font size outside the project design system',
+  },
 
   // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
   {
@@ -347,6 +411,17 @@ const ANTIPATTERNS = [
     skillSection: 'Visual Details',
     skillGuideline: 'repeating-gradient decorative stripes',
   },
+  {
+    id: 'codex-grid-background',
+    category: 'slop',
+    severity: 'advisory',
+    gated: 'gpt',
+    name: 'Decorative grid-line background',
+    description:
+      'A two-axis grid drawn with hairline linear-gradient layers ("1px, transparent 1px" on both axes) is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
+    skillSection: 'Visual Details',
+    skillGuideline: 'two-axis grid-line gradient background',
+  },
   {
     id: 'theater-slop-phrase',
     category: 'slop',
@@ -408,12 +483,32 @@ function filterByProviders(findings, providers = []) {
   });
 }
 
+
+// Set of scope tags rules can declare (e.g. 'type', 'layout'). Used by the
+// CLI --scope flag to narrow output to one design domain.
+const RULE_SCOPES = new Set(
+  ANTIPATTERNS.flatMap(rule => rule.scopes || []),
+);
+
+// Keep only findings whose rule declares at least one of the requested
+// scopes. An empty scope list means no filtering (default CLI behavior).
+function filterByScopes(findings, scopes = []) {
+  if (!scopes || scopes.length === 0) return findings;
+  const enabled = new Set(scopes);
+  return findings.filter(f => {
+    const rule = getAntipattern(f.antipattern);
+    return (rule?.scopes || []).some(scope => enabled.has(scope));
+  });
+}
+
 export {
   ANTIPATTERNS,
+  RULE_SCOPES,
   RULE_ENGINE_SUPPORT,
   GATED_PROVIDERS,
   getAntipattern,
   getRulesForCategory,
   getRuleEngineSupport,
   filterByProviders,
+  filterByScopes,
 };

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

@@ -18,6 +18,7 @@ import {
   parseRgb,
   relativeLuminance,
 } from '../shared/color.mjs';
+import { extractGoogleFontFamilies } from '../shared/fonts.mjs';
 
 const DETECTOR_IS_BROWSER = typeof window !== 'undefined';
 
@@ -514,9 +515,13 @@ function checkHtmlPatterns(html) {
   // --- Motion ---
 
   // Bounce/elastic animation names
-  const bounceRe = /animation(?:-name)?\s*:\s*[^;]*\b(bounce|elastic|wobble|jiggle|spring)\b/gi;
-  if (bounceRe.test(html)) {
-    findings.push({ id: 'bounce-easing', snippet: 'Bounce/elastic animation in CSS' });
+  const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
+  const bounceMatch = bounceRe.exec(html);
+  if (bounceMatch) {
+    const animationToken = bounceMatch[1]
+      .split(/[,\s]+/)
+      .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
+    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}` });
   }
 
   // Overshoot cubic-bezier
@@ -569,6 +574,42 @@ function checkHtmlPatterns(html) {
     findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
   }
 
+  // --- Provider tells (gated): two-axis grid-line background (Codex/GPT) ---
+  // The Codex grid tell is two hairline `linear-gradient(... <color> 1px,
+  // transparent 1px)` layers (one per axis) tiled by a repeating
+  // `background-size` cell. Both signals must co-occur in the SAME style block
+  // (a CSS rule body or one inline `style="..."`): two hairline stops WITHOUT a
+  // tiling background-size is a fixed crosshair, not a grid, and a single
+  // hairline is a legitimate ruled line. Scoping to one block also stops
+  // unrelated single-axis rules on separate elements from adding up across the
+  // page. Count hairlines only inside `background`/`background-image` values so
+  // a hairline in an unrelated property (mask-image, border-image) can't stand
+  // 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 hairlineRe = /\b\d{1,3}px\s*,\s*transparent\s+\d{1,3}px/gi;
+    const gridSizeRe = /background-size\s*:[^;{}"']*\b\d{1,3}px\b/i;
+    const bgDeclRe = /\bbackground(?:-image)?\s*:\s*([^;{}"']*)/gi;
+    const blockRe = /\{([^{}]*)\}|style\s*=\s*"([^"]*)"|style\s*=\s*'([^']*)'/gi;
+    let blk;
+    while ((blk = blockRe.exec(html)) !== null) {
+      const block = blk[1] || blk[2] || blk[3] || '';
+      if (!gridSizeRe.test(block)) continue;
+      let hairlineCount = 0;
+      let bm;
+      bgDeclRe.lastIndex = 0;
+      while ((bm = bgDeclRe.exec(block)) !== null) {
+        const stops = bm[1].match(hairlineRe);
+        if (stops) hairlineCount += stops.length;
+      }
+      if (hairlineCount >= 2) {
+        findings.push({ id: 'codex-grid-background', snippet: 'two-axis grid-line gradient background' });
+        break;
+      }
+    }
+  }
+
   // --- Provider tells (gated): "X theater" framing copy (GPT) ---
   // Lives here (regex-on-HTML) rather than in the text-content analyzers so it
   // runs in the bundled browser path too, not just the CLI/static path.
@@ -974,11 +1015,16 @@ function parseAnyColor(s) {
   // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
   // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
   // Match L (with optional %), then C and H separated permissively.
-  m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i);
+  m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
   if (m) {
     const Lnum = parseFloat(m[1]);
     const L = m[2] === '%' ? Lnum / 100 : Lnum;
-    return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
+    const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
+    if (m[5] !== undefined) {
+      const alpha = parseFloat(m[5]);
+      rgb.a = m[6] === '%' ? alpha / 100 : alpha;
+    }
+    return rgb;
   }
   return null;
 }
@@ -1007,9 +1053,19 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
   '[role="navigation"]',
   '[aria-label*="breadcrumb" i]',
   '[class*="breadcrumb" i]',
+  '[aria-hidden="true"]',
   '[data-impeccable-allow-kickers]',
 ].join(',');
 
+const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
+  'article',
+  'button',
+  'a',
+  'li',
+  '[role="listitem"]',
+  '[role="option"]',
+].join(',');
+
 function cleanInlineText(el) {
   return [...el.childNodes]
     .filter(n => n.nodeType === 3)
@@ -1019,6 +1075,11 @@ function cleanInlineText(el) {
     .trim();
 }
 
+function isRepeatedKickerCardContext(heading, kicker) {
+  const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
+  return Boolean(item && (!item.contains || item.contains(kicker)));
+}
+
 function isRepeatedKickerCandidate(opts) {
   const {
     headingTag,
@@ -1032,6 +1093,7 @@ function isRepeatedKickerCandidate(opts) {
   } = opts;
   if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
   if (!headingText || headingText.length < 3) return false;
+  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
   if (!(headingFontSize >= 20)) return false;
   if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
   if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
@@ -1053,6 +1115,7 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
     if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
     const kicker = heading.previousElementSibling;
     if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
+    if (isRepeatedKickerCardContext(heading, kicker)) continue;
 
     const headingStyle = getStyle(heading);
     const kickerStyle = getStyle(kicker);
@@ -1235,6 +1298,84 @@ function resolveLengthPx(value, fontSizePx) {
   return num * fontSizePx;
 }
 
+function cssColorIsTransparent(value) {
+  if (!value) return true;
+  const str = String(value).trim().toLowerCase();
+  if (!str || str === 'transparent' || str === 'rgba(0, 0, 0, 0)') return true;
+  const parsed = parseAnyColor(str);
+  if (parsed) return (parsed.a ?? 1) <= 0.05;
+  return /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(str);
+}
+
+function colorsNearlyMatch(a, b) {
+  const ca = parseAnyColor(a);
+  const cb = parseAnyColor(b);
+  if (!ca || !cb) return false;
+  const alphaDelta = Math.abs((ca.a ?? 1) - (cb.a ?? 1));
+  const channelDelta = Math.max(
+    Math.abs(ca.r - cb.r),
+    Math.abs(ca.g - cb.g),
+    Math.abs(ca.b - cb.b),
+  );
+  return alphaDelta <= 0.03 && channelDelta <= 3;
+}
+
+function getComputedStyleFor(win, el) {
+  if (win && typeof win.getComputedStyle === 'function') {
+    try { return win.getComputedStyle(el); } catch {}
+  }
+  if (typeof getComputedStyle === 'function') {
+    try { return getComputedStyle(el); } catch {}
+  }
+  return null;
+}
+
+function hasVisibleBackgroundBoundary(style, el, win) {
+  const bg = style?.backgroundColor || '';
+  if (cssColorIsTransparent(bg)) return false;
+
+  let parent = el?.parentElement || null;
+  while (parent) {
+    const parentStyle = getComputedStyleFor(win, parent);
+    const parentBg = parentStyle?.backgroundColor || '';
+    if (!cssColorIsTransparent(parentBg)) {
+      return !colorsNearlyMatch(bg, parentBg);
+    }
+    parent = parent.parentElement;
+  }
+
+  return true;
+}
+
+const TEXT_EDGE_TAGS = new Set(['A', 'BUTTON', 'CODE', 'DD', 'DT', 'FIGCAPTION', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'P', 'PRE', 'SPAN', 'TD', 'TH']);
+
+function hasMeaningfulDirectText(node) {
+  if (!node?.childNodes) return false;
+  for (const child of node.childNodes) {
+    if (child.nodeType === 3 && child.textContent.trim().length > 4) return true;
+  }
+  return false;
+}
+
+function textDescendantsFlushSides(el, rect) {
+  const flush = { top: false, right: false, bottom: false, left: false };
+  if (!rect || !el?.querySelectorAll) return flush;
+  const TEXT_EDGE_THRESHOLD = 4;
+  const candidates = el.querySelectorAll('a, button, code, dd, dt, figcaption, h1, h2, h3, h4, h5, h6, li, p, pre, span, td, th');
+  for (const node of candidates) {
+    if (!TEXT_EDGE_TAGS.has(node.tagName) || !hasMeaningfulDirectText(node)) continue;
+    let nodeRect = null;
+    try { nodeRect = node.getBoundingClientRect(); } catch {}
+    if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
+    if (nodeRect.bottom < rect.top || nodeRect.top > rect.bottom || nodeRect.right < rect.left || nodeRect.left > rect.right) continue;
+    if (nodeRect.top - rect.top <= TEXT_EDGE_THRESHOLD) flush.top = true;
+    if (rect.right - nodeRect.right <= TEXT_EDGE_THRESHOLD) flush.right = true;
+    if (rect.bottom - nodeRect.bottom <= TEXT_EDGE_THRESHOLD) flush.bottom = true;
+    if (nodeRect.left - rect.left <= TEXT_EDGE_THRESHOLD) flush.left = true;
+  }
+  return flush;
+}
+
 // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
 // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
 // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -1264,7 +1405,8 @@ function checkQuality(opts) {
   // font-size — bigger text demands proportionally more padding.
   //   vertical:   max(4px, fontSize × 0.3)
   //   horizontal: max(8px, fontSize × 0.5)
-  if (rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
+  const isInlineCode = tag === 'code' && !(el.closest && el.closest('pre'));
+  if (!isInlineCode && rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
     const borders = {
       top: parseFloat(style.borderTopWidth) || 0,
       right: parseFloat(style.borderRightWidth) || 0,
@@ -1272,7 +1414,7 @@ function checkQuality(opts) {
       left: parseFloat(style.borderLeftWidth) || 0,
     };
     const borderCount = Object.values(borders).filter(w => w > 0).length;
-    const hasBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)';
+    const hasBg = hasVisibleBackgroundBoundary(style, el, win);
     if (borderCount >= 2 || hasBg) {
       const vPads = [], hPads = [];
       if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0);
@@ -1320,10 +1462,6 @@ function checkQuality(opts) {
       !['fixed', 'absolute'].includes(elPosition) &&
       el.children && el.children.length > 0
     ) {
-      const isTransparent = (c) =>
-        !c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)' ||
-        /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(c);
-
       const borderW = {
         top:    parseFloat(style.borderTopWidth)    || 0,
         right:  parseFloat(style.borderRightWidth)  || 0,
@@ -1331,10 +1469,10 @@ function checkQuality(opts) {
         left:   parseFloat(style.borderLeftWidth)   || 0,
       };
       const borderVisible = {
-        top:    borderW.top    > 0 && !isTransparent(style.borderTopColor),
-        right:  borderW.right  > 0 && !isTransparent(style.borderRightColor),
-        bottom: borderW.bottom > 0 && !isTransparent(style.borderBottomColor),
-        left:   borderW.left   > 0 && !isTransparent(style.borderLeftColor),
+        top:    borderW.top    > 0 && !cssColorIsTransparent(style.borderTopColor),
+        right:  borderW.right  > 0 && !cssColorIsTransparent(style.borderRightColor),
+        bottom: borderW.bottom > 0 && !cssColorIsTransparent(style.borderBottomColor),
+        left:   borderW.left   > 0 && !cssColorIsTransparent(style.borderLeftColor),
       };
       // Outline detection. jsdom decomposes `border` shorthand into
       // border{Top,…}Width/Color but does NOT decompose `outline` —
@@ -1354,8 +1492,8 @@ function checkQuality(opts) {
           if (cMatch) outlineColorVal = cMatch[1];
         }
       }
-      const outlineVisible = outlineW > 0 && !isTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
-      const bgVisible = !isTransparent(style.backgroundColor);
+      const outlineVisible = outlineW > 0 && !cssColorIsTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
+      const bgVisible = hasVisibleBackgroundBoundary(style, el, win);
 
       const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
       if (anyVisible) {
@@ -1383,13 +1521,7 @@ function checkQuality(opts) {
         const CHILD_INSULATE_THRESHOLD = 4;
         const childrenInsulate = { top: false, right: false, bottom: false, left: false };
         for (const child of el.children) {
-          let childStyle = null;
-          if (win && typeof win.getComputedStyle === 'function') {
-            try { childStyle = win.getComputedStyle(child); } catch {}
-          }
-          if (!childStyle && typeof getComputedStyle === 'function') {
-            try { childStyle = getComputedStyle(child); } catch {}
-          }
+          let childStyle = getComputedStyleFor(win, child);
           if (!childStyle) continue;
           const childPad = {
             top:    resolveLengthPx(childStyle.paddingTop,    fontSize) ?? 0,
@@ -1397,15 +1529,37 @@ function checkQuality(opts) {
             bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
             left:   resolveLengthPx(childStyle.paddingLeft,   fontSize) ?? 0,
           };
+          const childMargin = {
+            top:    resolveLengthPx(childStyle.marginTop,    fontSize) ?? 0,
+            right:  resolveLengthPx(childStyle.marginRight,  fontSize) ?? 0,
+            bottom: resolveLengthPx(childStyle.marginBottom, fontSize) ?? 0,
+            left:   resolveLengthPx(childStyle.marginLeft,   fontSize) ?? 0,
+          };
+          if (rect && typeof child.getBoundingClientRect === 'function') {
+            try {
+              const childRect = child.getBoundingClientRect();
+              if (childRect && childRect.width > 0 && childRect.height > 0) {
+                if (childRect.top - rect.top >= CHILD_INSULATE_THRESHOLD) childrenInsulate.top = true;
+                if (rect.right - childRect.right >= CHILD_INSULATE_THRESHOLD) childrenInsulate.right = true;
+                if (rect.bottom - childRect.bottom >= CHILD_INSULATE_THRESHOLD) childrenInsulate.bottom = true;
+                if (childRect.left - rect.left >= CHILD_INSULATE_THRESHOLD) childrenInsulate.left = true;
+              }
+            } catch {}
+          }
           for (const s of ['top', 'right', 'bottom', 'left']) {
-            if (childPad[s] >= CHILD_INSULATE_THRESHOLD) childrenInsulate[s] = true;
+            if (childPad[s] >= CHILD_INSULATE_THRESHOLD || childMargin[s] >= CHILD_INSULATE_THRESHOLD) {
+              childrenInsulate[s] = true;
+            }
           }
         }
 
+        const textFlush = rect ? textDescendantsFlushSides(el, rect) : null;
+        const fullBleedBgBand = rect && viewportWidth > 0 && rect.width >= viewportWidth * 0.94 && bgVisible && !outlineVisible;
         const flushSides = [];
         for (const side of ['top', 'right', 'bottom', 'left']) {
-          const sideBounded = borderVisible[side] || outlineVisible || bgVisible;
-          if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side]) {
+          const bgBoundsSide = bgVisible && !(fullBleedBgBand && (side === 'left' || side === 'right'));
+          const sideBounded = borderVisible[side] || outlineVisible || bgBoundsSide;
+          if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side] && (!textFlush || textFlush[side])) {
             flushSides.push(side);
           }
         }
@@ -1499,7 +1653,7 @@ function checkQuality(opts) {
   // Only flag actual body content, not UI labels (buttons, tabs, badges, captions, footer text, etc.)
   if (hasDirectText && textLen > 20 && fontSize < 12) {
     const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
-    const inUIContext = el.closest && el.closest('button, a, label, summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="label" i], [class*="caption" i]');
+    const inUIContext = el.closest && el.closest('button, a, label, summary, pre, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [aria-hidden="true"], [class*="badge" i], [class*="caption" i], [class*="chip" i], [class*="code" i], [class*="console" i], [class*="diff" i], [class*="label" i], [class*="meta" i], [class*="mock" i], [class*="pill" i], [class*="preview" i], [class*="tag" i], [class*="terminal" i], [class*="writes" i]');
     const isUppercase = style.textTransform === 'uppercase';
     if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
       findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
@@ -1919,14 +2073,9 @@ function checkPageTypography(doc, win) {
 
   // Check Google Fonts links in HTML
   const html = doc.documentElement?.outerHTML || '';
-  const gfRe = /fonts\.googleapis\.com\/css2?\?family=([^&"'\s]+)/gi;
-  let m;
-  while ((m = gfRe.exec(html)) !== null) {
-    const families = m[1].split('|').map(f => f.split(':')[0].replace(/\+/g, ' ').toLowerCase());
-    for (const f of families) {
-      fonts.add(f);
-      if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
-    }
+  for (const f of extractGoogleFontFamilies(html)) {
+    fonts.add(f);
+    if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
   }
 
   // Also parse raw HTML/style content for font-family (jsdom may not expose all via CSSOM)
@@ -2107,17 +2256,28 @@ function checkCreamPalette(doc, win) {
 }
 
 // ─── Oversized hero headline ────────────────────────────────────────────────
-// Fires when a *long* headline is set at display size, so a full sentence ends
-// up dominating the viewport. A punchy one- or two-word headline at the same
-// size is a legitimate stylistic choice and must pass — length, not size
-// alone, is the tell.
+// Fires when a *long* headline is set at display size and actually dominates
+// the viewport. A punchy one- or two-word headline at the same size is a
+// legitimate stylistic choice, and a large-but-contained two-line hero should
+// pass too — length and viewport share together are the tell.
 const OVERSIZED_H1_FONT_PX = 72;
 const OVERSIZED_H1_MIN_CHARS = 40;
-function checkOversizedH1({ tag, fontSize, headingText }) {
+const OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO = 0.28;
+const OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO = 0.25;
+function checkOversizedH1({ tag, fontSize, headingText, rect = null, viewportWidth = 0, viewportHeight = 0 }) {
   if (tag !== 'h1') return [];
   const textLen = headingText.length;
   if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
-    return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars "${headingText.slice(0, 60)}"` }];
+    let viewportDetail = '';
+    if (rect && viewportWidth > 0 && viewportHeight > 0) {
+      const heightRatio = rect.height / viewportHeight;
+      const areaRatio = (rect.width * rect.height) / (viewportWidth * viewportHeight);
+      const dominatesViewport = heightRatio >= OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO
+        || areaRatio >= OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO;
+      if (!dominatesViewport) return [];
+      viewportDetail = `, ${Math.round(heightRatio * 100)}vh`;
+    }
+    return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars${viewportDetail} "${headingText.slice(0, 60)}"` }];
   }
   return [];
 }
@@ -2135,31 +2295,54 @@ function checkElementOversizedH1DOM(el) {
   const style = getComputedStyle(el);
   const fontSize = parseFloat(style.fontSize) || 0;
   const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
-  return checkOversizedH1({ tag, fontSize, headingText });
+  const rect = el.getBoundingClientRect();
+  const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
+  const viewportHeight = (typeof window !== 'undefined' ? window.innerHeight : 0) || 0;
+  return checkOversizedH1({ tag, fontSize, headingText, rect, viewportWidth, viewportHeight });
 }
 
 // ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
-function shadowMaxBlurPx(boxShadow) {
+const CSS_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\([^)]*\)|#[0-9a-fA-F]{3,8}\b|\b(?:black|white|transparent|currentcolor)\b/gi;
+
+function shadowLayerAlpha(layer) {
+  CSS_COLOR_TOKEN_RE.lastIndex = 0;
+  const match = CSS_COLOR_TOKEN_RE.exec(layer);
+  if (!match) return 1;
+  if (match[0].toLowerCase() === 'transparent') return 0;
+  const parsed = parseAnyColor(match[0]);
+  return parsed ? (parsed.a ?? 1) : 1;
+}
+
+function shadowMaxBlurPx(boxShadow, { minAlpha = 0 } = {}) {
   if (!boxShadow || boxShadow === 'none') return 0;
   let maxBlur = 0;
   // Split into layers on commas not inside parentheses (rgba(...) etc.).
   for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
+    if (shadowLayerAlpha(layer) < minAlpha) continue;
     // Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
     // ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
     // unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
     // both reduce to the same numbers here.
-    const cleaned = layer.replace(/rgba?\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]+|\b[a-z]+\b/gi, ' ');
+    const cleaned = layer.replace(CSS_COLOR_TOKEN_RE, ' ').replace(/\b[a-z]+\b/gi, ' ');
     const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
     if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
   }
   return maxBlur;
 }
 
-function checkGptThinBorderWideShadow({ borderWidths, boxShadow }) {
-  const maxBorder = Math.max(0, ...borderWidths);
-  const hasThinBorder = maxBorder > 0 && maxBorder <= 1.5;
-  const blur = shadowMaxBlurPx(boxShadow);
-  if (hasThinBorder && blur >= 16) {
+function cssColorAlpha(value) {
+  if (cssColorIsTransparent(value)) return 0;
+  const parsed = parseAnyColor(value);
+  return parsed ? (parsed.a ?? 1) : 1;
+}
+
+function checkGptThinBorderWideShadow({ borderWidths, borderColors, boxShadow }) {
+  const visibleThinBorders = borderWidths
+    .map((width, index) => ({ width, alpha: cssColorAlpha(borderColors?.[index] || '') }))
+    .filter(({ width, alpha }) => width > 0 && width <= 1.5 && alpha >= 0.28);
+  const maxBorder = Math.max(0, ...visibleThinBorders.map(({ width }) => width));
+  const blur = shadowMaxBlurPx(boxShadow, { minAlpha: 0.12 });
+  if (visibleThinBorders.length >= 2 && blur >= 16) {
     return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
   }
   return [];
@@ -2174,13 +2357,22 @@ function borderWidthsFromStyle(style) {
   ];
 }
 
+function borderColorsFromStyle(style) {
+  return [
+    style.borderTopColor || '',
+    style.borderRightColor || '',
+    style.borderBottomColor || '',
+    style.borderLeftColor || '',
+  ];
+}
+
 function checkElementGptBorderShadow(el, style) {
-  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
+  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
 }
 
 function checkElementGptBorderShadowDOM(el) {
   const style = getComputedStyle(el);
-  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
+  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
 }
 
 // ─── Clipped overflow container ───────────────────────────────────────────────
@@ -2193,17 +2385,131 @@ function classSelector(el) {
   return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
 }
 
+function positionedChildIsDecorative(child) {
+  if (!child || typeof child.getAttribute !== 'function') return false;
+  if (child.closest?.('[aria-hidden="true"]')) return true;
+  const role = (child.getAttribute('role') || '').toLowerCase();
+  if (role === 'none' || role === 'presentation') return true;
+  const tag = child.tagName ? child.tagName.toLowerCase() : '';
+  if (['img', 'svg', 'canvas', 'video'].includes(tag)) return true;
+  const ident = `${child.getAttribute('class') || ''} ${child.getAttribute('id') || ''}`;
+  if (
+    /\b(art|bg|background|badge|blob|crop|decor|dot|glow|grain|image|mask|ornament|overlay|photo|scrim|shadow|shine|texture)\b/i.test(ident) &&
+    !positionedChildHasSubstantiveContent(child)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+const POSITIONED_CHILD_INTERACTIVE_SELECTOR = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'summary',
+  'textarea',
+  '[tabindex]:not([tabindex="-1"])',
+  '[role="button"]',
+  '[role="dialog"]',
+  '[role="link"]',
+  '[role="listbox"]',
+  '[role="menu"]',
+  '[role="menuitem"]',
+  '[role="option"]',
+  '[role="tooltip"]',
+].join(',');
+
+function positionedChildHasSubstantiveContent(child) {
+  const text = (child.textContent || '').replace(/\s+/g, ' ').trim();
+  if (text.length > 0) return true;
+  if (typeof child.matches === 'function') {
+    try {
+      if (child.matches(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
+    } catch {}
+  }
+  if (typeof child.querySelector === 'function') {
+    try {
+      if (child.querySelector(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
+    } catch {}
+  }
+  return false;
+}
+
+function clippingContainerIsIntentionalViewport(el) {
+  if (!el || typeof el.getAttribute !== 'function') return false;
+  const roleDescription = (el.getAttribute('aria-roledescription') || '').toLowerCase();
+  if (/\b(carousel|slider)\b/.test(roleDescription)) return true;
+  const ident = `${el.getAttribute('class') || ''} ${el.getAttribute('id') || ''}`.toLowerCase();
+  return /\b(carousel|comparison|compare|fisheye|marquee|preview|scroller|slider|slideshow|split|viewport)\b/.test(ident) ||
+    /\b(demo-area|demo-stage|demo-viewport)\b/.test(ident);
+}
+
+function elementRect(el) {
+  if (!el || typeof el.getBoundingClientRect !== 'function') return null;
+  try {
+    const rect = el.getBoundingClientRect();
+    if (!rect) return null;
+    const values = [rect.top, rect.right, rect.bottom, rect.left, rect.width, rect.height];
+    if (!values.every(Number.isFinite)) return null;
+    if (rect.width <= 0 && rect.height <= 0) return null;
+    return rect;
+  } catch {
+    return null;
+  }
+}
+
+function positionedStyleImpliesEscape(style) {
+  const values = [
+    style.top,
+    style.right,
+    style.bottom,
+    style.left,
+    style.inset,
+    style.insetBlock,
+    style.insetInline,
+    style.insetBlockStart,
+    style.insetBlockEnd,
+    style.insetInlineStart,
+    style.insetInlineEnd,
+  ].filter(Boolean).map(value => String(value).trim().toLowerCase());
+  for (const value of values) {
+    if (/(^|[\s(])-+(?:\d|\.)/.test(value)) return true;
+    if (/(^|[\s(])100(?:\.0+)?%/.test(value)) return true;
+  }
+  return false;
+}
+
+function positionedChildEscapesClip(el, child, clipX, clipY) {
+  const parentRect = elementRect(el);
+  const childRect = elementRect(child);
+  if (!parentRect || !childRect) return null;
+  const threshold = 2;
+  return Boolean(
+    (clipX && (childRect.left < parentRect.left - threshold || childRect.right > parentRect.right + threshold)) ||
+    (clipY && (childRect.top < parentRect.top - threshold || childRect.bottom > parentRect.bottom + threshold))
+  );
+}
+
 function checkClippedOverflow(el, style, getStyle) {
   const clips = (v) => v === 'hidden' || v === 'clip';
   const scrolls = (v) => v === 'auto' || v === 'scroll';
   const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
-  const anyClip = clips(ox) || clips(oy) || clips(ov);
+  const clipX = clips(ox) || clips(ov);
+  const clipY = clips(oy) || clips(ov);
+  const anyClip = clipX || clipY;
   const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
   if (!anyClip || anyScroll) return [];
+  if (clippingContainerIsIntentionalViewport(el)) return [];
   if (!el.querySelectorAll) return [];
   for (const child of el.querySelectorAll('*')) {
-    const pos = (getStyle(child).position) || '';
+    const childStyle = getStyle(child);
+    const pos = childStyle.position || '';
     if (pos === 'absolute' || pos === 'fixed') {
+      if (positionedChildIsDecorative(child)) continue;
+      const escapes = positionedChildEscapesClip(el, child, clipX, clipY);
+      if (escapes === false) continue;
+      if (escapes === null && !positionedStyleImpliesEscape(childStyle)) continue;
       return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
     }
   }
@@ -2222,14 +2528,94 @@ function checkElementClippedOverflowDOM(el) {
 // ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
 const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
 
+function metricLengthPx(value, fontSizePx = 16) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string') return null;
+  return resolveLengthPx(value, fontSizePx);
+}
+
+function firstMetricLengthPx(fontSizePx, ...values) {
+  for (const value of values) {
+    const parsed = metricLengthPx(value, fontSizePx);
+    if (parsed !== null) return parsed;
+  }
+  return null;
+}
+
+function expandBoxShorthand(parts) {
+  if (parts.length === 1) return [parts[0], parts[0], parts[0], parts[0]];
+  if (parts.length === 2) return [parts[0], parts[1], parts[0], parts[1]];
+  if (parts.length === 3) return [parts[0], parts[1], parts[2], parts[1]];
+  return [parts[0], parts[1], parts[2], parts[3]];
+}
+
+function clippedByInset(clipPath) {
+  const match = String(clipPath || '').trim().toLowerCase().match(/^inset\s*\(([^)]*)\)$/);
+  if (!match) return false;
+  const beforeRound = match[1].split(/\s+round\s+/)[0].trim();
+  if (!beforeRound) return false;
+  const values = expandBoxShorthand(beforeRound.split(/\s+/).slice(0, 4));
+  const percents = values.map(value => String(value).trim().match(/^(-?\d+(?:\.\d+)?)%$/));
+  if (percents.some(match => !match)) return false;
+  const [top, right, bottom, left] = percents.map(match => parseFloat(match[1]));
+  return top + bottom >= 100 || left + right >= 100;
+}
+
+function clippedByRect(clip) {
+  const match = String(clip || '').trim().toLowerCase().match(/^rect\s*\(([^)]*)\)$/);
+  if (!match) return false;
+  const values = match[1].split(/[,\s]+/).map(value => value.trim()).filter(Boolean);
+  if (values.length !== 4) return false;
+  const [top, right, bottom, left] = values.map(value => metricLengthPx(value, 16));
+  if ([top, right, bottom, left].some(value => value === null)) return false;
+  return bottom <= top || right <= left;
+}
+
+function isScreenReaderOnlyTextStyle(style, metrics = {}) {
+  if (!style) return false;
+  const overflowValues = [style.overflow, style.overflowX, style.overflowY]
+    .map(value => String(value || '').toLowerCase());
+  const clipsOverflow = overflowValues.some(value => value === 'hidden' || value === 'clip');
+
+  const fontSize = metricLengthPx(style.fontSize, 16) || 16;
+  const width = firstMetricLengthPx(fontSize, metrics.width, metrics.clientWidth, style.width, style.inlineSize);
+  const height = firstMetricLengthPx(fontSize, metrics.height, metrics.clientHeight, style.height, style.blockSize);
+  const isTiny = width !== null && height !== null && width <= 2 && height <= 2;
+  const isAbsolutelyHidden = String(style.position || '').toLowerCase() === 'absolute' && isTiny && clipsOverflow;
+
+  const clipPath = String(style.clipPath || style.webkitClipPath || '').trim();
+  const clip = String(style.clip || '').trim();
+  return isAbsolutelyHidden || clippedByInset(clipPath) || clippedByRect(clip);
+}
+
+function isRenderedForBrowserRule(el) {
+  for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
+    if (cur.getAttribute?.('aria-hidden') === 'true') return false;
+    const style = getComputedStyle(cur);
+    const visibility = String(style.visibility || '').toLowerCase();
+    if (style.display === 'none' || visibility === 'hidden' || visibility === 'collapse') return false;
+    if ((parseFloat(style.opacity) || 0) <= 0.01) return false;
+    if (String(style.contentVisibility || '').toLowerCase() === 'hidden') return false;
+  }
+  return true;
+}
+
 function checkElementTextOverflowDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
+  if (!isRenderedForBrowserRule(el)) return [];
   // Only the element that actually owns overflowing text — not its ancestors,
   // which inherit a wider scrollWidth from the spilling descendant.
   const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
   if (!hasDirectText) return [];
   const style = getComputedStyle(el);
+  const rect = el.getBoundingClientRect ? el.getBoundingClientRect() : null;
+  if (isScreenReaderOnlyTextStyle(style, {
+    width: rect?.width,
+    height: rect?.height,
+    clientWidth: el.clientWidth,
+    clientHeight: el.clientHeight,
+  })) return [];
   const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
   if (isScrollRegion(style)) return [];
   // A scrollable ancestor means this overflow is intentional and scrollable.
@@ -2312,5 +2698,6 @@ export {
   checkClippedOverflow,
   checkElementClippedOverflow,
   checkElementClippedOverflowDOM,
+  isScreenReaderOnlyTextStyle,
   checkElementTextOverflowDOM,
 };

.agents/skills/impeccable/scripts/detector/shared/fonts.mjs

@@ -0,0 +1,30 @@
+const GOOGLE_FONTS_URL_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
+
+function normalizeGoogleFontFamilyParam(value) {
+  return String(value || '')
+    .split('|')
+    .map(part => part.split(':')[0].trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function extractGoogleFontFamilies(text) {
+  const families = [];
+  if (!text) return families;
+
+  GOOGLE_FONTS_URL_RE.lastIndex = 0;
+  let urlMatch;
+  while ((urlMatch = GOOGLE_FONTS_URL_RE.exec(text)) !== null) {
+    const url = urlMatch[0];
+    const queryStart = url.indexOf('?');
+    if (queryStart === -1) continue;
+
+    const params = new URLSearchParams(url.slice(queryStart + 1).replace(/&amp;/g, '&'));
+    for (const value of params.getAll('family')) {
+      families.push(...normalizeGoogleFontFamilyParam(value));
+    }
+  }
+
+  return families;
+}
+
+export { extractGoogleFontFamilies };

.agents/skills/impeccable/scripts/detector/shared/inline-ignores.mjs

@@ -0,0 +1,148 @@
+/**
+ * Inline, in-file ignore directives — eslint-disable-style waivers that live at
+ * the point they apply and travel with the artifact instead of (or alongside)
+ * an ignore in `.impeccable/config.json`.
+ *
+ * A config ignore is the right default for repo-wide policy. This complements it
+ * for the one case config can't cover: a waiver that belongs to a single file and
+ * needs to follow that file when it leaves the repo — a generated/exported
+ * standalone document, an emailed HTML file, a snippet scanned out of context.
+ *
+ * Comment-syntax-agnostic: the directive is a raw token matched anywhere on a
+ * line, so the same marker works across every comment style impeccable scans —
+ * `//`, `/* *\/`, `<!-- -->`, `#`, `{/* *\/}`, `{# #}`. Trailing comment closers
+ * are stripped before the rule list is parsed.
+ *
+ * Syntax (reason optional; eslint `--` or biome `:` separator):
+ *
+ *   impeccable-disable <rule>[, <rule>...] [-- reason]   whole file
+ *   impeccable-disable-line <rule>...      [-- reason]   the same line
+ *   impeccable-disable-next-line <rule>... [-- reason]   the following line
+ *   impeccable-disable                                   bare / `*` = every rule
+ *
+ * Examples:
+ *
+ *   <!-- impeccable-disable overused-font -- exported brand doc, font is first-party -->
+ *   .brand { font-family: Inter; } /* impeccable-disable-line overused-font *\/
+ *   // impeccable-disable-next-line bounce-easing: intentional playful affordance
+ *
+ * Behavior is suppression, for parity with config ignores: a matched directive
+ * drops the finding. The inline reason is self-documenting in the diff; it is not
+ * required and is discarded at scan time (only used here to keep reason words out
+ * of the parsed rule list).
+ */
+
+const DIRECTIVE_RE = /impeccable-(disable-next-line|disable-line|disable)\b[ \t]*([^\n\r]*)/gi;
+
+// Trailing comment closers, so `*/`, `*/}`, `-->`, `*}`, `#}`, `%>`, `}}` don't
+// leak into the rule list. Anchored to end-of-line; the leading `\s*` mops up the
+// space before the closer. `--+>` covers `-->` and any longer dash run.
+const TRAILING_CLOSER_RE = /\s*(?:\*\/\}?|--+>|\*\}|#\}|%>|\}\})\s*$/;
+
+function normalizeRule(token) {
+  return String(token || '').trim().toLowerCase();
+}
+
+// Split the directive remainder into rule tokens, dropping any human reason that
+// follows an eslint-style `--` or biome-style `:` separator. Rule ids only ever
+// contain single hyphens (`overused-font`, `bounce-easing`), so `--` and `:`
+// are unambiguous separators.
+function parseRuleList(remainder) {
+  let text = String(remainder || '').replace(TRAILING_CLOSER_RE, '').trim();
+  // Cut off a human reason at the first `--` (eslint) or `:` (biome) separator.
+  const reasonSep = text.match(/\s*(?:--+|:)\s*/);
+  if (reasonSep) text = text.slice(0, reasonSep.index);
+  const tokens = text.split(/[\s,]+/).map(normalizeRule).filter(Boolean);
+  if (tokens.length === 0 || tokens.includes('*')) return ['*'];
+  return tokens;
+}
+
+function addRules(set, rules) {
+  for (const rule of rules) set.add(rule);
+}
+
+function getSet(map, key) {
+  let set = map.get(key);
+  if (!set) {
+    set = new Set();
+    map.set(key, set);
+  }
+  return set;
+}
+
+/**
+ * Parse every inline ignore directive in a file's raw text.
+ *
+ * Returns sets keyed by the 1-based line the directive *targets* so matching is a
+ * direct lookup:
+ *   - file:     rules disabled for the whole file
+ *   - line:     line -> rules disabled on that exact line (disable-line)
+ *   - nextLine: line -> rules disabled on that line (disable-next-line on line-1)
+ *
+ * `*` in any set means "every rule".
+ */
+function parseInlineIgnores(content) {
+  const result = { file: new Set(), line: new Map(), nextLine: new Map() };
+  const text = typeof content === 'string' ? content : '';
+  // Cheap bail-out: the substring must be present for any directive to exist.
+  // Case-insensitive to match DIRECTIVE_RE's `i` flag (e.g. `Impeccable-Disable`).
+  if (!/impeccable-disable/i.test(text)) return result;
+
+  // Split on `\n` only, exactly as detectText numbers lines, so directive line
+  // keys line up with finding `line` values (incl. on `\r`-only line endings).
+  // The directive regex excludes `\r`, so a trailing `\r` on `\r\n` files is
+  // never captured into the rule list.
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    DIRECTIVE_RE.lastIndex = 0;
+    let m;
+    while ((m = DIRECTIVE_RE.exec(lines[i])) !== null) {
+      const variant = m[1].toLowerCase();
+      const rules = parseRuleList(m[2]);
+      if (variant === 'disable') {
+        addRules(result.file, rules);
+      } else if (variant === 'disable-line') {
+        addRules(getSet(result.line, i + 1), rules);
+      } else {
+        // disable-next-line on line i+1 targets line i+2.
+        addRules(getSet(result.nextLine, i + 2), rules);
+      }
+    }
+  }
+  return result;
+}
+
+function setMatches(set, rule) {
+  return Boolean(set) && (set.has('*') || set.has(rule));
+}
+
+function isInlineIgnored(finding, directives) {
+  const rule = normalizeRule(finding && finding.antipattern);
+  if (!rule) return false;
+  if (setMatches(directives.file, rule)) return true;
+  const line = Number(finding && finding.line) || 0;
+  if (line > 0) {
+    if (setMatches(directives.line.get(line), rule)) return true;
+    if (setMatches(directives.nextLine.get(line), rule)) return true;
+  }
+  return false;
+}
+
+function hasDirectives(directives) {
+  return directives.file.size > 0 || directives.line.size > 0 || directives.nextLine.size > 0;
+}
+
+/**
+ * Drop findings waived by an inline directive in the same file's source text.
+ * Findings without a usable line number (e.g. static-HTML page-level findings)
+ * are only matched by whole-file directives — which is the standalone-document
+ * case this primitive exists for.
+ */
+function applyInlineIgnores(findings, content) {
+  if (!Array.isArray(findings) || findings.length === 0) return findings;
+  const directives = parseInlineIgnores(content);
+  if (!hasDirectives(directives)) return findings;
+  return findings.filter((finding) => !isInlineIgnored(finding, directives));
+}
+
+export { parseInlineIgnores, applyInlineIgnores, isInlineIgnored };

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

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+/**
+ * The Impeccable hooks command manages the design hook runtime
+ * via the `hook` key and shared detector ignores via the `detector` key in
+ * .impeccable/config.json / .impeccable/config.local.json.
+ *
+ * Usage:
+ *   node hook-admin.mjs status                         # print current state
+ *   node hook-admin.mjs on                             # set enabled: true
+ *   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-value <rule> <value>    # append to shared ignoreValues
+ *   node hook-admin.mjs ignore-value <rule> <value> --local
+ *   node hook-admin.mjs reset                          # remove all config + cache
+ *
+ * Designed to be invoked by the LLM from the reference/hooks.md flow.
+ * Output is human-readable; the harness will pass it back to the user.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
+
+import {
+  getConfigPath,
+  getLocalConfigPath,
+  getCachePath,
+  getPendingPath,
+  readConfig,
+  DEFAULT_CONFIG,
+  ensureHookGitExcludes,
+  normalizeIgnoreValue,
+  normalizeIgnoreValueEntries,
+} from './hook-lib.mjs';
+
+const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
+const IMPECCABLE_HOOK_COMMAND_MARKERS = [
+  'skills/impeccable/scripts/hook-probe.mjs',
+  'skills/impeccable/scripts/hook.mjs',
+  'skills/impeccable/scripts/hook-before-edit.mjs',
+  'skills/impeccable/scripts/hook-after-edit.mjs',
+  'skills/impeccable/scripts/hook-stop.mjs',
+];
+const TIMEOUT_SECONDS = 5;
+const STATUS_MESSAGE = 'Checking UI changes';
+
+const HOOK_MANIFEST_TARGETS = [
+  {
+    provider: '.claude',
+    skillRel: '.claude/skills/impeccable',
+    destRel: '.claude/settings.local.json',
+    sharedDestRel: '.claude/settings.json',
+    manifest: () => ({
+      description: 'Impeccable design detector: runs after Edit/Write/MultiEdit on UI files and surfaces findings as system reminders.',
+      hooks: {
+        PostToolUse: [
+          {
+            matcher: 'Edit|Write|MultiEdit',
+            hooks: [
+              {
+                type: 'command',
+                command: 'node "${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs"',
+                timeout: TIMEOUT_SECONDS,
+                statusMessage: STATUS_MESSAGE,
+              },
+            ],
+          },
+        ],
+      },
+    }),
+  },
+  {
+    provider: '.agents',
+    skillRel: '.agents/skills/impeccable',
+    destRel: '.codex/hooks.json',
+    manifest: () => ({
+      hooks: {
+        PostToolUse: [
+          {
+            matcher: 'Edit|Write|apply_patch',
+            hooks: [
+              {
+                type: 'command',
+                command: 'node ".agents/skills/impeccable/scripts/hook.mjs"',
+                timeout: TIMEOUT_SECONDS,
+                statusMessage: STATUS_MESSAGE,
+              },
+            ],
+          },
+        ],
+      },
+    }),
+  },
+  {
+    provider: '.cursor',
+    skillRel: '.cursor/skills/impeccable',
+    destRel: '.cursor/hooks.json',
+    manifest: () => ({
+      version: 1,
+      hooks: {
+        preToolUse: [
+          {
+            command: 'node ".cursor/skills/impeccable/scripts/hook-before-edit.mjs"',
+            timeout: TIMEOUT_SECONDS,
+          },
+        ],
+      },
+    }),
+  },
+  {
+    // GitHub Copilot reads repo-level hooks from `.github/hooks/*.json`. The same
+    // manifest is honored by the CLI (once committed to the default branch) and
+    // the cloud/app agent. Schema differs: lowercase `postToolUse`, flat entries,
+    // `bash`/`timeoutSec`, and a `matcher` regex against the `edit`/`create` tools.
+    provider: '.github',
+    skillRel: '.github/skills/impeccable',
+    destRel: '.github/hooks/impeccable.json',
+    manifest: () => ({
+      version: 1,
+      hooks: {
+        postToolUse: [
+          {
+            type: 'command',
+            matcher: 'edit|create|apply_patch',
+            bash: 'node "$(git rev-parse --show-toplevel)/.github/skills/impeccable/scripts/hook.mjs"',
+            timeoutSec: TIMEOUT_SECONDS,
+          },
+        ],
+      },
+    }),
+  },
+];
+
+function readRawConfigFile(filePath) {
+  if (!fs.existsSync(filePath)) return { exists: false, malformed: false, raw: null };
+  try {
+    return { exists: true, malformed: false, raw: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
+  } catch {
+    return { exists: true, malformed: true, raw: null };
+  }
+}
+
+const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
+
+function hookSection(unified) {
+  return unified && typeof unified === 'object' && !Array.isArray(unified) && unified.hook && typeof unified.hook === 'object' && !Array.isArray(unified.hook)
+    ? unified.hook
+    : null;
+}
+
+function detectorSection(unified) {
+  return unified && typeof unified === 'object' && !Array.isArray(unified) && unified.detector && typeof unified.detector === 'object' && !Array.isArray(unified.detector)
+    ? unified.detector
+    : null;
+}
+
+function readRawHookConfig(cwd, opts = {}) {
+  const unified = readRawConfigFile(opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd)).raw;
+  return hookSection(unified);
+}
+
+function readRawDetectorConfig(cwd, opts = {}) {
+  const unified = readRawConfigFile(opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd)).raw;
+  const merged = mergeDetectorConfig(hookSection(unified));
+  return mergeDetectorConfig(detectorSection(unified), merged);
+}
+
+function stripDetectorKeys(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 = {}) {
+  const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
+  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));
+  // 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 } };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
+  return filePath;
+}
+
+function writeDetectorConfig(cwd, detectorConfig, opts = {}) {
+  const filePath = opts.local ? getLocalConfigPath(cwd) : getConfigPath(cwd);
+  if (opts.local) ensureHookGitExcludes(cwd);
+  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 next = {
+    ...existing,
+    detector: mergeDetectorConfig(detectorConfig, existingDetector),
+  };
+  if (Object.keys(nextHook).length > 0) next.hook = nextHook;
+  else delete next.hook;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
+  return filePath;
+}
+
+function mergeHookConfig(existing) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  return {
+    enabled: base.enabled === false ? false : true,
+    limits: {
+      maxFindings: Number.isFinite(base?.limits?.maxFindings) ? base.limits.maxFindings : DEFAULT_CONFIG.limits.maxFindings,
+      maxChars: Number.isFinite(base?.limits?.maxChars) ? base.limits.maxChars : DEFAULT_CONFIG.limits.maxChars,
+    },
+  };
+}
+
+function mergeDetectorConfig(existing, seed = null) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const out = seed ? {
+    ignoreRules: [...seed.ignoreRules],
+    ignoreFiles: [...seed.ignoreFiles],
+    ignoreValues: normalizeIgnoreValueEntries(seed.ignoreValues),
+  } : {
+    ignoreRules: [],
+    ignoreFiles: [],
+    ignoreValues: [],
+  };
+  if (seed?.designSystem && typeof seed.designSystem === 'object' && !Array.isArray(seed.designSystem)) {
+    out.designSystem = { ...seed.designSystem };
+  }
+  if (base.designSystem && typeof base.designSystem === 'object' && !Array.isArray(base.designSystem)) {
+    out.designSystem = {
+      ...(out.designSystem || {}),
+      enabled: base.designSystem.enabled === false ? false : true,
+    };
+  }
+  if (Array.isArray(base.ignoreRules)) {
+    out.ignoreRules = Array.from(new Set([...out.ignoreRules, ...base.ignoreRules.map(String)]));
+  }
+  if (Array.isArray(base.ignoreFiles)) {
+    out.ignoreFiles = Array.from(new Set([...out.ignoreFiles, ...base.ignoreFiles.map(String)]));
+  }
+  if (Array.isArray(base.ignoreValues)) {
+    out.ignoreValues = mergeIgnoreValueEntries(out.ignoreValues, base.ignoreValues);
+  }
+  return out;
+}
+
+function mergeIgnoreValueEntries(existing, incoming) {
+  const map = new Map();
+  for (const entry of normalizeIgnoreValueEntries(existing)) {
+    map.set(ignoreValueEntryKey(entry), entry);
+  }
+  for (const entry of normalizeIgnoreValueEntries(incoming)) {
+    map.set(ignoreValueEntryKey(entry), entry);
+  }
+  return Array.from(map.values());
+}
+
+function ignoreValueEntryKey(entry) {
+  const files = Array.isArray(entry.files) && entry.files.length > 0 ? entry.files.join('\x1f') : '';
+  return `${entry.rule}\0${entry.value}\0${files}`;
+}
+
+function statusReport(cwd) {
+  const shared = readRawConfigFile(getConfigPath(cwd));
+  const local = readRawConfigFile(getLocalConfigPath(cwd));
+  const cfg = readConfig(cwd);
+  const envKill = process.env.IMPECCABLE_HOOK_DISABLED;
+  const envState = envKill ? `IMPECCABLE_HOOK_DISABLED=${envKill}` : 'unset';
+  const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.impeccable/config.json';
+  const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.impeccable/config.local.json';
+  const cachePath = path.relative(cwd, getCachePath(cwd)) || '.impeccable/hook.cache.json';
+  const fileState = (info, relPath, absent) => {
+    if (info.malformed) return `${relPath} (malformed; ignored)`;
+    if (info.exists) return relPath;
+    return `${relPath} (${absent})`;
+  };
+  const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
+
+  const lines = [
+    `Impeccable design hook`,
+    `  state:        ${cfg.enabled ? 'enabled' : 'disabled'}`,
+    `  shared file:  ${fileState(shared, cfgPath, 'using defaults; file not present')}`,
+    `  local file:   ${fileState(local, localPath, 'not present')}`,
+    `  ignoreRules:  ${cfg.ignoreRules.length ? cfg.ignoreRules.join(', ') : '(none)'}`,
+    `  ignoreFiles:  ${cfg.ignoreFiles.length ? cfg.ignoreFiles.join(', ') : '(none)'}`,
+    `  ignoreValues: ${ignoreValues.length ? ignoreValues.join(', ') : '(none)'}`,
+    `  maxFindings:  ${cfg.limits.maxFindings}`,
+    `  maxChars:     ${cfg.limits.maxChars}`,
+    `  env override: ${envState}`,
+    `  cache file:   ${fs.existsSync(getCachePath(cwd)) ? cachePath : `${cachePath} (not present)`}`,
+  ];
+  return lines.join('\n');
+}
+
+function setEnabled(cwd, value) {
+  const config = mergeHookConfig(readRawHookConfig(cwd));
+  config.enabled = value;
+  const target = writeHookConfig(cwd, config);
+  if (!value) {
+    return `Design hook disabled for this project (wrote ${path.relative(cwd, target) || target}).`;
+  }
+
+  const localTarget = writeHookConfig(cwd, { consent: 'accepted' }, { local: true });
+  const repaired = repairHookManifests(cwd);
+  const parts = [
+    `Design hook enabled for this project (wrote ${path.relative(cwd, target) || target}).`,
+    `Recorded local hook consent in ${path.relative(cwd, localTarget) || localTarget}.`,
+  ];
+  if (repaired.written.length > 0) {
+    parts.push(`Installed or repaired hook manifests for: ${repaired.written.join(', ')}.`);
+  } else if (repaired.already.length > 0) {
+    parts.push(`Hook manifests already installed for: ${repaired.already.join(', ')}.`);
+  } else {
+    parts.push('No installed provider skill folders found to repair.');
+  }
+  if (repaired.backups.length > 0) {
+    parts.push(`Backed up malformed manifest(s): ${repaired.backups.map((filePath) => path.relative(cwd, filePath) || filePath).join(', ')}.`);
+  }
+  return parts.join(' ');
+}
+
+function repairHookManifests(cwd) {
+  const result = { written: [], already: [], backups: [] };
+  for (const target of HOOK_MANIFEST_TARGETS) {
+    if (!fs.existsSync(path.join(cwd, target.skillRel))) continue;
+    const dest = path.join(cwd, target.destRel);
+    const sharedDest = target.sharedDestRel ? path.join(cwd, target.sharedDestRel) : null;
+
+    if (sharedDest && fileHasImpeccableHookMarker(sharedDest)) {
+      pruneImpeccableHookFromManifest(dest);
+      result.already.push(target.provider);
+      continue;
+    }
+
+    const fresh = target.manifest();
+    let next = fresh;
+    if (fs.existsSync(dest)) {
+      try {
+        next = mergeHookManifests(JSON.parse(fs.readFileSync(dest, 'utf-8')), fresh);
+      } catch {
+        const backup = `${dest}.bak`;
+        fs.copyFileSync(dest, backup);
+        result.backups.push(backup);
+      }
+    }
+
+    const serialized = `${JSON.stringify(next, null, 2)}\n`;
+    const current = fs.existsSync(dest) ? safeReadText(dest) : null;
+    if (current === serialized) {
+      result.already.push(target.provider);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, serialized);
+    result.written.push(target.provider);
+  }
+  return result;
+}
+
+function safeReadText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function mergeHookManifests(existing, fresh) {
+  const existingObject = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
+  const freshObject = fresh && typeof fresh === 'object' && !Array.isArray(fresh) ? fresh : {};
+  const existingHooks = existingObject.hooks && typeof existingObject.hooks === 'object' && !Array.isArray(existingObject.hooks)
+    ? existingObject.hooks
+    : {};
+  const freshHooks = freshObject.hooks && typeof freshObject.hooks === 'object' && !Array.isArray(freshObject.hooks)
+    ? freshObject.hooks
+    : {};
+
+  const merged = { ...existingObject, hooks: {} };
+  if (freshObject.version !== undefined) merged.version = freshObject.version;
+  if (freshObject.description !== undefined) merged.description = freshObject.description;
+
+  const hookEvents = new Set([...Object.keys(existingHooks), ...Object.keys(freshHooks)]);
+  for (const event of hookEvents) {
+    const preserved = stripImpeccableHookEntries(existingHooks[event]);
+    const added = Array.isArray(freshHooks[event]) ? freshHooks[event] : [];
+    const mergedEntries = [...preserved, ...added];
+    if (mergedEntries.length > 0) merged.hooks[event] = mergedEntries;
+  }
+  return merged;
+}
+
+function fileHasImpeccableHookMarker(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
+  if (!parsed.hooks || typeof parsed.hooks !== 'object') return false;
+  return valueHasImpeccableHookMarker(parsed.hooks);
+}
+
+function valueHasImpeccableHookMarker(value) {
+  if (typeof value === 'string') {
+    return IMPECCABLE_HOOK_COMMAND_MARKERS.some((marker) => value.includes(marker));
+  }
+  if (Array.isArray(value)) return value.some(valueHasImpeccableHookMarker);
+  if (value && typeof value === 'object') return Object.values(value).some(valueHasImpeccableHookMarker);
+  return false;
+}
+
+function stripImpeccableHookEntry(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  // `command`/`args`: Claude/Codex/Cursor. `bash`/`powershell`: GitHub Copilot's
+  // flat entry shape, where the marker lives under the shell-command keys.
+  if (valueHasImpeccableHookMarker(entry.command) || valueHasImpeccableHookMarker(entry.args)
+    || valueHasImpeccableHookMarker(entry.bash) || valueHasImpeccableHookMarker(entry.powershell)) {
+    return null;
+  }
+  if (!Array.isArray(entry.hooks)) return entry;
+
+  const strippedHooks = entry.hooks
+    .map(stripImpeccableHookEntry)
+    .filter(Boolean);
+
+  if (strippedHooks.length === 0 && entry.hooks.some(valueHasImpeccableHookMarker)) {
+    return null;
+  }
+  return { ...entry, hooks: strippedHooks };
+}
+
+function stripImpeccableHookEntries(entries) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map(stripImpeccableHookEntry)
+    .filter(Boolean);
+}
+
+function pruneImpeccableHookFromManifest(manifestPath) {
+  if (!fileHasImpeccableHookMarker(manifestPath)) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+
+  const existingHooks = parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks)
+    ? parsed.hooks
+    : {};
+  const cleanedHooks = {};
+  for (const [event, entries] of Object.entries(existingHooks)) {
+    const kept = stripImpeccableHookEntries(entries);
+    if (kept.length > 0) cleanedHooks[event] = kept;
+  }
+
+  const next = { ...parsed };
+  if (Object.keys(cleanedHooks).length > 0) {
+    next.hooks = cleanedHooks;
+  } else {
+    delete next.hooks;
+    delete next.description;
+    delete next.version;
+  }
+
+  if (Object.keys(next).length === 0) {
+    fs.rmSync(manifestPath, { force: true });
+  } else {
+    fs.writeFileSync(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  return true;
+}
+
+function normalizeRuleId(rule) {
+  return String(rule || '').trim().toLowerCase();
+}
+
+function parseIgnoreRuleArgs(args) {
+  const positionals = [];
+  let allValues = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i] || '');
+    if (arg === '--all-values') {
+      allValues = true;
+    } else if (arg === '--reason') {
+      while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) i++;
+    } else if (arg.startsWith('--reason=')) {
+      // Accepted for command symmetry; ignoreRules stores rule ids only.
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown ignore-rule flag: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return {
+    rule: normalizeRuleId(positionals[0]),
+    allValues,
+  };
+}
+
+function addIgnoreRule(cwd, args) {
+  const parsed = parseIgnoreRuleArgs(args);
+  const rule = parsed.rule;
+  if (!rule) throw new Error(`Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule side-tab`);
+  if (rule === 'overused-font' && !parsed.allValues) {
+    throw new Error(`overused-font is value-specific by default. Use ${IMPECCABLE_COMMAND} hooks ignore-value overused-font <font> for a confirmed font, or ${IMPECCABLE_COMMAND} hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.`);
+  }
+  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
+  if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
+  writeDetectorConfig(cwd, config);
+  return `Added "${rule}" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
+}
+
+function addIgnoreFile(cwd, glob) {
+  if (!glob) throw new Error(`Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "src/legacy/**"`);
+  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
+  if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
+  writeDetectorConfig(cwd, config);
+  return `Added "${glob}" to detector.ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
+}
+
+function parseIgnoreValueArgs(args) {
+  const positionals = [];
+  let shared = false;
+  let local = false;
+  let reason = '';
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--shared') {
+      shared = true;
+    } else if (arg === '--local') {
+      local = true;
+    } else if (arg === '--reason') {
+      const chunks = [];
+      while (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) {
+        chunks.push(args[++i]);
+      }
+      reason = chunks.join(' ').trim();
+    } else if (String(arg).startsWith('--reason=')) {
+      reason = String(arg).slice('--reason='.length).trim();
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  const [rule, ...valueParts] = positionals;
+  return {
+    rule: String(rule || '').trim().toLowerCase(),
+    value: normalizeIgnoreValue(valueParts.join(' ')),
+    shared,
+    local,
+    reason,
+  };
+}
+
+function addIgnoreValue(cwd, args) {
+  const parsed = parseIgnoreValueArgs(args);
+  if (!parsed.rule || !parsed.value) {
+    throw new Error(`Pass a rule id and value, e.g. ${IMPECCABLE_COMMAND} hooks ignore-value overused-font Inter`);
+  }
+
+  if (parsed.shared && parsed.local) {
+    throw new Error('Pass only one scope flag: --shared or --local');
+  }
+
+  const local = parsed.local;
+  const config = mergeDetectorConfig(readRawDetectorConfig(cwd, { local }));
+  const key = `${parsed.rule}\0${parsed.value}`;
+  const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
+
+  if (existing) {
+    if (parsed.reason) existing.reason = parsed.reason;
+  } else {
+    const entry = {
+      rule: parsed.rule,
+      value: parsed.value,
+      createdAt: new Date().toISOString(),
+    };
+    if (parsed.reason) entry.reason = parsed.reason;
+    config.ignoreValues.push(entry);
+  }
+
+  const target = writeDetectorConfig(cwd, config, { local });
+  const scope = local ? 'local detector.ignoreValues' : 'shared detector.ignoreValues';
+  return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
+}
+
+function reset(cwd) {
+  const removed = [];
+  // Unified files may hold non-hook keys (e.g. updateCheck); strip only the
+  // hook/detector subtrees and keep the rest, deleting the file only if nothing remains.
+  for (const filePath of [getConfigPath(cwd), getLocalConfigPath(cwd)]) {
+    try {
+      const raw = readRawConfigFile(filePath).raw;
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw) || (!('hook' in raw) && !('detector' in raw))) continue;
+      const { hook, detector, ...rest } = raw;
+      if (Object.keys(rest).length === 0) {
+        fs.unlinkSync(filePath);
+      } else {
+        fs.writeFileSync(filePath, JSON.stringify(rest, null, 2) + '\n');
+      }
+      removed.push(path.relative(cwd, filePath) || filePath);
+    } catch { /* ignore */ }
+  }
+  // State files are wholly ours; delete outright.
+  for (const filePath of [getCachePath(cwd), getPendingPath(cwd)]) {
+    try {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        removed.push(path.relative(cwd, filePath) || filePath);
+      }
+    } catch { /* ignore */ }
+  }
+  return removed.length
+    ? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
+    : 'No hook config or cache to remove. Already at defaults.';
+}
+
+function main() {
+  const [, , actionArg, ...rest] = process.argv;
+  const action = (actionArg || 'status').toLowerCase();
+  const cwd = process.cwd();
+
+  if (!ACTIONS.has(action)) {
+    process.stderr.write(`Unknown action: ${action}\nValid: ${Array.from(ACTIONS).join(', ')}\n`);
+    process.exit(1);
+  }
+
+  try {
+    let out = '';
+    switch (action) {
+      case 'status': out = statusReport(cwd); break;
+      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-value': out = addIgnoreValue(cwd, rest); break;
+      case 'reset':  out = reset(cwd); break;
+    }
+    process.stdout.write(out + '\n');
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message || err}\n`);
+    process.exit(1);
+  }
+}
+
+main();

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

@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+/**
+ * Impeccable design hook — Cursor preToolUse write gate.
+ *
+ * Cursor's stop hook is not consistently dispatched by the headless agent, so
+ * this hook checks proposed Write/Edit content before it lands. It only denies
+ * writes when the real detector finds an issue in the proposed UI content.
+ *
+ * Contract: never break a turn accidentally. On malformed input or internal
+ * errors, allow the tool and exit 0.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  ALLOWED_EXTS,
+  EDIT_COUNT_THRESHOLD,
+  GENERATED_PATH,
+  SENSITIVE_PATH,
+  appendDesignSystemNote,
+  designSystemOptions,
+  filterFindings,
+  isNativePlatform,
+  loadDetector,
+  matchConfiguredExtension,
+  matchesAnyGlob,
+  persistCache,
+  readCache,
+  readConfig,
+  renderTemplate,
+  resolveCacheCwd,
+  resolveProjectCwd,
+  resolveProjectPlatform,
+  truthy,
+  writeAuditLog,
+} from './hook-lib.mjs';
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+function done(payload = null) {
+  if (payload) process.stdout.write(JSON.stringify(payload));
+  process.exit(0);
+}
+
+function allow(extra = {}, payload = {}) {
+  writeAuditLog(process.env, {
+    ts: new Date().toISOString(),
+    event: 'preToolUse',
+    ...extra,
+  });
+  return done({ permission: 'allow', ...payload });
+}
+
+function deny(message, audit) {
+  writeAuditLog(process.env, {
+    ts: new Date().toISOString(),
+    event: 'preToolUse',
+    blocked: true,
+    ...audit,
+  });
+  return done({
+    permission: 'deny',
+    user_message: message,
+    agent_message: message,
+  });
+}
+
+function toolInput(event) {
+  return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
+}
+
+function proposedFilePath(event, cwd) {
+  const input = toolInput(event);
+  const raw = input.file_path || input.path || input.target_file || event?.file_path;
+  const candidate = typeof raw === 'string' && raw.trim()
+    ? raw
+    : shellWriteDestination(shellCommand(input));
+  if (typeof candidate !== 'string' || !candidate.trim()) return '';
+  return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
+}
+
+function proposedContent(event, cwd, filePath) {
+  const input = toolInput(event);
+  for (const key of ['content', 'streamContent', 'text']) {
+    if (typeof input[key] === 'string') return input[key];
+  }
+
+  const editProjection = projectedEditContent(input, filePath, cwd);
+  if (editProjection !== undefined) return editProjection;
+
+  if (hasFragmentEditContent(input)) {
+    return { skipped: 'fragment-only-edit' };
+  }
+
+  const command = shellCommand(input);
+  const pythonContent = shellPythonWriteContent(command);
+  if (pythonContent) return pythonContent;
+  const shellContent = shellHereDocContent(command);
+  if (shellContent) return shellContent;
+  const copiedContent = shellCopiedFileContent(command, cwd);
+  if (copiedContent) return copiedContent;
+  return '';
+}
+
+function hasFragmentEditContent(input) {
+  if (!input || typeof input !== 'object') return false;
+  if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
+    return true;
+  }
+  return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
+}
+
+function projectedEditContent(input, filePath, cwd) {
+  if (!filePath) return undefined;
+  const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
+  const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
+  if (singleOld !== undefined || singleNew !== undefined) {
+    if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
+    const original = readExistingProjectFile(filePath, cwd);
+    if (original === null) return { skipped: 'edit-original-unreadable' };
+    const projected = replaceOnce(original, singleOld, singleNew);
+    return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
+  }
+
+  if (!Array.isArray(input.edits)) return undefined;
+  const original = readExistingProjectFile(filePath, cwd);
+  if (original === null) return { skipped: 'edit-original-unreadable' };
+
+  let projected = original;
+  for (const edit of input.edits) {
+    if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
+    const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
+    const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
+    if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
+    const next = replaceOnce(projected, oldString, newString);
+    if (next === null) return { skipped: 'edit-old-string-missing' };
+    projected = next;
+  }
+  return projected;
+}
+
+function firstString(obj, keys) {
+  for (const key of keys) {
+    if (typeof obj?.[key] === 'string') return obj[key];
+  }
+  return undefined;
+}
+
+function replaceOnce(original, oldString, newString) {
+  if (oldString === '') return null;
+  const index = original.indexOf(oldString);
+  if (index === -1) return null;
+  return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
+}
+
+function readExistingProjectFile(filePath, cwd) {
+  if (!isInsideProject(filePath, cwd)) return null;
+  if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > 1024 * 1024) return null;
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function shellCommand(input) {
+  if (typeof input.command === 'string') return input.command;
+  if (input.args && typeof input.args.command === 'string') return input.args.command;
+  return '';
+}
+
+function shellRedirectPath(command) {
+  if (!command || typeof command !== 'string') return '';
+  const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
+  return (match?.[1] || match?.[2] || match?.[3] || '').trim();
+}
+
+function shellWriteDestination(command) {
+  return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || shellPythonWriteDestination(command) || '';
+}
+
+function shellPythonWriteDestination(command) {
+  if (!/\bpython(?:3)?\b/.test(command || '')) return '';
+  const directPath = firstMatch(command, /(?:^|[^\w.])(?:pathlib\.)?Path\(\s*(["'])(.*?)\1\s*\)\s*\.write_text\s*\(/);
+  if (directPath) return directPath;
+
+  const pathsByVar = new Map();
+  const assignmentRe = /\b([A-Za-z_]\w*)\s*=\s*(?:pathlib\.)?Path\(\s*(["'])(.*?)\2\s*\)/g;
+  let assignment;
+  while ((assignment = assignmentRe.exec(command))) {
+    pathsByVar.set(assignment[1], assignment[3]);
+  }
+
+  const writeVarRe = /\b([A-Za-z_]\w*)\.write_text\s*\(/g;
+  let writeVar;
+  while ((writeVar = writeVarRe.exec(command))) {
+    const candidate = pathsByVar.get(writeVar[1]);
+    if (candidate) return candidate;
+  }
+
+  return firstMatch(command, /\bopen\(\s*(["'])(.*?)\1\s*,\s*(["'])[wax](?:\+)?b?\3/);
+}
+
+function firstMatch(value, re) {
+  const match = String(value || '').match(re);
+  return (match?.[2] || '').trim();
+}
+
+function shellTeeDestination(command) {
+  const words = shellWords(command);
+  const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
+  if (teeIndex === -1) return '';
+  for (const word of words.slice(teeIndex + 1)) {
+    if (['&&', '||', ';', '|'].includes(word)) break;
+    if (word === '--') continue;
+    if (word.startsWith('-')) continue;
+    return word;
+  }
+  return '';
+}
+
+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 (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
+  try {
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isFile() || stat.size > 1024 * 1024) return '';
+    return fs.readFileSync(sourcePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function shellCopyPaths(command) {
+  const words = shellWords(command);
+  if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
+  const args = [];
+  for (const word of words.slice(1)) {
+    if (['&&', '||', ';', '|'].includes(word)) break;
+    if (word === '--') continue;
+    if (word.startsWith('-')) continue;
+    args.push(word);
+  }
+  if (args.length < 2) return null;
+  return { source: args[args.length - 2], dest: args[args.length - 1] };
+}
+
+function shellWords(command) {
+  if (!command || typeof command !== 'string') return [];
+  const words = [];
+  const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
+  let match;
+  while ((match = re.exec(command))) {
+    words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
+  }
+  return words;
+}
+
+function shellHereDocContent(command) {
+  if (!command || typeof command !== 'string') return '';
+  const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
+  if (!markerMatch) return '';
+  const marker = markerMatch[1];
+  const start = (markerMatch.index || 0) + markerMatch[0].length;
+  const rest = command.slice(start);
+  const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
+  const end = rest.search(endRe);
+  return end >= 0 ? rest.slice(0, end) : '';
+}
+
+function shellPythonWriteContent(command) {
+  if (!/\bpython(?:3)?\b/.test(command || '')) return '';
+  const script = shellHereDocContent(command) || command;
+  return pythonStringArg(script, /\.write_text\s*\(\s*/g) || pythonStringArg(script, /\.write\s*\(\s*/g);
+}
+
+function pythonStringArg(script, prefixRe) {
+  let prefix;
+  while ((prefix = prefixRe.exec(script))) {
+    const start = prefixRe.lastIndex;
+    const triple = script.slice(start, start + 3);
+    if (triple === "'''" || triple === '"""') {
+      const end = script.indexOf(triple, start + 3);
+      if (end !== -1) return script.slice(start + 3, end);
+      continue;
+    }
+    const quote = script[start];
+    if (quote !== '"' && quote !== "'") continue;
+    let out = '';
+    for (let i = start + 1; i < script.length; i++) {
+      const ch = script[i];
+      if (ch === '\\') {
+        out += script[i + 1] || '';
+        i += 1;
+      } else if (ch === quote) {
+        return out;
+      } else {
+        out += ch;
+      }
+    }
+  }
+  return '';
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function relativePath(filePath, cwd) {
+  try {
+    const rel = path.relative(cwd, filePath);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
+    return rel.split(path.sep).join('/');
+  } catch {
+    return filePath;
+  }
+}
+
+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.
+async function detectProposedHtml(detector, content, filePath, scanOptions) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'impeccable-pre-'));
+  const tmpFile = path.join(dir, path.basename(filePath));
+  try {
+    fs.writeFileSync(tmpFile, content);
+    const findings = await detector.detectHtml(tmpFile, scanOptions);
+    // Findings carry the temp path; remap so file-scoped ignores still match.
+    return (findings || []).map((f) => (f && typeof f === 'object' ? { ...f, file: filePath } : f));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function cursorBlockMessage(findings, filePath, config, cwd) {
+  const rendered = renderTemplate(findings, filePath, config, { cwd });
+  const blocked = rendered.replace(
+    '[impeccable@1] Design hook findings requiring review',
+    '[impeccable@1] Impeccable design hook blocked this write before it landed. Design hook findings requiring review',
+  );
+  return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
+}
+
+function findingSignature(findings) {
+  return findings
+    .map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
+    .sort()
+    .join('|');
+}
+
+function bumpCursorDenial(cache, sessionId, filePath, findings) {
+  const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
+  cache.sessions[sessionId] = session;
+  session.updatedAt = Date.now();
+  const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
+  session.files[filePath] = fileEntry;
+  const key = findingSignature(findings);
+  fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
+    ? fileEntry.cursorDenials
+    : {};
+  fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
+  return { key, count: fileEntry.cursorDenials[key] };
+}
+
+async function main() {
+  if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
+    return allow({ skipped: 'env-disabled' });
+  }
+
+  let event = null;
+  try {
+    const raw = await readStdin();
+    if (raw) event = JSON.parse(raw);
+  } catch {
+    return allow({ skipped: 'stdin-malformed' });
+  }
+
+  if (!event || typeof event !== 'object') {
+    return allow({ skipped: 'stdin-empty' });
+  }
+
+  const sessionCwd = resolveProjectCwd(event);
+  const started = Date.now();
+  const filePath = proposedFilePath(event, sessionCwd);
+  // Re-key config/cache to the edited file's project root when the session
+  // was launched from a non-project umbrella directory (issue #305).
+  const cwd = resolveCacheCwd(filePath, sessionCwd);
+  const audit = {
+    harness: 'cursor',
+    cwd,
+    tool: event.tool_name || null,
+    file: filePath || null,
+  };
+
+  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 (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 });
+
+  // Config is read before the extension gate so `detector.extensions` entries
+  // (e.g. `.blade.php` template files, issue #316) can widen it.
+  const config = readConfig(cwd);
+  const ext = path.extname(filePath).toLowerCase();
+  const configuredExt = matchConfiguredExtension(filePath, config.extensions);
+  audit.ext = configuredExt ? configuredExt.ext : ext;
+  if (!ALLOWED_EXTS.has(ext) && !configuredExt) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
+
+  const contentResult = proposedContent(event, cwd, filePath);
+  if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
+    return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
+  }
+  const content = typeof contentResult === 'string' ? contentResult : '';
+  if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
+
+  if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
+
+  // Web rule engine, native project: stand aside (see resolveProjectPlatform).
+  const platform = resolveProjectPlatform(cwd);
+  if (isNativePlatform(platform)) {
+    return allow({ ...audit, skipped: 'native-platform', platform, durationMs: Date.now() - started });
+  }
+
+  const rel = relativePath(filePath, cwd);
+  if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
+    return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
+  }
+
+  const detector = await loadDetector();
+  if (!detector || typeof detector.detectText !== 'function') {
+    return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
+  }
+  const scanOptions = designSystemOptions(config, detector, cwd);
+
+  // Mirror runHook's engine routing so template issues the HTML engine catches
+  // post-edit cannot slip past the pre-write gate.
+  const useHtmlEngine = configuredExt
+    ? configuredExt.engine === 'html'
+    : (ext === '.html' || ext === '.htm');
+  let findings = [];
+  try {
+    findings = useHtmlEngine && typeof detector.detectHtml === 'function'
+      ? await detectProposedHtml(detector, content, filePath, scanOptions)
+      : await detector.detectText(content, filePath, scanOptions);
+  } catch {
+    return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
+  }
+
+  const filtered = filterFindings(findings || [], content, ext, config);
+  if (filtered.length === 0) {
+    return allow({
+      ...audit,
+      findings: (findings || []).length,
+      blockedFindings: 0,
+      durationMs: Date.now() - started,
+    });
+  }
+
+  const message = appendDesignSystemNote(cursorBlockMessage(filtered, filePath, config, cwd), scanOptions);
+  const sessionId = event.session_id || event.conversation_id || 'unknown';
+  const cache = readCache(cwd);
+  const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
+  persistCache(cwd, cache);
+  if (denial.count > EDIT_COUNT_THRESHOLD) {
+    const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
+    return allow({
+      ...audit,
+      findings: (findings || []).length,
+      blockedFindings: filtered.length,
+      cursorDenialKey: denial.key,
+      cursorDenialCount: denial.count,
+      downgraded: true,
+      chars: warning.length,
+      durationMs: Date.now() - started,
+    }, {
+      user_message: warning,
+      agent_message: warning,
+    });
+  }
+  return deny(message, {
+    ...audit,
+    findings: (findings || []).length,
+    blockedFindings: filtered.length,
+    cursorDenialKey: denial.key,
+    cursorDenialCount: denial.count,
+    chars: message.length,
+    durationMs: Date.now() - started,
+  });
+}
+
+main().catch((err) => {
+  if (process.env.IMPECCABLE_HOOK_DEBUG) {
+    process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
+  }
+  done({ permission: 'allow' });
+});

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Impeccable design hook — PostToolUse entry point.
+ *
+ * Reads the Claude Code / Codex / Cursor hook event from stdin, runs the design
+ * detector against the touched file, and emits a system reminder via
+ * `hookSpecificOutput.additionalContext` when findings exist.
+ *
+ * Contract: never break a turn. Always exit 0. Clean files emit a small ack
+ * unless quiet mode is enabled.
+ *
+ * Most logic lives in `hook-lib.mjs` so it is unit-testable without a
+ * subprocess. This file is the thin stdin/stdout adapter.
+ */
+
+import { runHook, writeAuditLog } from './hook-lib.mjs';
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+async function main() {
+  // Snapshot the inherited env FIRST so the re-entrancy guard checks the
+  // parent's value, not the value we are about to export for any child
+  // processes the hook might ever spawn.
+  const inheritedEnv = { ...process.env };
+  process.env.IMPECCABLE_HOOK_DEPTH = process.env.IMPECCABLE_HOOK_DEPTH || '1';
+
+  let stdinJson = '';
+  try { stdinJson = await readStdin(); } catch { /* fall through */ }
+
+  const result = await runHook({
+    stdinJson,
+    env: inheritedEnv,
+    cwd: process.cwd(),
+  });
+
+  writeAuditLog(process.env, result.audit, process.cwd());
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  process.exit(result.exitCode || 0);
+}
+
+main().catch((err) => {
+  // Last-ditch: never break the agent's turn even if something we did not
+  // anticipate goes wrong. Audit-log the failure if logging is enabled.
+  try {
+    writeAuditLog(process.env, {
+      ts: new Date().toISOString(),
+      event: 'PostToolUse',
+      error: String(err && err.message ? err.message : err),
+    });
+  } catch { /* swallow */ }
+  if (process.env.IMPECCABLE_HOOK_DEBUG) {
+    process.stderr.write(`[impeccable-hook] ${err}\n`);
+  }
+  process.exit(0);
+});

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

@@ -1,126 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-export const IMPECCABLE_DIR = '.impeccable';
-export const LIVE_DIR = 'live';
-export const CRITIQUE_DIR = 'critique';
-
-export function getImpeccableDir(cwd = process.cwd()) {
-  return path.join(cwd, IMPECCABLE_DIR);
-}
-
-export function getDesignSidecarPath(cwd = process.cwd()) {
-  return path.join(getImpeccableDir(cwd), 'design.json');
-}
-
-export function getDesignSidecarCandidates(cwd = process.cwd(), contextDir = cwd) {
-  const candidates = [
-    getDesignSidecarPath(cwd),
-    path.join(cwd, 'DESIGN.json'),
-  ];
-  const contextLegacy = path.join(contextDir, 'DESIGN.json');
-  if (!candidates.includes(contextLegacy)) candidates.push(contextLegacy);
-  return candidates;
-}
-
-export function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd) {
-  return firstExisting(getDesignSidecarCandidates(cwd, contextDir));
-}
-
-export function getLiveDir(cwd = process.cwd()) {
-  return path.join(getImpeccableDir(cwd), LIVE_DIR);
-}
-
-export function getLiveConfigPath(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'config.json');
-}
-
-export function getLegacyLiveConfigPath(scriptsDir) {
-  return path.join(scriptsDir, 'config.json');
-}
-
-export function resolveLiveConfigPath({ cwd = process.cwd(), scriptsDir, env = process.env } = {}) {
-  if (env.IMPECCABLE_LIVE_CONFIG && env.IMPECCABLE_LIVE_CONFIG.trim()) {
-    const configured = env.IMPECCABLE_LIVE_CONFIG.trim();
-    return path.isAbsolute(configured) ? configured : path.resolve(cwd, configured);
-  }
-  const primary = getLiveConfigPath(cwd);
-  if (fs.existsSync(primary)) return primary;
-  if (scriptsDir) {
-    const legacy = getLegacyLiveConfigPath(scriptsDir);
-    if (fs.existsSync(legacy)) return legacy;
-  }
-  return primary;
-}
-
-export function getLiveServerPath(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'server.json');
-}
-
-export function getLegacyLiveServerPath(cwd = process.cwd()) {
-  return path.join(cwd, '.impeccable-live.json');
-}
-
-export function readLiveServerInfo(cwd = process.cwd()) {
-  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
-    try {
-      const info = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-      if (info && typeof info.pid === 'number' && !isLiveServerPidReachable(info.pid)) {
-        try { fs.unlinkSync(filePath); } catch {}
-        continue;
-      }
-      return { info, path: filePath };
-    } catch {
-      /* try next */
-    }
-  }
-  return null;
-}
-
-export function isLiveServerPidReachable(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    // ESRCH means "no such process". EPERM means the process exists but this
-    // user cannot signal it, so the live server info is still valid.
-    return err?.code !== 'ESRCH';
-  }
-}
-
-export function writeLiveServerInfo(cwd = process.cwd(), info) {
-  const filePath = getLiveServerPath(cwd);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(info));
-  return filePath;
-}
-
-export function removeLiveServerInfo(cwd = process.cwd()) {
-  for (const filePath of [getLiveServerPath(cwd), getLegacyLiveServerPath(cwd)]) {
-    try { fs.unlinkSync(filePath); } catch {}
-  }
-}
-
-export function getLiveSessionsDir(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'sessions');
-}
-
-export function getLegacyLiveSessionsDir(cwd = process.cwd()) {
-  return path.join(cwd, '.impeccable-live', 'sessions');
-}
-
-export function getLiveAnnotationsDir(cwd = process.cwd()) {
-  return path.join(getLiveDir(cwd), 'annotations');
-}
-
-export function getCritiqueDir(cwd = process.cwd()) {
-  return path.join(getImpeccableDir(cwd), CRITIQUE_DIR);
-}
-
-export function getLegacyLiveAnnotationsDir(cwd = process.cwd()) {
-  return path.join(cwd, '.impeccable-live', 'annotations');
-}
-
-function firstExisting(paths) {
-  return paths.find((filePath) => fs.existsSync(filePath)) || null;
-}

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

@@ -62,7 +62,7 @@ function parseYamlSubset(yaml) {
       stack.pop();
     }
 
-    const key = content.slice(0, colonIdx).trim();
+    const key = unquoteYamlKey(content.slice(0, colonIdx).trim());
     const rest = stripInlineYamlComment(content.slice(colonIdx + 1).trim());
     const parent = stack[stack.length - 1].obj;
 
@@ -93,6 +93,13 @@ function findTopLevelColon(s) {
   return -1;
 }
 
+function unquoteYamlKey(key) {
+  if ((key.startsWith('"') && key.endsWith('"')) || (key.startsWith("'") && key.endsWith("'"))) {
+    return key.slice(1, -1);
+  }
+  return key;
+}
+
 function stripInlineYamlComment(s) {
   let inQuote = null;
   for (let i = 0; i < s.length; i++) {

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

@@ -0,0 +1,640 @@
+/**
+ * CLI-side reader/writer for the unified `.impeccable` config.
+ *
+ * The CLI (published to npm) and the skill scripts (bundled into the install)
+ * live in separate trees and cannot share runtime code, so this duplicates a
+ * small slice of skill/scripts/hook-lib.mjs — the config-path layout, detector
+ * ignore semantics, and the `.git/info/exclude` handling. Keep the schema,
+ * ignore filtering, and exclude marker in sync if either side changes.
+ *
+ * Schema (config.json shared / config.local.json gitignored, per-developer):
+ *   {
+ *     "detector": { "ignoreRules": [], "ignoreFiles": [], "ignoreValues": [], "designSystem": { "enabled": true } },
+ *     "hook": { "consent": "accepted" | "declined", ... },
+ *     "updateCheck": bool
+ *   }
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { join, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+export function getConfigPath(root) {
+  return join(root, '.impeccable', 'config.json');
+}
+
+export function getLocalConfigPath(root) {
+  return join(root, '.impeccable', 'config.local.json');
+}
+
+function safeReadJson(filePath) {
+  try {
+    const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+function hookSection(raw) {
+  return raw && raw.hook && typeof raw.hook === 'object' && !Array.isArray(raw.hook) ? raw.hook : null;
+}
+
+function detectorSection(raw) {
+  return raw && raw.detector && typeof raw.detector === 'object' && !Array.isArray(raw.detector) ? raw.detector : null;
+}
+
+const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
+
+const DEFAULT_DETECTION_CONFIG = Object.freeze({
+  ignoreRules: [],
+  ignoreFiles: [],
+  ignoreValues: [],
+  designSystem: { enabled: true },
+});
+
+function cloneDetectionConfig() {
+  return {
+    ignoreRules: [],
+    ignoreFiles: [],
+    ignoreValues: [],
+    designSystem: { ...DEFAULT_DETECTION_CONFIG.designSystem },
+  };
+}
+
+function cloneRawDetectionConfig() {
+  return {
+    ignoreRules: [],
+    ignoreFiles: [],
+    ignoreValues: [],
+  };
+}
+
+function applyDetectionConfigSource(config, raw) {
+  if (!raw || typeof raw !== 'object') return config;
+  if (raw.designSystem && typeof raw.designSystem === 'object' && !Array.isArray(raw.designSystem)) {
+    config.designSystem = {
+      ...config.designSystem,
+      enabled: raw.designSystem.enabled === false ? false : true,
+    };
+  }
+  if (Array.isArray(raw.ignoreRules)) {
+    config.ignoreRules = uniqueStrings([...config.ignoreRules, ...raw.ignoreRules]);
+  }
+  if (Array.isArray(raw.ignoreFiles)) {
+    config.ignoreFiles = uniqueStrings([...config.ignoreFiles, ...raw.ignoreFiles]);
+  }
+  if (Array.isArray(raw.ignoreValues)) {
+    config.ignoreValues = mergeIgnoreValues(config.ignoreValues, raw.ignoreValues);
+  }
+  return config;
+}
+
+function uniqueStrings(values) {
+  return Array.from(new Set(values.map(String)));
+}
+
+/**
+ * Detector filters shared by `npx impeccable detect` and the design hook.
+ * `hook.enabled` remains hook lifecycle state; manual CLI scans still run when
+ * the hook is disabled, but they honor the same ignore rules and design-system
+ * toggle.
+ */
+export function readDetectionConfig(root) {
+  const config = cloneDetectionConfig();
+  for (const filePath of [getConfigPath(root), getLocalConfigPath(root)]) {
+    const raw = safeReadJson(filePath);
+    // Back-compat: old builds stored detector filters under hook.*.
+    applyDetectionConfigSource(config, hookSection(raw));
+    applyDetectionConfigSource(config, detectorSection(raw));
+  }
+  return config;
+}
+
+export function readRawDetectionConfig(root, opts = {}) {
+  const raw = safeReadJson(opts.local ? getLocalConfigPath(root) : getConfigPath(root));
+  const config = cloneRawDetectionConfig();
+  applyDetectionConfigSource(config, hookSection(raw));
+  applyDetectionConfigSource(config, detectorSection(raw));
+  return config;
+}
+
+export function writeDetectionConfig(root, detectorConfig, opts = {}) {
+  const filePath = opts.local ? getLocalConfigPath(root) : getConfigPath(root);
+  if (opts.local) ensureConfigGitExclude(root);
+  const existing = safeReadJson(filePath) || {};
+  const existingHook = hookSection(existing);
+  const nextHook = stripDetectorKeys(existingHook);
+  const nextDetector = {
+    ...(detectorSection(existing) || {}),
+    ...normalizeDetectionConfigForWrite(detectorConfig),
+  };
+  const next = {
+    ...existing,
+    detector: nextDetector,
+  };
+  if (nextHook && Object.keys(nextHook).length > 0) {
+    next.hook = nextHook;
+  } else {
+    delete next.hook;
+  }
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`);
+  return filePath;
+}
+
+function normalizeDetectionConfigForWrite(config) {
+  const out = {};
+  if (Array.isArray(config?.ignoreRules)) {
+    out.ignoreRules = uniqueStrings(config.ignoreRules.map((rule) => normalizeIgnoreRule(rule)).filter(Boolean));
+  }
+  if (Array.isArray(config?.ignoreFiles)) {
+    out.ignoreFiles = uniqueStrings(config.ignoreFiles.filter(v => typeof v === 'string' && v.trim()).map(v => v.trim()));
+  }
+  out.ignoreValues = normalizeIgnoreValueEntries(config?.ignoreValues || []);
+  if (config?.designSystem && typeof config.designSystem === 'object' && !Array.isArray(config.designSystem)) {
+    out.designSystem = {
+      enabled: config.designSystem.enabled === false ? false : true,
+    };
+  }
+  return out;
+}
+
+function stripDetectorKeys(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!DETECTOR_CONFIG_KEYS.has(key)) out[key] = value;
+  }
+  return out;
+}
+
+export function normalizeIgnoreValue(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+function normalizeIgnoreRule(rule) {
+  return String(rule || '').trim().toLowerCase();
+}
+
+function colorIgnoreKey(value) {
+  const color = parseIgnoreColor(value);
+  if (!color) return '';
+  return `${color.r},${color.g},${color.b},${Math.round(color.a * 255)}`;
+}
+
+function parseIgnoreColor(value) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return null;
+
+  const hex = text.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+  if (hex) return parseHexIgnoreColor(hex[1]);
+
+  const rgb = text.match(/^rgba?\((.*)\)$/i);
+  if (rgb) {
+    const parts = splitColorArgs(rgb[1]);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const r = parseRgbChannel(parts[0]);
+    const g = parseRgbChannel(parts[1]);
+    const b = parseRgbChannel(parts[2]);
+    const a = parts[3] === undefined ? 1 : parseAlphaChannel(parts[3]);
+    if ([r, g, b, a].some((v) => v === null)) return null;
+    return { r, g, b, a };
+  }
+
+  const hsl = text.match(/^hsla?\((.*)\)$/i);
+  if (hsl) {
+    const parts = splitColorArgs(hsl[1]);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const h = parseHueChannel(parts[0]);
+    const s = parsePercentChannel(parts[1]);
+    const l = parsePercentChannel(parts[2]);
+    const a = parts[3] === undefined ? 1 : parseAlphaChannel(parts[3]);
+    if ([h, s, l, a].some((v) => v === null)) return null;
+    return hslToRgb(h, s, l, a);
+  }
+
+  return null;
+}
+
+function parseHexIgnoreColor(hex) {
+  if (hex.length === 3 || hex.length === 4) {
+    const r = parseInt(hex[0] + hex[0], 16);
+    const g = parseInt(hex[1] + hex[1], 16);
+    const b = parseInt(hex[2] + hex[2], 16);
+    const a = hex.length === 4 ? parseInt(hex[3] + hex[3], 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a };
+}
+
+function splitColorArgs(body) {
+  const text = String(body || '').trim();
+  if (!text) return [];
+  if (text.includes(',')) {
+    const parts = text.split(',').map((part) => part.trim()).filter(Boolean);
+    const last = parts[parts.length - 1];
+    if (last && last.includes('/')) {
+      const split = last.split('/').map((part) => part.trim()).filter(Boolean);
+      return [...parts.slice(0, -1), ...split];
+    }
+    return parts;
+  }
+  return text.replace(/\s*\/\s*/g, ' / ').split(/\s+/).filter((part) => part && part !== '/');
+}
+
+function parseRgbChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(%)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const scaled = match[2] ? value * 2.55 : value;
+  if (scaled < 0 || scaled > 255) return null;
+  return Math.round(scaled);
+}
+
+function parseAlphaChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(%)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const alpha = match[2] ? value / 100 : value;
+  return alpha >= 0 && alpha <= 1 ? alpha : null;
+}
+
+function parseHueChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(deg|rad|turn|grad)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const unit = match[2] || 'deg';
+  if (unit === 'turn') return value * 360;
+  if (unit === 'rad') return value * (180 / Math.PI);
+  if (unit === 'grad') return value * 0.9;
+  return value;
+}
+
+function parsePercentChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)%$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  return value >= 0 && value <= 100 ? value / 100 : null;
+}
+
+function hslToRgb(hue, saturation, lightness, alpha) {
+  const h = (((hue % 360) + 360) % 360) / 360;
+  if (saturation === 0) {
+    const gray = clampByte(Math.round(lightness * 255));
+    return { r: gray, g: gray, b: gray, a: alpha };
+  }
+  const q = lightness < 0.5
+    ? lightness * (1 + saturation)
+    : lightness + saturation - lightness * saturation;
+  const p = 2 * lightness - q;
+  const toRgb = (t) => {
+    let channel = t;
+    if (channel < 0) channel += 1;
+    if (channel > 1) channel -= 1;
+    if (channel < 1 / 6) return p + (q - p) * 6 * channel;
+    if (channel < 1 / 2) return q;
+    if (channel < 2 / 3) return p + (q - p) * (2 / 3 - channel) * 6;
+    return p;
+  };
+  return {
+    r: clampByte(Math.round(toRgb(h + 1 / 3) * 255)),
+    g: clampByte(Math.round(toRgb(h) * 255)),
+    b: clampByte(Math.round(toRgb(h - 1 / 3) * 255)),
+    a: alpha,
+  };
+}
+
+function clampByte(value) {
+  return Math.min(255, Math.max(0, value));
+}
+
+function ignoreValueMatches(rule, entryValue, findingValue) {
+  if (entryValue === findingValue) return true;
+  if (rule !== 'design-system-color') return false;
+  const entryColor = colorIgnoreKey(entryValue);
+  return Boolean(entryColor && entryColor === colorIgnoreKey(findingValue));
+}
+
+export function normalizeIgnoreValueEntries(entries) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const rule = normalizeIgnoreRule(entry.rule);
+    const value = normalizeIgnoreValue(entry.value);
+    if (!rule || !value) continue;
+    const normalized = { rule, value };
+    const files = uniqueStrings([
+      ...(typeof entry.file === 'string' && entry.file.trim() ? [entry.file.trim()] : []),
+      ...(Array.isArray(entry.files) ? entry.files.filter(v => typeof v === 'string' && v.trim()).map(v => v.trim()) : []),
+    ]);
+    if (files.length > 0) normalized.files = files;
+    if (typeof entry.reason === 'string' && entry.reason.trim()) {
+      normalized.reason = entry.reason.trim();
+    }
+    if (typeof entry.createdAt === 'string' && entry.createdAt.trim()) {
+      normalized.createdAt = entry.createdAt.trim();
+    }
+    out.push(normalized);
+  }
+  return out;
+}
+
+function mergeIgnoreValues(existing, incoming) {
+  const map = new Map();
+  for (const entry of normalizeIgnoreValueEntries(existing)) {
+    map.set(`${entry.rule}\0${entry.value}\0${ignoreValueFilesKey(entry.files)}`, entry);
+  }
+  for (const entry of normalizeIgnoreValueEntries(incoming)) {
+    map.set(`${entry.rule}\0${entry.value}\0${ignoreValueFilesKey(entry.files)}`, entry);
+  }
+  return Array.from(map.values());
+}
+
+function ignoreValueFilesKey(files) {
+  return Array.isArray(files) && files.length > 0 ? files.join('\x1f') : '';
+}
+
+// Glob -> RegExp. Supports `**`, `*`, `?`, and `{a,b}` alternation.
+function globToRegex(glob) {
+  let re = '^';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i += 2;
+        if (glob[i] === '/') i += 1;
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else if (c === '{') {
+      const end = glob.indexOf('}', i);
+      if (end === -1) { re += '\\{'; i += 1; continue; }
+      const parts = glob.slice(i + 1, end).split(',').map((p) => p.replace(/[.+^$()|[\]\\]/g, '\\$&'));
+      re += `(?:${parts.join('|')})`;
+      i = end + 1;
+    } else if (/[.+^$()|[\]\\]/.test(c)) {
+      re += `\\${c}`;
+      i += 1;
+    } else {
+      re += c;
+      i += 1;
+    }
+  }
+  re += '$';
+  return new RegExp(re);
+}
+
+export function matchesAnyGlob(filePath, globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return false;
+  const normalized = String(filePath || '').split(sep).join('/');
+  for (const glob of globs) {
+    try {
+      const re = globToRegex(String(glob));
+      if (re.test(normalized)) return true;
+      const base = normalized.split('/').pop();
+      if (re.test(base)) return true;
+    } catch {
+      /* malformed glob, skip */
+    }
+  }
+  return false;
+}
+
+export function shouldIgnoreDetectionFile(filePath, root, config) {
+  const globs = config?.ignoreFiles || [];
+  if (!Array.isArray(globs) || globs.length === 0) return false;
+  const raw = String(filePath || '').trim();
+  if (!raw) return false;
+  if (matchesAnyGlob(raw, globs)) return true;
+
+  try {
+    const abs = isAbsolute(raw) ? raw : resolve(root, raw);
+    if (matchesAnyGlob(abs, globs)) return true;
+    const rel = relative(root, abs);
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+      return matchesAnyGlob(rel, globs);
+    }
+  } catch {
+    /* ignore */
+  }
+  return false;
+}
+
+export function filterDetectionFindings(findings, config) {
+  if (!Array.isArray(findings) || findings.length === 0) return [];
+  const ignoreRules = new Set((config?.ignoreRules || []).map((rule) => normalizeIgnoreRule(rule)));
+  const ignoreValues = normalizeIgnoreValueEntries(config?.ignoreValues || []);
+  return findings.filter((finding) => {
+    if (!finding || typeof finding !== 'object') return false;
+    if (ignoreRules.has(normalizeIgnoreRule(finding.antipattern))) return false;
+    if (isIgnoredFindingValue(finding, ignoreValues)) return false;
+    return true;
+  });
+}
+
+function isIgnoredFindingValue(finding, ignoreValues) {
+  if (!Array.isArray(ignoreValues) || ignoreValues.length === 0) return false;
+  const rule = normalizeIgnoreRule(finding.antipattern);
+  if (!rule) return false;
+  // File-scoped wildcards suppress rules with no extractable value, such as side-tab.
+  const value = extractFindingIgnoreValue(finding);
+  return ignoreValues.some((entry) => {
+    if (entry.rule !== rule) return false;
+    const wildcardValue = entry.value === '*';
+    if (!wildcardValue && (!value || !ignoreValueMatches(rule, entry.value, value))) return false;
+    if (!Array.isArray(entry.files) || entry.files.length === 0) return !wildcardValue;
+    return findingMatchesScopedIgnoreFile(finding, entry.files);
+  });
+}
+
+function findingMatchesScopedIgnoreFile(finding, globs) {
+  const filePath = String(finding?.file || '').trim();
+  if (!filePath) return false;
+  if (matchesAnyGlob(filePath, globs)) return true;
+
+  const normalized = filePath.split(sep).join('/');
+  const parts = normalized.split('/').filter(Boolean);
+  for (let i = 0; i < parts.length; i++) {
+    const suffix = parts.slice(i).join('/');
+    if (matchesAnyGlob(suffix, globs)) return true;
+  }
+  return false;
+}
+
+export function extractFindingIgnoreValue(finding) {
+  if (!finding || typeof finding !== 'object') return '';
+  const rule = normalizeIgnoreRule(finding.antipattern);
+  const directValueRules = new Set([
+    'overused-font',
+    'bounce-easing',
+    'design-system-font',
+    'design-system-color',
+    'design-system-radius',
+  ]);
+  if (!directValueRules.has(rule)) return '';
+  return normalizeIgnoreValue(extractFindingIgnoreValueRaw(finding, rule));
+}
+
+function extractFindingIgnoreValueRaw(finding, rule = normalizeIgnoreRule(finding?.antipattern)) {
+  const direct = cleanIgnoreValueDisplay(finding.ignoreValue || finding.value || '');
+  if (direct) return direct;
+
+  const candidates = [finding.detail, finding.snippet].filter((v) => typeof v === 'string' && v);
+  for (const text of candidates) {
+    if (rule === 'bounce-easing') {
+      const motion = extractMotionIgnoreValue(text);
+      if (motion) return motion;
+      continue;
+    }
+
+    const primary = text.match(/Primary font:\s*([^()\n;]+)/i);
+    if (primary) return cleanIgnoreValueDisplay(primary[1]);
+
+    const family = text.match(/font-family\s*:\s*["']?([^'",;\n]+)/i);
+    if (family) return cleanIgnoreValueDisplay(family[1]);
+
+    const google = text.match(/[?&]family=([^&:;\n]+)/i);
+    if (google) {
+      try {
+        return cleanIgnoreValueDisplay(decodeURIComponent(google[1]));
+      } catch {
+        return cleanIgnoreValueDisplay(google[1]);
+      }
+    }
+  }
+
+  return '';
+}
+
+function extractMotionIgnoreValue(text) {
+  const tailwind = text.match(/\banimate-bounce\b/i);
+  if (tailwind) return cleanIgnoreValueDisplay(tailwind[0]);
+
+  const bezier = text.match(/cubic-bezier\([^)]+\)/i);
+  if (bezier) return cleanIgnoreValueDisplay(bezier[0]);
+
+  const animation = text.match(/animation(?:-name)?\s*:\s*([^;\n]+)/i);
+  if (animation) {
+    const token = animation[1]
+      .split(/[,\s]+/)
+      .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
+    if (token) return cleanIgnoreValueDisplay(token);
+  }
+
+  return '';
+}
+
+function cleanIgnoreValueDisplay(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\+/g, ' ')
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * The recorded design-hook decision: 'accepted' | 'declined' | undefined.
+ * config.local.json (per-developer) overrides config.json.
+ */
+export function getHookConsent(root) {
+  let consent;
+  for (const filePath of [getConfigPath(root), getLocalConfigPath(root)]) {
+    const hook = hookSection(safeReadJson(filePath));
+    if (hook && (hook.consent === 'accepted' || hook.consent === 'declined')) consent = hook.consent;
+  }
+  return consent;
+}
+
+/**
+ * Persist the per-developer decision to config.local.json, preserving any
+ * sibling keys, and ensure the file is gitignored.
+ */
+export function setHookConsent(root, value) {
+  const filePath = getLocalConfigPath(root);
+  const existing = safeReadJson(filePath) || {};
+  const hook = hookSection(existing) || {};
+  const next = { ...existing, hook: { ...hook, consent: value } };
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`);
+  ensureConfigGitExclude(root);
+  return filePath;
+}
+
+const EXCLUDE_OPEN = '# impeccable-config-ignore-start';
+const EXCLUDE_CLOSE = '# impeccable-config-ignore-end';
+const EXCLUDE_PATTERNS = ['.impeccable/config.local.json'];
+
+/**
+ * Add config.local.json to `.git/info/exclude` so a developer's decision is
+ * never committed. Idempotent via marker comments. Best-effort; returns false
+ * when there is no resolvable git dir.
+ */
+export function ensureConfigGitExclude(root) {
+  try {
+    const gitDir = resolveGitDir(root);
+    if (!gitDir) return false;
+    const target = join(gitDir, 'info', 'exclude');
+    const existing = existsSync(target) ? readFileSync(target, 'utf-8') : '';
+    const block = [EXCLUDE_OPEN, ...EXCLUDE_PATTERNS, EXCLUDE_CLOSE].join('\n');
+    const markerRe = new RegExp(`${escapeRegExp(EXCLUDE_OPEN)}[\\s\\S]*?${escapeRegExp(EXCLUDE_CLOSE)}`);
+    let updated;
+    if (markerRe.test(existing)) {
+      updated = existing.replace(markerRe, block);
+    } else {
+      const prefix = existing.length === 0 ? '' : existing.endsWith('\n') ? existing : `${existing}\n`;
+      updated = `${prefix}${block}\n`;
+    }
+    if (updated !== existing) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, updated);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveGitDir(root) {
+  const dotGit = join(root, '.git');
+  if (!existsSync(dotGit)) return null;
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+    // A `.git` file (worktree/submodule) points elsewhere: "gitdir: <path>".
+    const match = readFileSync(dotGit, 'utf-8').match(/gitdir:\s*(.+)/);
+    if (match) {
+      const resolved = match[1].trim();
+      return isAbsolute(resolved) ? resolved : join(root, resolved);
+    }
+  } catch {
+    /* fall through */
+  }
+  return null;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectRoot } from '../context.mjs';
+export { IMPECCABLE_COMMAND_PREFIX } from './provider.mjs';
+
+export const IMPECCABLE_DIR = '.impeccable';
+export const LIVE_DIR = 'live';
+export const CRITIQUE_DIR = 'critique';
+
+export function getImpeccableDir(cwd = process.cwd(), options = {}) {
+  return path.join(resolveProjectRoot(cwd, options), IMPECCABLE_DIR);
+}
+
+export function getDesignSidecarPath(cwd = process.cwd(), options = {}) {
+  return path.join(getImpeccableDir(cwd, options), 'design.json');
+}
+
+export function getDesignSidecarCandidates(cwd = process.cwd(), contextDir = cwd, options = {}) {
+  const projectRoot = resolveProjectRoot(cwd, options);
+  const candidates = [
+    getDesignSidecarPath(cwd, options),
+    path.join(projectRoot, 'DESIGN.json'),
+  ];
+  const contextLegacy = path.join(contextDir, 'DESIGN.json');
+  if (!candidates.includes(contextLegacy)) candidates.push(contextLegacy);
+  return candidates;
+}
+
+export function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd, options = {}) {
+  return firstExisting(getDesignSidecarCandidates(cwd, contextDir, options));
+}
+
+export function getLiveDir(cwd = process.cwd(), options = {}) {
+  return path.join(getImpeccableDir(cwd, options), LIVE_DIR);
+}
+
+export function getLiveConfigPath(cwd = process.cwd(), options = {}) {
+  return path.join(getLiveDir(cwd, options), 'config.json');
+}
+
+export function getLegacyLiveConfigPath(scriptsDir) {
+  return path.join(scriptsDir, 'config.json');
+}
+
+export function resolveLiveConfigPath({ cwd = process.cwd(), scriptsDir, env = process.env, targetPath } = {}) {
+  if (env.IMPECCABLE_LIVE_CONFIG && env.IMPECCABLE_LIVE_CONFIG.trim()) {
+    const configured = env.IMPECCABLE_LIVE_CONFIG.trim();
+    return path.isAbsolute(configured) ? configured : path.resolve(cwd, configured);
+  }
+  const primary = getLiveConfigPath(cwd, { targetPath });
+  if (fs.existsSync(primary)) return primary;
+  if (scriptsDir) {
+    const legacy = getLegacyLiveConfigPath(scriptsDir);
+    if (fs.existsSync(legacy)) return legacy;
+  }
+  return primary;
+}
+
+export function getLiveServerPath(cwd = process.cwd(), options = {}) {
+  return path.join(getLiveDir(cwd, options), 'server.json');
+}
+
+export function getLegacyLiveServerPath(cwd = process.cwd(), options = {}) {
+  return path.join(resolveProjectRoot(cwd, options), '.impeccable-live.json');
+}
+
+export function readLiveServerInfo(cwd = process.cwd(), options = {}) {
+  for (const filePath of [getLiveServerPath(cwd, options), getLegacyLiveServerPath(cwd, options)]) {
+    try {
+      const info = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      if (info && typeof info.pid === 'number' && !isLiveServerPidReachable(info.pid)) {
+        try { fs.unlinkSync(filePath); } catch {}
+        continue;
+      }
+      return { info, path: filePath };
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+export function isLiveServerPidReachable(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH means "no such process". EPERM means the process exists but this
+    // user cannot signal it, so the live server info is still valid.
+    return err?.code !== 'ESRCH';
+  }
+}
+
+export function writeLiveServerInfo(cwd = process.cwd(), info, options = {}) {
+  const filePath = getLiveServerPath(cwd, options);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(info));
+  return filePath;
+}
+
+export function removeLiveServerInfo(cwd = process.cwd(), options = {}) {
+  for (const filePath of [getLiveServerPath(cwd, options), getLegacyLiveServerPath(cwd, options)]) {
+    try { fs.unlinkSync(filePath); } catch {}
+  }
+}
+
+export function getLiveSessionsDir(cwd = process.cwd(), options = {}) {
+  return path.join(getLiveDir(cwd, options), 'sessions');
+}
+
+export function getLegacyLiveSessionsDir(cwd = process.cwd(), options = {}) {
+  return path.join(resolveProjectRoot(cwd, options), '.impeccable-live', 'sessions');
+}
+
+export function getLiveAnnotationsDir(cwd = process.cwd(), options = {}) {
+  return path.join(getLiveDir(cwd, options), 'annotations');
+}
+
+export function getCritiqueDir(cwd = process.cwd(), options = {}) {
+  return path.join(getImpeccableDir(cwd, options), CRITIQUE_DIR);
+}
+
+export function getLegacyLiveAnnotationsDir(cwd = process.cwd(), options = {}) {
+  return path.join(resolveProjectRoot(cwd, options), '.impeccable-live', 'annotations');
+}
+
+function firstExisting(paths) {
+  return paths.find((filePath) => fs.existsSync(filePath)) || null;
+}

.agents/skills/impeccable/scripts/lib/provider.mjs

@@ -0,0 +1,4 @@
+// Source scripts default to slash commands. The provider build replaces only
+// this exact declaration, avoiding heuristic rewrites across executable code.
+export const IMPECCABLE_COMMAND_PREFIX = "$";
+export const IMPECCABLE_COMMAND = `${IMPECCABLE_COMMAND_PREFIX}impeccable`;

.agents/skills/impeccable/scripts/lib/target-args.mjs

@@ -0,0 +1,42 @@
+class TargetArgError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'TargetArgError';
+    this.code = code;
+  }
+}
+
+export function parseTargetPath(args = [], { strict = false } = {}) {
+  let targetPath = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i]);
+    if (arg === '--target' || arg === '-t') {
+      const next = args[i + 1];
+      if (next && !String(next).startsWith('-')) {
+        targetPath = String(next);
+        i++;
+        continue;
+      }
+      if (strict) {
+        throw new TargetArgError('--target requires a path value.', 'TARGET_VALUE_MISSING');
+      }
+      continue;
+    }
+    if (arg.startsWith('--target=')) {
+      const value = arg.slice('--target='.length);
+      if (value) {
+        targetPath = value;
+        continue;
+      }
+      if (strict) {
+        throw new TargetArgError('--target requires a path value.', 'TARGET_VALUE_MISSING');
+      }
+    }
+  }
+  return targetPath;
+}
+
+export function parseTargetOptions(args = [], options = {}) {
+  const targetPath = parseTargetPath(args, options);
+  return targetPath ? { targetPath } : {};
+}

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

@@ -15,8 +15,14 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isGeneratedFile } from './is-generated.mjs';
-import { readBuffer as readManualEditsBuffer, writeBuffer as writeManualEditsBuffer } from './live-manual-edits-buffer.mjs';
+import { isGeneratedFile } from './lib/is-generated.mjs';
+import { readBuffer as readManualEditsBuffer, writeBuffer as writeManualEditsBuffer } from './live/manual-edits-buffer.mjs';
+import {
+  applyDeferredSvelteComponentAccepts,
+  findSvelteComponentManifest,
+  inlineSvelteComponentAccept,
+  removeSvelteComponentSession,
+} from './live/svelte-component.mjs';
 
 const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
 
@@ -41,6 +47,9 @@ Required:
 
 Options:
   --page-url URL     Current browser page URL; scopes staged copy-edit cleanup
+  --defer-source-write
+                     Deprecated compatibility flag. Svelte component accepts
+                     now write the real source immediately.
 
 Output (JSON):
   { handled, file, carbonize }`);
@@ -64,18 +73,67 @@ Output (JSON):
 
   // Find the file containing this session's markers
   const found = findSessionFile(id, process.cwd());
-  if (!found) {
+  const svelteComponentManifest = found ? null : findSvelteComponentManifest(id, process.cwd());
+
+  if (!found && !svelteComponentManifest) {
     console.log(JSON.stringify({ handled: false, error: 'Session markers not found for id: ' + id }));
     process.exit(0);
   }
 
+  if (svelteComponentManifest) {
+    if (isDiscard) {
+      removeSvelteComponentSession(id, process.cwd());
+      console.log(JSON.stringify({
+        handled: true,
+        file: svelteComponentManifest.sourceFile,
+        carbonize: false,
+        previewMode: 'svelte-component',
+        componentDir: svelteComponentManifest.componentDir,
+      }));
+      return;
+    }
+
+    let result;
+    try {
+      result = inlineSvelteComponentAccept(
+        svelteComponentManifest,
+        variantNum,
+        paramValues,
+        process.cwd(),
+      );
+    } catch (err) {
+      result = {
+        handled: false,
+        error: err.message,
+        file: svelteComponentManifest.sourceFile,
+        sourceFile: svelteComponentManifest.sourceFile,
+        previewMode: 'svelte-component',
+        componentDir: svelteComponentManifest.componentDir,
+      };
+    }
+    if (result.carbonize) {
+      result.todo = 'REQUIRED before next poll: carbonize cleanup in ' + result.file + '. See reference/live.md "Required after accept".';
+    }
+    console.log(JSON.stringify({ handled: result.handled !== false, ...result }));
+    return;
+  }
+
   const { file: targetFile, content, lines } = found;
   const relFile = path.relative(process.cwd(), targetFile);
+  const previewBlock = findMarkerBlock(id, lines);
+  const sourceShadowPreview = previewBlock
+    ? readSourceShadowPreviewMeta(content, id)
+    : null;
+
+  if (sourceShadowPreview) {
+    console.log(JSON.stringify({
+      handled: false,
+      error: 'source_shadow_preview_deprecated',
+      hint: 'Svelte live mode now uses svelte-component injection. Re-wrap the element and regenerate variants.',
+    }));
+    process.exit(0);
+  }
 
-  // Bail if the session lives in a generated file. The agent manually wrote
-  // the wrapper there for preview, and is responsible for writing the
-  // accepted variant to true source (or cleaning up on discard). See
-  // "Handle fallback" in live.md.
   if (isGeneratedFile(targetFile, { cwd: process.cwd() })) {
     console.log(JSON.stringify({
       handled: false,
@@ -207,6 +265,71 @@ function handleDiscard(id, lines, targetFile) {
 // Accept
 // ---------------------------------------------------------------------------
 
+/**
+ * Build carbonize stitch-in lines. JSX targets occupy a single child slot
+ * (ternary branch, return value, etc.) — the same constraint as live-wrap.
+ * When isJsx, tuck markers + <style> + variant wrapper inside one outer
+ * <div data-impeccable-carbonize> so the slot keeps a single root node.
+ */
+function buildCarbonizeReplacement({
+  indent,
+  commentSyntax,
+  isJsx,
+  id,
+  variantNum,
+  cssContent,
+  paramValues,
+  restored,
+}) {
+  const lines = [];
+  if (!cssContent) {
+    lines.push(...restored);
+    return lines;
+  }
+
+  const variantStyleAttr = isJsx
+    ? "style={{ display: 'contents' }}"
+    : 'style="display: contents"';
+
+  const pushCarbonizeBody = (bodyIndent) => {
+    const bodyRestored = reindentContent(restored, indent, bodyIndent + '  ');
+    lines.push(bodyIndent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
+    lines.push(bodyIndent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
+    for (const cssLine of cssContent) {
+      lines.push(bodyIndent + cssLine.trimStart());
+    }
+    lines.push(bodyIndent + (isJsx ? '`}</style>' : '</style>'));
+    if (paramValues && Object.keys(paramValues).length > 0) {
+      lines.push(
+        bodyIndent + commentSyntax.open + ' impeccable-param-values ' + id + ': ' + JSON.stringify(paramValues) + ' ' + commentSyntax.close,
+      );
+    }
+    lines.push(bodyIndent + commentSyntax.open + ' impeccable-carbonize-end ' + id + ' ' + commentSyntax.close);
+    lines.push(bodyIndent + '<div data-impeccable-variant="' + variantNum + '" ' + variantStyleAttr + '>');
+    lines.push(...bodyRestored);
+    lines.push(bodyIndent + '</div>');
+  };
+
+  if (isJsx) {
+    const wrapperStyle = 'style={{ display: "contents" }}';
+    lines.push(indent + '<div data-impeccable-carbonize="' + id + '" ' + wrapperStyle + '>');
+    pushCarbonizeBody(indent + '  ');
+    lines.push(indent + '</div>');
+  } else {
+    pushCarbonizeBody(indent);
+  }
+
+  return lines;
+}
+
+function reindentContent(contentLines, fromIndent, toIndent) {
+  return contentLines.map((line) => {
+    if (line.trim() === '') return '';
+    if (line.startsWith(fromIndent)) return toIndent + line.slice(fromIndent.length);
+    return toIndent + line.trimStart();
+  });
+}
+
 function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const block = findMarkerBlock(id, lines);
   if (!block) return { handled: false, error: 'Markers not found' };
@@ -235,45 +358,17 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   const hasHelperAttrs = variantText.includes('data-impeccable-variant');
   const needsCarbonize = !!(cssContent || hasHelperAttrs);
 
-  // Build the replacement
   const restored = deindentContent(variantContent, indent);
-  const replacement = [];
-
-  if (cssContent) {
-    replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
-    // JSX targets need the CSS body wrapped in a template literal so that the
-    // `{` and `}` in CSS rules don't get parsed as JSX expressions.
-    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
-    // Re-indent CSS content to match
-    for (const cssLine of cssContent) {
-      replacement.push(indent + cssLine.trimStart());
-    }
-    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
-    if (paramValues && Object.keys(paramValues).length > 0) {
-      // Preserve the user's knob positions for the carbonize-cleanup agent
-      // to bake into the final CSS when it collapses scoped rules.
-      replacement.push(indent + commentSyntax.open + ' impeccable-param-values ' + id + ': ' + JSON.stringify(paramValues) + ' ' + commentSyntax.close);
-    }
-    replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-end ' + id + ' ' + commentSyntax.close);
-  }
-
-  // Keep the `@scope ([data-impeccable-variant="N"])` selectors in the
-  // carbonize CSS block working visually by re-wrapping the accepted content
-  // in a data-impeccable-variant="N" div with `display: contents` (so layout
-  // isn't affected). The carbonize agent strips this attribute + wrapper when
-  // it moves the CSS to a proper stylesheet.
-  //
-  // Style attribute syntax has to follow the host file's flavor — JSX files
-  // need the object form, otherwise React 19 throws "Failed to set indexed
-  // property [0] on CSSStyleDeclaration" while parsing the string char-by-char.
-  if (cssContent) {
-    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
-    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
-    replacement.push(...restored);
-    replacement.push(indent + '</div>');
-  } else {
-    replacement.push(...restored);
-  }
+  const replacement = buildCarbonizeReplacement({
+    indent,
+    commentSyntax,
+    isJsx,
+    id,
+    variantNum,
+    cssContent,
+    paramValues,
+    restored,
+  });
 
   const newLines = [
     ...lines.slice(0, replaceRange.start),
@@ -285,6 +380,34 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
   return { carbonize: needsCarbonize, acceptedOriginalText: originalContent.join('\n') };
 }
 
+function readSourceShadowPreviewMeta(content, id) {
+  const escaped = escapeRegExp(id);
+  const wrapperRe = new RegExp('<[^>]+data-impeccable-variants=(["\'])' + escaped + '\\1[^>]*>');
+  const match = String(content || '').match(wrapperRe);
+  if (!match) return null;
+  const tag = match[0];
+  if (readHtmlAttr(tag, 'data-impeccable-preview') !== 'source-shadow') return null;
+  const sourceFile = readHtmlAttr(tag, 'data-impeccable-source-file');
+  const sourceStartLine = Number(readHtmlAttr(tag, 'data-impeccable-source-start'));
+  const sourceEndLine = Number(readHtmlAttr(tag, 'data-impeccable-source-end'));
+  if (!sourceFile || !Number.isFinite(sourceStartLine) || !Number.isFinite(sourceEndLine)) return null;
+  return { sourceFile, sourceStartLine, sourceEndLine };
+}
+
+function readHtmlAttr(tag, name) {
+  const match = String(tag || '').match(new RegExp('\\s' + escapeRegExp(name) + '\\s*=\\s*(["\'])(.*?)\\1'));
+  if (!match) return null;
+  return decodeHtmlAttr(match[2]);
+}
+
+function decodeHtmlAttr(value) {
+  return String(value || '')
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
 // ---------------------------------------------------------------------------
 // Parsing helpers
 // ---------------------------------------------------------------------------
@@ -686,4 +809,4 @@ if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs
   acceptCli();
 }
 
-export { findMarkerBlock, extractOriginal, extractVariant, extractCss, deindentContent, detectCommentSyntax, scrubManualEditsAgainstFile, scrubManualEditsAgainstOriginalBlock };
+export { findMarkerBlock, extractOriginal, extractVariant, extractCss, deindentContent, detectCommentSyntax, scrubManualEditsAgainstFile, scrubManualEditsAgainstOriginalBlock, applyDeferredSvelteComponentAccepts };

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

@@ -0,0 +1,146 @@
+/**
+ * Browser-side DOM helpers for Impeccable live mode.
+ *
+ * Kept separate from live-browser.js so future browser script parts can share
+ * chrome mounting, lookup, focus, and picker helpers without depending on the
+ * full overlay UI bundle.
+ */
+(function (root) {
+  'use strict';
+  if (!root) return;
+
+  function createLiveBrowserDomHelpers({
+    prefix,
+    skipTags,
+    document: doc = root.document,
+    css = root.CSS,
+    crypto = root.crypto,
+  } = {}) {
+    if (!prefix) throw new Error('prefix required');
+    if (!doc) throw new Error('document required');
+    const tagsToSkip = skipTags || new Set();
+
+    function own(el) {
+      return el && (el.id?.startsWith(prefix) || el.closest?.('[id^="' + prefix + '"]'));
+    }
+
+    function pickable(el) {
+      if (!el || el.nodeType !== 1) return false;
+      if (tagsToSkip.has(String(el.tagName || '').toLowerCase())) return false;
+      if (own(el)) return false;
+      const r = el.getBoundingClientRect();
+      return r.width >= 20 && r.height >= 20;
+    }
+
+    function desc(el) {
+      if (!el) return '';
+      let s = el.tagName.toLowerCase();
+      if (el.id) s += '#' + el.id;
+      else if (el.classList.length) s += '.' + [...el.classList].slice(0, 2).join('.');
+      return s;
+    }
+
+    function rectIsUsableAnchor(rect) {
+      return !!rect && rect.width > 0.5 && rect.height > 0.5;
+    }
+
+    function makeFrozenAnchor(el) {
+      if (!el || !el.getBoundingClientRect) return null;
+      const r = el.getBoundingClientRect();
+      if (!rectIsUsableAnchor(r)) return null;
+      const rect = {
+        x: r.x, y: r.y,
+        top: r.top, left: r.left,
+        right: r.right, bottom: r.bottom,
+        width: r.width, height: r.height,
+      };
+      return {
+        __impeccableFrozenAnchor: true,
+        tagName: el.tagName || 'DIV',
+        id: el.id || '',
+        classList: el.classList ? [...el.classList] : [],
+        hasAttribute: () => false,
+        getBoundingClientRect: () => rect,
+      };
+    }
+
+    function id8() {
+      if (crypto?.randomUUID) return crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+      return (Math.random().toString(16).slice(2) + Date.now().toString(16)).slice(0, 8);
+    }
+
+    function cssId(id) {
+      if (css?.escape) return css.escape(id);
+      return String(id).replace(/([ !"#$%&'()*+,./:;<=>?@[\\\]^`{|}~])/g, '\\$1');
+    }
+
+    function liveUiRoot() {
+      const uiRoot = root.__IMPECCABLE_LIVE_UI_ROOT__;
+      if (uiRoot && typeof uiRoot.appendChild === 'function') return uiRoot;
+      return doc.body;
+    }
+
+    function uiAppend(el) {
+      liveUiRoot().appendChild(el);
+      return el;
+    }
+
+    function uiAppendStyle(styleEl) {
+      const uiRoot = liveUiRoot();
+      if (uiRoot && uiRoot !== doc.body) uiRoot.appendChild(styleEl);
+      else doc.head.appendChild(styleEl);
+      return styleEl;
+    }
+
+    function uiGetById(id) {
+      const uiRoot = liveUiRoot();
+      if (uiRoot?.getElementById) {
+        const found = uiRoot.getElementById(id);
+        if (found) return found;
+      }
+      if (uiRoot?.querySelector) {
+        const found = uiRoot.querySelector('#' + cssId(id));
+        if (found) return found;
+      }
+      return doc.getElementById(id);
+    }
+
+    function activeElementDeep() {
+      let active = doc.activeElement;
+      while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+      return active;
+    }
+
+    function defangOutsideHandlers(rootEl, { setPointerEvents = true } = {}) {
+      if (!rootEl) return;
+      if (setPointerEvents) {
+        rootEl.style.setProperty('pointer-events', 'auto', 'important');
+      }
+      const stop = (e) => e.stopPropagation();
+      rootEl.addEventListener('pointerdown', stop);
+      rootEl.addEventListener('mousedown', stop);
+      rootEl.addEventListener('focusin', stop);
+    }
+
+    return {
+      own,
+      pickable,
+      desc,
+      rectIsUsableAnchor,
+      makeFrozenAnchor,
+      id8,
+      cssId,
+      liveUiRoot,
+      uiAppend,
+      uiAppendStyle,
+      uiGetById,
+      activeElementDeep,
+      defangOutsideHandlers,
+    };
+  }
+
+  root.__IMPECCABLE_LIVE_DOM__ = {
+    version: 1,
+    createLiveBrowserDomHelpers,
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

.agents/skills/impeccable/scripts/live-commit-manual-edits.mjs

@@ -16,8 +16,8 @@
  */
 
 import { buildManualEditEvidence } from './live-manual-edit-evidence.mjs';
-import { readBuffer, readBufferStrict, writeBuffer, countByPage } from './live-manual-edits-buffer.mjs';
-import { isGeneratedFile } from './is-generated.mjs';
+import { readBuffer, readBufferStrict, writeBuffer, countByPage } from './live/manual-edits-buffer.mjs';
+import { isGeneratedFile } from './lib/is-generated.mjs';
 import {
   runCopyEditBatchAgent,
   runCopyEditPostApplyChecks,

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

@@ -3,8 +3,8 @@
  * Canonical durable completion acknowledgement for Impeccable live sessions.
  */
 
-import { createLiveSessionStore } from './live-session-store.mjs';
-import { readLiveServerInfo } from './impeccable-paths.mjs';
+import { createLiveSessionStore } from './live/session-store.mjs';
+import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
 
 function parseArgs(argv) {
   const out = { status: 'complete' };

.agents/skills/impeccable/scripts/live-discard-manual-edits.mjs

@@ -16,7 +16,7 @@
  * Output JSON: { discarded: N, entries: [...discardedEntries], totalCount: N }
  */
 
-import { readBuffer, removeEntries, truncateBuffer } from './live-manual-edits-buffer.mjs';
+import { readBuffer, removeEntries, truncateBuffer } from './live/manual-edits-buffer.mjs';
 
 function argVal(args, name) {
   const prefix = name + '=';

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

@@ -16,12 +16,41 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveLiveConfigPath } from './impeccable-paths.mjs';
+import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
+import {
+  applySvelteKitLiveAdapter,
+  detectSvelteKitProject,
+  removeSvelteKitLiveAdapter,
+} from './live/sveltekit-adapter.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 IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
+const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
+
+export const LIVE_IGNORE_PATTERNS = Object.freeze([
+  '.impeccable/hook.cache.json',
+  '.impeccable/hook.pending.json',
+  '.impeccable/config.local.json',
+  '.impeccable/live/server.json',
+  '.impeccable/live/sessions/',
+  '.impeccable/live/previews/',
+  '.impeccable/live/annotations/',
+  '.impeccable/live/cache/',
+  '.impeccable/live/manual-edit-apply-transaction.json',
+  '.impeccable/live/manual-edit-events.jsonl',
+  '.impeccable/live/manual-edit-evidence/',
+  '.impeccable/live/pending-manual-edits.json',
+  '.impeccable/live/deferred-svelte-component-accepts.json',
+  '.impeccable-live.json',
+  '.impeccable-live/',
+  'node_modules/.impeccable-live/',
+  'src/lib/impeccable/ImpeccableLiveRoot.svelte',
+  'src/lib/impeccable/__runtime.js',
+  'src/lib/impeccable/[0-9a-f]*/',
+]);
 
 /**
  * Hard-excluded directory patterns. These are NEVER user-facing pages and
@@ -83,8 +112,14 @@ Output (JSON):
   validateConfig(config);
 
   const resolvedFiles = resolveFiles(process.cwd(), config);
+  const svelteKit = detectSvelteKitProject(process.cwd(), config);
 
   if (args.includes('--remove')) {
+    if (svelteKit) {
+      const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
+      console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
+      return;
+    }
     const results = resolvedFiles.map((relFile) => {
       const absFile = path.resolve(process.cwd(), relFile);
       if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
@@ -110,6 +145,13 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  const gitIgnore = ensureLiveGitIgnores(process.cwd());
+
+  if (svelteKit) {
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
+    return;
+  }
 
   const results = resolvedFiles.map((relFile) => {
     const absFile = path.resolve(process.cwd(), relFile);
@@ -129,10 +171,68 @@ Output (JSON):
     };
   });
   const anyInserted = results.some((r) => r.inserted);
-  console.log(JSON.stringify({ ok: anyInserted, port, results }));
+  console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
   if (!anyInserted) process.exit(1);
 }
 
+export function ensureLiveGitIgnores(cwd = process.cwd()) {
+  const target = resolveIgnoreTarget(cwd);
+  const existing = fs.existsSync(target.path) ? fs.readFileSync(target.path, 'utf-8') : '';
+  const block = [
+    IGNORE_MARKER_OPEN,
+    ...LIVE_IGNORE_PATTERNS,
+    IGNORE_MARKER_CLOSE,
+  ].join('\n');
+  const markerRe = new RegExp(`${escapeRegExp(IGNORE_MARKER_OPEN)}[\\s\\S]*?${escapeRegExp(IGNORE_MARKER_CLOSE)}`);
+
+  let updated;
+  if (markerRe.test(existing)) {
+    updated = existing.replace(markerRe, block);
+  } else {
+    const prefix = existing.length === 0 ? '' : existing.endsWith('\n') ? existing : existing + '\n';
+    updated = `${prefix}${prefix.endsWith('\n\n') || prefix === '' ? '' : '\n'}${block}\n`;
+  }
+
+  if (updated !== existing) {
+    fs.mkdirSync(path.dirname(target.path), { recursive: true });
+    fs.writeFileSync(target.path, updated, 'utf-8');
+  }
+
+  return {
+    file: path.relative(cwd, target.path).split(path.sep).join('/'),
+    mode: target.mode,
+    changed: updated !== existing,
+    patterns: [...LIVE_IGNORE_PATTERNS],
+  };
+}
+
+function resolveIgnoreTarget(cwd) {
+  const gitExcludePath = resolveGitInfoExcludePath(cwd);
+  if (gitExcludePath) {
+    return { path: gitExcludePath, mode: 'git-info-exclude' };
+  }
+  return { path: path.join(cwd, '.gitignore'), mode: 'gitignore' };
+}
+
+function resolveGitInfoExcludePath(cwd) {
+  const dotGit = path.join(cwd, '.git');
+  if (!fs.existsSync(dotGit)) return null;
+
+  const stat = fs.statSync(dotGit);
+  if (stat.isDirectory()) return path.join(dotGit, 'info', 'exclude');
+  if (!stat.isFile()) return null;
+
+  const body = fs.readFileSync(dotGit, 'utf-8').trim();
+  const match = body.match(/^gitdir:\s*(.+)$/i);
+  if (!match) return null;
+  const gitDir = path.isAbsolute(match[1]) ? match[1] : path.resolve(cwd, match[1]);
+  return path.join(gitDir, 'info', 'exclude');
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  * Expand config.files (which may contain glob patterns) into a literal list
  * of existing file paths relative to rootDir. Literal entries pass through;
@@ -270,8 +370,26 @@ function buildTagBlock(syntax, port, filePath) {
   );
 }
 
+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) {
-  const block = buildTagBlock(config.commentSyntax, port, filePath);
+  const lineEnding = detectLineEnding(content);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), 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.
@@ -285,9 +403,15 @@ function insertTag(content, config, port, filePath) {
   const idx = content.indexOf(config.insertAfter);
   if (idx === -1) return content;
   const after = idx + config.insertAfter.length;
-  // Preserve a single trailing newline if the anchor didn't end with one
-  const prefix = content[after] === '\n' ? content.slice(0, after + 1) : content.slice(0, after) + '\n';
-  return prefix + block + content.slice(prefix.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;
 }
 
 /**
@@ -303,8 +427,8 @@ function insertTag(content, config, port, filePath) {
  */
 function removeTag(content, _syntax) {
   const patterns = [
-    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\n|$)?)/,
-    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\n|$)?)/,
+    /([ \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;
@@ -312,7 +436,7 @@ function removeTag(content, _syntax) {
     do {
       content = next;
       next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
-        if (trailing.includes('\n')) return leadingIndent;
+        if (/[\r\n]/.test(trailing)) return leadingIndent;
         return leadingIndent || trailing || '';
       });
       if (next !== content) changed = true;

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

@@ -9,7 +9,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isGeneratedFile } from './is-generated.mjs';
+import { isGeneratedFile } from './lib/is-generated.mjs';
 import {
   buildSearchQueries,
   findElement,
@@ -21,6 +21,11 @@ import {
   buildCssAuthoring,
   buildCssSelectorPrefixExamples,
 } from './live-wrap.mjs';
+import {
+  buildSvelteComponentCssAuthoring,
+  scaffoldSvelteComponentInsertSession,
+  shouldUseSvelteComponentInjection,
+} from './live/svelte-component.mjs';
 
 const INSERT_POSITIONS = new Set(['before', 'after']);
 
@@ -192,6 +197,41 @@ Output (JSON):
   const styleMode = detectStyleMode(targetFile);
   const isJsx = commentSyntax.open === '{/*';
   const spliceIndex = computeInsertLine(startLine, endLine, position);
+  const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
+
+  if (shouldUseSvelteComponentInjection(targetFile)) {
+    const session = scaffoldSvelteComponentInsertSession({
+      id,
+      count,
+      sourceFile: relTargetFile,
+      insertLine: spliceIndex + 1,
+      position,
+      anchorStartLine: startLine + 1,
+      anchorEndLine: endLine + 1,
+      anchorLines: lines.slice(startLine, endLine + 1),
+      cwd: process.cwd(),
+    });
+    console.log(JSON.stringify({
+      mode: 'insert',
+      position,
+      file: session.manifestFile,
+      sourceFile: relTargetFile,
+      previewMode: 'svelte-component',
+      componentDir: session.componentDir,
+      propContract: session.propContract,
+      insertLine: 1,
+      sourceInsertLine: spliceIndex + 1,
+      anchorStartLine: startLine + 1,
+      anchorEndLine: endLine + 1,
+      commentSyntax,
+      styleMode: 'svelte-component',
+      styleTag: null,
+      cssSelectorPrefixExamples: [],
+      cssAuthoring: buildSvelteComponentCssAuthoring(count),
+    }));
+    return;
+  }
+
   const indent = lines[spliceIndex]?.match(/^(\s*)/)?.[1]
     ?? lines[startLine]?.match(/^(\s*)/)?.[1]
     ?? '';
@@ -216,7 +256,7 @@ Output (JSON):
   console.log(JSON.stringify({
     mode: 'insert',
     position,
-    file: path.relative(process.cwd(), targetFile),
+    file: relTargetFile,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

.agents/skills/impeccable/scripts/live-manual-edit-evidence.mjs

@@ -10,8 +10,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isGeneratedFile } from './is-generated.mjs';
-import { readBuffer, getBufferPath } from './live-manual-edits-buffer.mjs';
+import { isGeneratedFile } from './lib/is-generated.mjs';
+import { readBuffer, getBufferPath } from './live/manual-edits-buffer.mjs';
 
 const EVIDENCE_VERSION = 1;
 const TEXT_EXTENSIONS = new Set(['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro', '.js', '.mjs', '.ts']);

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

@@ -2,31 +2,37 @@
  * CLI client for the live variant mode poll/reply protocol.
  *
  * Usage:
- *   npx impeccable poll                         # Block until browser event, print JSON
- *   npx impeccable poll --stream                # Experimental: keep polling; one JSON line per event
- *   npx impeccable poll --timeout=600000        # Custom timeout (ms); default is long-poll friendly
- *   npx impeccable poll --reply <id> done       # Reply "done" to event <id>
- *   npx impeccable poll --reply <id> error "msg" # Reply with error
+ *   node <scripts_path>/live-poll.mjs                         # Block until browser event, print JSON
+ *   node <scripts_path>/live-poll.mjs --stream                # Experimental: keep polling; one JSON line per event
+ *   node <scripts_path>/live-poll.mjs --timeout=600000        # Custom timeout (ms); default is long-poll friendly
+ *   node <scripts_path>/live-poll.mjs --reply <id> done       # Reply "done" to event <id>
+ *   node <scripts_path>/live-poll.mjs --reply <id> error "msg" # Reply with error
  */
 
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live-completion.mjs';
-import { readLiveServerInfo } from './impeccable-paths.mjs';
+import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
+import { readLiveServerInfo } from './lib/impeccable-paths.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.
+const SELF_DIR = path.dirname(fileURLToPath(import.meta.url));
+const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
 
 // Node's built-in fetch (undici under the hood) enforces a 300s headers
 // timeout that can't be lowered per-request. We cap each request below
 // that ceiling and loop in `pollOnce` to synthesize a long poll without
 // depending on the standalone undici package.
 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']);
 
 function readServerInfo() {
   const record = readLiveServerInfo(process.cwd());
   if (!record) {
-    console.error('No running live server found. Start one with: npx impeccable live');
+    console.error(`No running live server found. Start one with: ${scriptCmd('live.mjs')}`);
     process.exit(1);
   }
   return record.info;
@@ -81,7 +87,7 @@ export function parseReplyArgs(args) {
 }
 
 function validateReplyArgs({ id, status }) {
-  const usage = "Usage: npx impeccable poll --reply <id> <status> [--file path] [--data '<json>'] [message]";
+  const usage = `Usage: ${scriptCmd('live-poll.mjs')} --reply <id> <status> [--file path] [--data '<json>'] [message]`;
   if (!id || id.startsWith('--')) {
     const err = new Error(`${usage}\nMissing event id after --reply.`);
     err.code = 'INVALID_REPLY_ARGS';
@@ -156,7 +162,7 @@ export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
       ? totalDeadline - Date.now()
       : PER_REQUEST_TIMEOUT_MS;
     const slice = Math.min(Math.max(remaining, 1000), PER_REQUEST_TIMEOUT_MS);
-    const res = await fetch(`${base}/poll?token=${token}&timeout=${slice}`);
+    const res = await fetch(`${base}/poll?token=${token}&timeout=${slice}&leaseMs=${DEFAULT_EVENT_LEASE_MS}`);
 
     if (res.status === 401) {
       const err = new Error('Authentication failed. The server token may have changed.');
@@ -282,11 +288,11 @@ export async function runPollStream(base, token, {
 function handlePollError(err) {
   if (err.code === 'AUTH_FAILED') {
     console.error(err.message);
-    console.error('Try restarting: npx impeccable live stop && npx impeccable live');
+    console.error(`Try restarting: ${scriptCmd('live-server.mjs')} stop && ${scriptCmd('live.mjs')}`);
     process.exit(1);
   }
   if (err.cause?.code === 'ECONNREFUSED') {
-    console.error('Live server not running. Start one with: npx impeccable live');
+    console.error(`Live server not running. Start one with: ${scriptCmd('live.mjs')}`);
     process.exit(1);
   }
   if (err.code === 'ACK_TIMEOUT') {
@@ -317,7 +323,7 @@ Modes:
 Options:
   --timeout=MS        One-shot poll timeout in ms (default: 600000). Ignored in --stream mode
   --ack-timeout=MS    Stream mode: max wait for --reply after generate/steer (default: 600000)
-  --file PATH         Attach a source file path to the reply (generate flow)
+  --file PATH         Attach a source file path to the reply (generate/steer flow)
   --data JSON         Attach a JSON result object to the reply (manual_edit_apply flow). Must be valid JSON
   --help              Show this help message
 
@@ -330,7 +336,7 @@ Harness note:
   const info = readServerInfo();
   const base = `http://localhost:${info.port}`;
 
-  // Reply mode: npx impeccable poll --reply <id> <status> [--file path] [--data '<json>'] [message]
+  // Reply mode: node <scripts_path>/live-poll.mjs --reply <id> <status> [--file path] [--data '<json>'] [message]
   if (args.includes('--reply')) {
     let reply;
     try {
@@ -344,7 +350,7 @@ Harness note:
       await postReply(base, info.token, reply);
     } catch (err) {
       if (err.cause?.code === 'ECONNREFUSED') {
-        console.error('Live server not running. Start one with: npx impeccable live');
+        console.error(`Live server not running. Start one with: ${scriptCmd('live.mjs')}`);
       } else {
         console.error('Reply failed:', err.message);
       }

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

@@ -3,7 +3,7 @@
  * Recover the next agent action from the durable live-session journal.
  */
 
-import { createLiveSessionStore } from './live-session-store.mjs';
+import { createLiveSessionStore } from './live/session-store.mjs';
 
 function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
   const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';

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

@@ -3,8 +3,8 @@
  * Print durable recovery status for Impeccable live sessions.
  */
 
-import { createLiveSessionStore } from './live-session-store.mjs';
-import { readLiveServerInfo } from './impeccable-paths.mjs';
+import { createLiveSessionStore } from './live/session-store.mjs';
+import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
 import { manualApplyResumeHint } from './live-resume.mjs';
 
 function readServerInfo() {

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

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import { resolveProjectRoot } from './context.mjs';
+import { parseTargetPath } from './lib/target-args.mjs';
+
+export function resolveLiveTarget(cwd = process.cwd(), args = []) {
+  const originalCwd = path.resolve(cwd);
+  let targetPath = null;
+  try {
+    targetPath = parseTargetPath(args, { strict: true });
+  } catch (err) {
+    if (err?.name === 'TargetArgError') {
+      process.stderr.write(`${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const absoluteTargetPath = targetPath
+    ? path.isAbsolute(targetPath) ? targetPath : path.resolve(originalCwd, targetPath)
+    : null;
+  const projectRoot = targetPath
+    ? resolveProjectRoot(originalCwd, { targetPath: absoluteTargetPath })
+    : originalCwd;
+  return {
+    originalCwd,
+    projectRoot,
+    targetPath,
+    absoluteTargetPath,
+    targetOptions: absoluteTargetPath ? { targetPath: absoluteTargetPath } : {},
+  };
+}

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

@@ -2,7 +2,7 @@
  * CLI helper: find an element in source and wrap it in a variant container.
  *
  * Usage:
- *   npx impeccable wrap --id SESSION_ID --count N --query "hero-combined-left" [--file path]
+ *   node <scripts_path>/live-wrap.mjs --id SESSION_ID --count N --query "hero-combined-left" [--file path]
  *
  * Searches project files for the element matching the query (class name, ID, or
  * text snippet), wraps it with the variant scaffolding, and prints the file path
@@ -13,8 +13,13 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isGeneratedFile } from './is-generated.mjs';
-import { readBuffer as readManualEditsBuffer } from './live-manual-edits-buffer.mjs';
+import { isGeneratedFile } from './lib/is-generated.mjs';
+import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
+import {
+  buildSvelteComponentCssAuthoring,
+  scaffoldSvelteComponentSession,
+  shouldUseSvelteComponentInjection,
+} from './live/svelte-component.mjs';
 
 const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
 
@@ -262,6 +267,8 @@ The agent should insert variant HTML at insertLine.`);
     .map((l) => (l.trim() === '' ? '' : indent + extra + l.slice(originalBaseIndent)))
     .join('\n');
   const originalIndented = reindentOriginal('    ');
+  const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
+  const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
 
   // Wrapper attributes differ by syntax. HTML allows plain string attrs;
   // JSX requires object-literal style and parses string attrs as HTML (which
@@ -302,38 +309,75 @@ The agent should insert variant HTML at insertLine.`);
     indent + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
   ];
 
-  // Replace the original element with the wrapper
-  const newLines = [
-    ...lines.slice(0, startLine),
-    ...wrapperLines,
-    ...lines.slice(endLine + 1),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let outputFile = targetFile;
+  let outputLines;
+  let outputStartLine = startLine + 1;
+  let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
+  let insertLine;
+  let svelteSession = null;
 
-  // Calculate insert line (the "insert below this line" comment).
-  // 0-indexed file position. Both HTML and JSX wrappers have 6 lines above
-  // the insert marker (HTML: start-comment + outer-div + Original-comment +
-  // original-div + content + close-original-div; JSX: outer-div +
-  // start-comment + Original-comment + original-div + content +
-  // close-original-div). Multi-line originals push the marker by their
-  // extra line count.
-  const insertLine = startLine + 6 + (originalLines.length - 1);
+  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({
+      id,
+      count,
+      sourceFile: relTargetFile,
+      sourceStartLine: startLine + 1,
+      sourceEndLine: endLine + 1,
+      originalLines,
+      cwd: process.cwd(),
+    });
+    outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
+    outputStartLine = 1;
+    outputEndLine = 1;
+    insertLine = 1;
+  } else {
+    // Replace the original element with the wrapper
+    const newLines = [
+      ...lines.slice(0, startLine),
+      ...wrapperLines,
+      ...lines.slice(endLine + 1),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+    // Calculate insert line (the "insert below this line" comment).
+    // 0-indexed file position. Both HTML and JSX wrappers have 6 lines above
+    // the insert marker (HTML: start-comment + outer-div + Original-comment +
+    // original-div + content + close-original-div; JSX: outer-div +
+    // start-comment + Original-comment + original-div + content +
+    // close-original-div). Multi-line originals push the marker by their
+    // extra line count.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
+  }
+
+  const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
+
+  const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
 
   console.log(JSON.stringify({
-    file: path.relative(process.cwd(), targetFile),
-    startLine: startLine + 1,       // 1-indexed for the agent
+    file: outputRelFile,
+    sourceFile: useSvelteComponent ? relTargetFile : undefined,
+    previewMode: useSvelteComponent ? 'svelte-component' : undefined,
+    componentDir: svelteSession?.componentDir,
+    propContract: svelteSession?.propContract,
+    sourceStartLine: useSvelteComponent ? startLine + 1 : undefined,
+    sourceEndLine: useSvelteComponent ? 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
     // wrapperLines.length + (originalLines.length - 1). Without the offset,
     // endLine pointed inside the wrapper for any picked element that
     // spanned more than one source line.
-    endLine: startLine + wrapperLines.length + (originalLines.length - 1), // 1-indexed
-    insertLine: insertLine + 1,     // 1-indexed: where variants go
+    endLine: outputEndLine, // 1-indexed
+    insertLine,            // 1-indexed: where variants go
     commentSyntax: commentSyntax,
-    styleMode: styleMode.mode,
-    styleTag: styleMode.styleTag,
-    cssSelectorPrefixExamples: buildCssSelectorPrefixExamples(styleMode.mode, count),
-    cssAuthoring: buildCssAuthoring(styleMode, count),
+    styleMode: useSvelteComponent ? 'svelte-component' : styleMode.mode,
+    styleTag: useSvelteComponent ? null : styleMode.styleTag,
+    cssSelectorPrefixExamples: useSvelteComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
+    cssAuthoring: useSvelteComponent ? svelteComponentAuthoring : buildCssAuthoring(styleMode, count),
     originalLineCount: originalLines.length,
   }));
 }
@@ -527,6 +571,14 @@ function splitClassList(classes) {
   return String(classes).split(/[,\s]+/).map(c => c.trim()).filter(Boolean);
 }
 
+function attrEscapeDouble(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
 function detectCommentSyntax(filePath) {
   const ext = path.extname(filePath).toLowerCase();
   if (ext === '.jsx' || ext === '.tsx') {

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

@@ -21,14 +21,16 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadContext } from './context.mjs';
+import { loadContext, resolveTargetSelection } from './context.mjs';
 import { resolveFiles } from './live-inject.mjs';
-import { readLiveServerInfo } from './impeccable-paths.mjs';
+import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { resolveLiveTarget } from './live-target.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 async function liveCli() {
   const args = process.argv.slice(2);
+  const liveTarget = resolveLiveTarget(process.cwd(), args);
 
   if (args.includes('--help') || args.includes('-h')) {
     console.log(`Usage: node live.mjs
@@ -38,37 +40,78 @@ Prepare everything for live variant mode in a single command:
   - Starts (or reuses) the live server in the background
   - Injects the browser script tag
   - Reads PRODUCT.md / DESIGN.md for project context
+  - In monorepos, choose a child app first; --target <path> is the fallback/manual path
 
 On success, prints a JSON blob with:
-  { ok, serverPort, serverToken, pageFile, hasContext, context }
+  { ok, serverPort, serverToken, pageFiles, projectRoot, repoRoot, targetPath, productPath, designPath }
+
+On target_selection_required, prints:
+  { ok: false, error: "target_selection_required", targetCandidates }
 
 On config_missing, prints:
   { ok: false, error: "config_missing", configPath, hint }
 
 The agent should then:
-  1. If config_missing, create the config and re-run this script
-  2. Optionally open the project's dev/preview URL in the browser (see reference/live.md—not serverPort)
-  3. Enter the poll loop: node live-poll.mjs`);
+  1. If target_selection_required, ask which app to use and rerun from that child cwd
+  2. If config_missing, create the config and re-run this script
+  3. Optionally open the project's dev/preview URL in the browser (see reference/live.md—not serverPort)
+  4. Enter the poll loop: node live-poll.mjs`);
+    process.exit(0);
+  }
+
+  const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
+  if (targetSelection) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'target_selection_required',
+      ...targetSelection,
+      hint: 'Ask the user which app Impeccable should use, then rerun live from that child app cwd. Use --target <path> only as a fallback or explicit path diagnostic.',
+    }, null, 2));
+    process.exit(0);
+  }
+
+  const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
+  const activeCwd = ctx.projectRoot;
+  const outputTargetPath = liveTarget.targetPath || null;
+
+  const missingContext = missingLiveContext(ctx);
+  if (missingContext.length > 0) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'context_missing',
+      missing: missingContext,
+      nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
+      targetPath: outputTargetPath,
+      projectRoot: ctx.projectRoot,
+      repoRoot: ctx.repoRoot,
+      productPath: ctx.productPath,
+      designPath: ctx.designPath,
+    }, null, 2));
     process.exit(0);
   }
 
   // 1. Check config (fail fast if missing — no point starting anything else)
-  const checkOut = runScript('live-inject.mjs', ['--check']);
+  const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
   const checkResult = safeParse(checkOut);
   if (!checkResult || !checkResult.ok) {
-    console.log(JSON.stringify(checkResult || { ok: false, error: 'check_failed', raw: checkOut }));
+    console.log(JSON.stringify({
+      ...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
+      targetPath: outputTargetPath,
+      projectRoot: ctx.projectRoot,
+      repoRoot: ctx.repoRoot,
+    }));
     process.exit(0);
   }
 
   // 2. Start server (or reuse existing)
-  const serverInfo = ensureServerRunning();
+  const serverInfo = ensureServerRunning(activeCwd);
   if (!serverInfo) {
     console.log(JSON.stringify({ ok: false, error: 'server_start_failed' }));
     process.exit(1);
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)]);
+  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({
@@ -80,22 +123,23 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load PRODUCT.md + DESIGN.md context.
-  const ctx = loadContext(process.cwd());
-
-  // 5. Compute drift-heal: compare resolved inject targets against the
+  // 4. Compute drift-heal: compare resolved inject targets against the
   //    project's HTML files. Orphans are HTML files not covered by config.
   //    Warning only — the agent decides whether to act.
-  const resolvedFiles = resolveFiles(process.cwd(), checkResult.config);
-  const drift = scanForDrift(process.cwd(), resolvedFiles, checkResult.config);
+  const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
+  const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
 
-  // 6. Emit everything the agent needs
+  // 5. Emit everything the agent needs
   console.log(JSON.stringify({
     ok: true,
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFiles: resolvedFiles,
+    liveConfigPath: checkResult.path,
     configDrift: drift,
+    targetPath: outputTargetPath,
+    projectRoot: ctx.projectRoot,
+    repoRoot: ctx.repoRoot,
     hasProduct: ctx.hasProduct,
     product: ctx.product,
     productPath: ctx.productPath,
@@ -105,6 +149,13 @@ The agent should then:
   }, null, 2));
 }
 
+function missingLiveContext(ctx) {
+  const missing = [];
+  if (!ctx.hasProduct) missing.push('PRODUCT.md');
+  if (!ctx.hasDesign) missing.push('DESIGN.md');
+  return missing;
+}
+
 /**
  * Drift-heal scan. Walks the project for HTML files under common
  * page-source directories (public/, src/, app/, pages/) and reports any
@@ -201,11 +252,11 @@ function globToRegex(pattern) {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function runScript(name, args) {
+function runScript(name, args, options = {}) {
   const scriptPath = path.join(__dirname, name);
   const cmd = `node "${scriptPath}" ${args.map(a => `"${a}"`).join(' ')}`;
   try {
-    return execSync(cmd, { encoding: 'utf-8', cwd: process.cwd(), timeout: 15_000 });
+    return execSync(cmd, { encoding: 'utf-8', cwd: options.cwd || process.cwd(), timeout: 15_000 });
   } catch (err) {
     // execSync throws on non-zero exit; return stdout if any
     return err.stdout || err.message || '';
@@ -219,10 +270,10 @@ function safeParse(out) {
 /**
  * Return { pid, port, token } for the running live server, starting one if needed.
  */
-function ensureServerRunning() {
+function ensureServerRunning(cwd = process.cwd()) {
   // Try to reuse an existing server
   try {
-    const existing = readLiveServerInfo(process.cwd())?.info;
+    const existing = readLiveServerInfo(cwd)?.info;
     if (existing && existing.pid) {
       try {
         process.kill(existing.pid, 0); // throws if dead
@@ -232,7 +283,7 @@ function ensureServerRunning() {
   } catch { /* no PID file */ }
 
   // Start a new server
-  const out = runScript('live-server.mjs', ['--background']);
+  const out = runScript('live-server.mjs', ['--background'], { cwd });
   return safeParse(out);
 }
 

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

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const LIVE_BROWSER_SCRIPT_PARTS = Object.freeze([
+  Object.freeze({ name: 'session-state', file: 'live-browser-session.js' }),
+  Object.freeze({ name: 'dom-helpers', file: 'live-browser-dom.js' }),
+  Object.freeze({ name: 'browser-ui', file: 'live-browser.js' }),
+]);
+
+export function resolveLiveBrowserScriptParts(scriptsDir, parts = LIVE_BROWSER_SCRIPT_PARTS) {
+  if (!scriptsDir) throw new Error('scriptsDir is required');
+  return parts.map((part, index) => ({
+    ...part,
+    index,
+    path: path.join(scriptsDir, part.file),
+  }));
+}
+
+export function assertLiveBrowserScriptParts(parts, exists = fs.existsSync) {
+  for (const part of parts) {
+    if (!exists(part.path)) {
+      throw new Error(`Live browser script part missing: ${part.name} (${part.path})`);
+    }
+  }
+  return parts;
+}
+
+export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.readFileSync(filePath, 'utf-8')) {
+  return parts.map((part) => ({
+    ...part,
+    source: readFile(part.path),
+  }));
+}
+
+export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
+  const prelude =
+    `window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
+    `window.__IMPECCABLE_PORT__ = ${port};\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.
+    `window.__IMPECCABLE_VOCAB__ = ${JSON.stringify(vocabulary)};\n`;
+
+  const body = parts.map((part) => {
+    const file = part.file || path.basename(part.path || '');
+    return `// --- impeccable live script part: ${part.name} (${file}) ---\n${part.source}`;
+  }).join('\n');
+
+  return prelude + body;
+}

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

@@ -3,6 +3,7 @@ export function completionTypeForAcceptResult(eventType, acceptResult) {
   if (acceptResult?.handled === true && acceptResult?.carbonize === true) return 'agent_done';
   if (acceptResult?.handled === true) return 'complete';
   if (acceptResult?.mode === 'error') return 'error';
+  if (eventType === 'accept' && acceptResult?.previewMode === 'svelte-component') return 'error';
   return 'agent_done';
 }
 

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

@@ -3,12 +3,13 @@
  * Extracted for unit testing (insert mode rules).
  */
 
-import { canCreateInsert } from './live-insert-ui.mjs';
+import { canCreateInsert } from './insert-ui.mjs';
 
-export const VISUAL_ACTIONS = [
-  'impeccable', 'bolder', 'quieter', 'distill', 'polish', 'typeset',
-  'colorize', 'layout', 'adapt', 'animate', 'delight', 'overdrive',
-];
+// 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 };
 
 const ID_PATTERN = /^[0-9a-f]{8}$/;
 const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;

.agents/skills/impeccable/scripts/live/manual-apply.mjs

@@ -0,0 +1,939 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLiveDir } from '../lib/impeccable-paths.mjs';
+import { readBuffer as readManualEditsBuffer } from './manual-edits-buffer.mjs';
+
+const APPLY_EVENT_HARD_TIMEOUT_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_HARD_TIMEOUT_MS || 150_000);
+const APPLY_EVENT_SOFT_DEADLINE_MS = Number(process.env.IMPECCABLE_LIVE_APPLY_EVENT_SOFT_DEADLINE_MS || 120_000);
+const DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE = 3;
+const MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE = 1;
+const MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE = 20;
+const MANUAL_APPLY_COMPACT_TEXT_LIMIT = 240;
+const MANUAL_APPLY_COMPACT_NEARBY_LIMIT = 4;
+
+export function createManualApplyController({
+  pendingEvents,
+  pendingApplyDeferreds,
+  timedOutApplyIds,
+  enqueueEvent,
+  acknowledgePendingEvent,
+  flushPendingPolls,
+  recordManualEditActivity,
+  cwd = () => process.cwd(),
+} = {}) {
+  const projectCwd = () => typeof cwd === 'function' ? cwd() : cwd || process.cwd();
+
+  function tombstoneTimedOutApplyId(eventId, details = {}) {
+    if (!eventId) return;
+    timedOutApplyIds.set(eventId, details);
+    if (timedOutApplyIds.size <= 200) return;
+    const oldest = timedOutApplyIds.keys().next().value;
+    timedOutApplyIds.delete(oldest);
+  }
+
+  function pushApplyEventAndWait(batch, pageUrl, chunk = null, repair = null) {
+    const cwdValue = projectCwd();
+    const eventId = randomUUID().replace(/-/g, '').slice(0, 8);
+    const evidencePath = writeManualApplyEvidence(eventId, batch, cwdValue);
+    const event = {
+      type: 'manual_edit_apply',
+      id: eventId,
+      pageUrl,
+      batch: compactManualApplyBatch(batch, cwdValue),
+      evidencePath,
+      agentAction: buildManualApplyAgentAction(eventId),
+      schemaVersion: 1,
+      deadlineMs: APPLY_EVENT_SOFT_DEADLINE_MS,
+    };
+    if (chunk) event.chunk = chunk;
+    if (repair) event.repair = repair;
+    const rollbackSnapshot = snapshotApplyEventFiles(batch, cwdValue);
+    recordManualEditActivity('manual_edit_apply_dispatched', {
+      id: eventId,
+      pageUrl,
+      chunk,
+      repair,
+      entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
+      opCount: countManualApplyOps(batch),
+      fileCount: collectManualApplyFiles(batch, [], cwdValue).length,
+    });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingApplyDeferreds.delete(eventId);
+        tombstoneTimedOutApplyId(eventId, { batch, rollbackSnapshot, cwd: cwdValue });
+        acknowledgePendingEvent(eventId);
+        removeManualApplyEvidence(evidencePath, cwdValue);
+        recordManualEditActivity('manual_edit_apply_timeout', {
+          id: eventId,
+          pageUrl,
+          chunk,
+          entryCount: Array.isArray(batch.entries) ? batch.entries.length : 0,
+          opCount: countManualApplyOps(batch),
+        });
+        reject(new Error('chat_agent_timeout'));
+      }, APPLY_EVENT_HARD_TIMEOUT_MS);
+      pendingApplyDeferreds.set(eventId, { resolve, reject, timer, event, batch, pageUrl, rollbackSnapshot, cwd: cwdValue });
+      enqueueEvent(event);
+    });
+  }
+
+  async function pushBatchInChunksAndWait(batch, pageUrl, context = {}) {
+    const repair = context?.repair || batch?.repair || null;
+    if (repair) return pushApplyEventAndWait(batch, pageUrl, null, repair);
+    const chunks = splitManualApplyBatch(batch, manualEditApplyChunkSize());
+    if (chunks.length <= 1) return pushApplyEventAndWait(batch, pageUrl);
+
+    const expectedOpsByEntry = new Map();
+    for (const entry of batch?.entries || []) {
+      expectedOpsByEntry.set(entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0);
+    }
+
+    const appliedOpsByEntry = new Map();
+    const failedByEntry = new Map();
+    const files = new Set();
+    const notes = [];
+    let aborted = false;
+
+    for (const chunk of chunks) {
+      if (aborted) {
+        markChunkEntriesFailed(failedByEntry, chunk, 'manual_edit_chunk_aborted');
+        continue;
+      }
+
+      let result;
+      try {
+        result = normalizeApplyChunkResult(await pushApplyEventAndWait(chunk.batch, pageUrl, chunk.meta));
+      } catch (err) {
+        markChunkEntriesFailed(failedByEntry, chunk, err.message || 'chat_agent_error');
+        aborted = true;
+        continue;
+      }
+
+      for (const file of result.files) files.add(file);
+      notes.push(...result.notes);
+
+      const chunkFailedIds = new Set();
+      for (const item of result.failed) {
+        const entryId = item.entryId || item.id;
+        if (!entryId) continue;
+        chunkFailedIds.add(entryId);
+        if (!failedByEntry.has(entryId)) {
+          failedByEntry.set(entryId, {
+            entryId,
+            reason: item.reason || item.message || 'failed',
+            candidates: Array.isArray(item.candidates) ? item.candidates : [],
+          });
+        }
+      }
+
+      if (result.status === 'error') {
+        markChunkEntriesFailed(failedByEntry, chunk, result.message || firstFailureReason(result) || 'chat_agent_error');
+        aborted = true;
+        continue;
+      }
+
+      const reportedAppliedIds = new Set(result.appliedEntryIds);
+      for (const entryId of reportedAppliedIds) {
+        if (!chunk.entryIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
+        appliedOpsByEntry.set(entryId, (appliedOpsByEntry.get(entryId) || 0) + (chunk.opCountsByEntry.get(entryId) || 0));
+      }
+
+      for (const entryId of chunk.entryIds) {
+        if (reportedAppliedIds.has(entryId) || chunkFailedIds.has(entryId)) continue;
+        if (!failedByEntry.has(entryId)) {
+          failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
+        }
+      }
+    }
+
+    const appliedEntryIds = [];
+    for (const [entryId, expectedOps] of expectedOpsByEntry.entries()) {
+      if (failedByEntry.has(entryId)) continue;
+      if ((appliedOpsByEntry.get(entryId) || 0) === expectedOps && expectedOps > 0) {
+        appliedEntryIds.push(entryId);
+      } else if (!failedByEntry.has(entryId)) {
+        failedByEntry.set(entryId, { entryId, reason: 'not_reported_applied', candidates: [] });
+      }
+    }
+
+    const failed = [...failedByEntry.values()];
+    return {
+      status: failed.length === 0 ? 'done' : appliedEntryIds.length > 0 ? 'partial' : 'error',
+      appliedEntryIds,
+      failed,
+      files: [...files],
+      notes,
+    };
+  }
+
+  function getDeferred(eventId) {
+    return pendingApplyDeferreds.get(eventId) || null;
+  }
+
+  function hasTimedOutId(eventId) {
+    return timedOutApplyIds.has(eventId);
+  }
+
+  function resolveDeferred(eventId, body) {
+    const deferred = pendingApplyDeferreds.get(eventId);
+    if (!deferred) return false;
+    pendingApplyDeferreds.delete(eventId);
+    clearTimeout(deferred.timer);
+    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
+    deferred.resolve(body);
+    return true;
+  }
+
+  function rejectDeferred(eventId, reason) {
+    const deferred = pendingApplyDeferreds.get(eventId);
+    if (!deferred) return false;
+    pendingApplyDeferreds.delete(eventId);
+    clearTimeout(deferred.timer);
+    removeManualApplyEvidence(deferred.event?.evidencePath, deferred.cwd || projectCwd());
+    deferred.reject(new Error(reason || 'chat_agent_error'));
+    return true;
+  }
+
+  function referencedManualApplyEvidencePaths(cwdValue = projectCwd()) {
+    const referenced = new Set();
+    const add = (event) => {
+      const fullPath = normalizeManualApplyEvidencePath(event?.evidencePath, cwdValue);
+      if (fullPath) referenced.add(fullPath);
+    };
+    for (const entry of pendingEvents) add(entry.event);
+    for (const deferred of pendingApplyDeferreds.values()) add(deferred.event);
+    return referenced;
+  }
+
+  function pruneStaleEvidence(cwdValue = projectCwd()) {
+    const dir = manualApplyEvidenceDir(cwdValue);
+    if (!fs.existsSync(dir)) return [];
+    const referenced = referencedManualApplyEvidencePaths(cwdValue);
+    const removed = [];
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      const fullPath = path.join(dir, name);
+      if (referenced.has(fullPath)) continue;
+      try {
+        fs.unlinkSync(fullPath);
+        removed.push(fullPath);
+      } catch {
+        // Stale evidence cleanup is best-effort; Apply verification never relies
+        // on deleting these files.
+      }
+    }
+    return removed;
+  }
+
+  function rollbackTimedOutReply(msg) {
+    const details = timedOutApplyIds.get(msg.id);
+    if (!details) return { rolledBackFiles: [], rollbackFailures: [] };
+    timedOutApplyIds.delete(msg.id);
+    return rollbackApplySnapshot(
+      details.batch,
+      details.rollbackSnapshot,
+      msg.data?.files || [],
+      'stale_manual_edit_apply_reply',
+      details.cwd || projectCwd(),
+    );
+  }
+
+  function cancelPendingEvents(pageUrl, reason = 'manual_edit_discarded') {
+    const canceledById = new Map();
+    const shouldCancel = (event) => event?.type === 'manual_edit_apply' && (!pageUrl || event.pageUrl === pageUrl);
+
+    for (let i = pendingEvents.length - 1; i >= 0; i -= 1) {
+      const event = pendingEvents[i]?.event;
+      if (!shouldCancel(event)) continue;
+      pendingEvents.splice(i, 1);
+      removeManualApplyEvidence(event.evidencePath, projectCwd());
+      canceledById.set(event.id, {
+        id: event.id,
+        pageUrl: event.pageUrl,
+        entryCount: event.batch?.entries?.length || 0,
+      });
+    }
+
+    for (const [eventId, deferred] of [...pendingApplyDeferreds.entries()]) {
+      if (!shouldCancel(deferred.event)) continue;
+      pendingApplyDeferreds.delete(eventId);
+      clearTimeout(deferred.timer);
+      const cwdValue = deferred.cwd || projectCwd();
+      const rollback = rollbackApplySnapshot(deferred.batch, deferred.rollbackSnapshot, [], reason, cwdValue);
+      tombstoneTimedOutApplyId(eventId, {
+        batch: deferred.batch,
+        rollbackSnapshot: deferred.rollbackSnapshot,
+        reason,
+        cwd: cwdValue,
+      });
+      removeManualApplyEvidence(deferred.event?.evidencePath, cwdValue);
+      canceledById.set(eventId, {
+        id: eventId,
+        pageUrl: deferred.pageUrl,
+        entryCount: deferred.batch?.entries?.length || 0,
+        rolledBackFiles: rollback.rolledBackFiles,
+        rollbackFailures: rollback.rollbackFailures,
+      });
+      deferred.reject(new Error(reason));
+    }
+
+    if (canceledById.size > 0) flushPendingPolls();
+    return [...canceledById.values()];
+  }
+
+  return {
+    buildAgentAction: buildManualApplyAgentAction,
+    cancelPendingEvents,
+    clearTransaction: (transactionId = null) => clearManualApplyTransaction(projectCwd(), transactionId),
+    countOps: countManualApplyOps,
+    getDeferred,
+    hasTimedOutId,
+    pruneStaleEvidence,
+    pushBatchInChunksAndWait,
+    readTransaction: () => readManualApplyTransaction(projectCwd()),
+    rejectDeferred,
+    resolveDeferred,
+    rollbackTimedOutReply,
+    rollbackTransaction: (opts = {}) => rollbackManualApplyTransaction({
+      cwd: projectCwd(),
+      recordManualEditActivity,
+      ...opts,
+    }),
+    summarizeEvent: (event = {}, batch = event.batch) => summarizeManualApplyEvent(event, batch, projectCwd()),
+    validateResultMessage: validateManualApplyResultMessage,
+    writeTransaction: (opts = {}) => writeManualApplyTransaction({ cwd: projectCwd(), ...opts }),
+  };
+}
+
+export function manualEditApplyChunkSize(env = process.env) {
+  const raw = Number(env.IMPECCABLE_LIVE_MANUAL_EDIT_CHUNK_SIZE);
+  if (!Number.isFinite(raw)) return DEFAULT_MANUAL_EDIT_APPLY_CHUNK_SIZE;
+  const size = Math.trunc(raw);
+  return Math.max(MIN_MANUAL_EDIT_APPLY_CHUNK_SIZE, Math.min(MAX_MANUAL_EDIT_APPLY_CHUNK_SIZE, size));
+}
+
+export function countManualApplyOps(entriesOrBatch) {
+  const entries = Array.isArray(entriesOrBatch)
+    ? entriesOrBatch
+    : Array.isArray(entriesOrBatch?.entries) ? entriesOrBatch.entries : [];
+  let count = 0;
+  for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
+  return count;
+}
+
+export function writeManualApplyEvidence(eventId, batch, cwd = process.cwd()) {
+  const dir = manualApplyEvidenceDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  const evidencePath = path.join(dir, `${eventId}.json`);
+  fs.writeFileSync(evidencePath, JSON.stringify(batch, null, 2) + '\n', 'utf-8');
+  return evidencePath;
+}
+
+export function manualApplyEvidenceDir(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'manual-edit-evidence');
+}
+
+export function normalizeManualApplyEvidencePath(evidencePath, cwd = process.cwd()) {
+  if (!evidencePath || typeof evidencePath !== 'string') return null;
+  const fullPath = path.isAbsolute(evidencePath) ? evidencePath : path.resolve(cwd, evidencePath);
+  const evidenceDir = manualApplyEvidenceDir(cwd);
+  const relative = path.relative(evidenceDir, fullPath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  if (path.extname(relative) !== '.json') return null;
+  return fullPath;
+}
+
+export function removeManualApplyEvidence(evidencePath, cwd = process.cwd()) {
+  const fullPath = normalizeManualApplyEvidencePath(evidencePath, cwd);
+  if (!fullPath) return false;
+  try {
+    fs.unlinkSync(fullPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function compactManualApplyBatch(batch = {}, cwd = process.cwd()) {
+  const entries = (batch.entries || []).map(compactManualApplyEntry);
+  const candidates = compactManualApplyCandidates(batch.candidates || [], cwd);
+  return {
+    version: batch.version,
+    pageUrl: batch.pageUrl || null,
+    count: batch.count,
+    entries,
+    ops: entries.flatMap((entry) => entry.ops.map((op) => ({ ...op, entryId: entry.id }))),
+    candidates: candidates.length > 0 ? candidates : undefined,
+    context: batch.context ? {
+      bufferPath: batch.context.bufferPath,
+      totalEntries: batch.context.totalEntries,
+      totalOps: batch.context.totalOps,
+      chunkIndex: batch.context.chunkIndex,
+      chunkTotal: batch.context.chunkTotal,
+      totalApplyOps: batch.context.totalApplyOps,
+    } : undefined,
+  };
+}
+
+export function compactManualApplyCandidates(candidates, cwd = process.cwd()) {
+  return (Array.isArray(candidates) ? candidates : [])
+    .slice(0, 24)
+    .map((candidate) => ({
+      entryId: candidate.entryId,
+      ref: candidate.ref,
+      sourceHint: compactManualApplySourceMatch(candidate.sourceHint, cwd),
+      textMatches: compactManualApplySourceMatches(candidate.textMatches, 8, cwd),
+      objectKeyMatches: compactManualApplySourceMatches(candidate.objectKeyMatches, 8, cwd),
+      contextTextMatches: compactManualApplySourceMatches(candidate.contextTextMatches, 8, cwd),
+      locatorMatches: compactManualApplySourceMatches(candidate.locatorMatches, 6, cwd),
+    }));
+}
+
+function compactManualApplySourceMatches(matches, limit, cwd) {
+  return (Array.isArray(matches) ? matches : [])
+    .slice(0, limit)
+    .map((match) => compactManualApplySourceMatch(match, cwd))
+    .filter(Boolean);
+}
+
+function compactManualApplySourceMatch(match, cwd) {
+  if (!match || typeof match !== 'object') return null;
+  const file = match.relativeFile || match.file;
+  if (!file && !match.line) return null;
+  return {
+    file: summarizeManualLogFile(file, cwd),
+    line: match.line || null,
+    column: match.column || null,
+    reason: match.reason || match.kind || undefined,
+    status: match.status || undefined,
+  };
+}
+
+function compactManualApplyEntry(entry = {}) {
+  return {
+    id: entry.id,
+    pageUrl: entry.pageUrl,
+    stagedAt: entry.stagedAt || null,
+    element: compactManualApplyContext(entry.element),
+    ops: (entry.ops || []).map(compactManualApplyOp),
+  };
+}
+
+function compactManualApplyOp(op = {}) {
+  return {
+    entryId: op.entryId,
+    ref: op.ref,
+    contextRef: op.contextRef,
+    tag: op.tag,
+    elementId: op.elementId,
+    classes: Array.isArray(op.classes) ? op.classes : [],
+    originalText: op.originalText,
+    newText: op.newText,
+    deleted: op.deleted === true || undefined,
+    sourceHint: op.sourceHint || null,
+    leaf: compactManualApplyContext(op.leaf),
+    nearbyEditableTexts: compactNearbyManualEditTexts(op.nearbyEditableTexts),
+    container: compactManualApplyContext(op.container),
+    contextHints: Array.isArray(op.contextHints) ? op.contextHints.slice(0, 8) : undefined,
+  };
+}
+
+function compactManualApplyContext(value) {
+  if (!value || typeof value !== 'object') return null;
+  return {
+    ref: value.ref,
+    tagName: value.tagName || value.tag || null,
+    id: value.id || null,
+    classes: Array.isArray(value.classes) ? value.classes : [],
+    textContent: truncateManualApplyText(value.textContent, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
+  };
+}
+
+function compactNearbyManualEditTexts(items) {
+  return (Array.isArray(items) ? items : [])
+    .slice(0, MANUAL_APPLY_COMPACT_NEARBY_LIMIT)
+    .map((item) => typeof item === 'string' ? { text: truncateManualApplyText(item, MANUAL_APPLY_COMPACT_TEXT_LIMIT) } : {
+      ref: item?.ref,
+      tag: item?.tag,
+      classes: Array.isArray(item?.classes) ? item.classes : [],
+      text: truncateManualApplyText(item?.text, MANUAL_APPLY_COMPACT_TEXT_LIMIT),
+    });
+}
+
+function truncateManualApplyText(value, max) {
+  if (typeof value !== 'string') return value || null;
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+function normalizeApplyChunkResult(result) {
+  const status = result?.status === 'partial' ? 'partial' : result?.status === 'error' ? 'error' : 'done';
+  return {
+    status,
+    message: typeof result?.message === 'string' ? result.message : null,
+    appliedEntryIds: Array.isArray(result?.appliedEntryIds) ? result.appliedEntryIds.filter((id) => typeof id === 'string') : [],
+    failed: Array.isArray(result?.failed) ? result.failed.filter(Boolean) : [],
+    files: Array.isArray(result?.files) ? result.files.filter((file) => typeof file === 'string') : [],
+    notes: Array.isArray(result?.notes) ? result.notes.filter((note) => typeof note === 'string') : [],
+  };
+}
+
+function manualApplyResultShapeHint(eventId = 'EVENT_ID') {
+  return `Use live-poll.mjs --reply ${eventId} done --data '{"status":"done","appliedEntryIds":["ENTRY_ID"],"failed":[],"files":["src/page.html"],"notes":[]}'`;
+}
+
+function invalidManualApplyResult(reason, eventId, extra = {}) {
+  return {
+    ok: false,
+    body: {
+      error: 'invalid_manual_apply_result',
+      reason,
+      hint: manualApplyResultShapeHint(eventId),
+      ...extra,
+    },
+  };
+}
+
+export function validateManualApplyResultMessage(msg, deferred) {
+  let data = msg?.data;
+  const eventId = msg?.id || deferred?.event?.id || 'EVENT_ID';
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return invalidManualApplyResult('missing_result_data', eventId);
+  }
+  if ('entries' in data || 'ops' in data) {
+    return invalidManualApplyResult('summary_result_not_allowed', eventId);
+  }
+  if (!['done', 'partial', 'error'].includes(data.status)) {
+    return invalidManualApplyResult('invalid_status', eventId, { status: data.status ?? null });
+  }
+
+  for (const key of ['appliedEntryIds', 'failed', 'files', 'notes']) {
+    if (!Array.isArray(data[key])) {
+      return invalidManualApplyResult(`${key}_must_be_array`, eventId);
+    }
+  }
+
+  for (const [index, value] of data.appliedEntryIds.entries()) {
+    if (typeof value !== 'string' || !value) {
+      return invalidManualApplyResult('appliedEntryIds_must_contain_strings', eventId, { index });
+    }
+  }
+  for (const [index, value] of data.files.entries()) {
+    if (typeof value !== 'string' || !value) {
+      return invalidManualApplyResult('files_must_contain_strings', eventId, { index });
+    }
+  }
+  for (const [index, value] of data.notes.entries()) {
+    if (typeof value !== 'string') {
+      return invalidManualApplyResult('notes_must_contain_strings', eventId, { index });
+    }
+  }
+  for (const [index, item] of data.failed.entries()) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      return invalidManualApplyResult('failed_must_contain_objects', eventId, { index });
+    }
+    if (typeof item.entryId !== 'string' || !item.entryId) {
+      return invalidManualApplyResult('failed_entryId_required', eventId, { index });
+    }
+    if (typeof item.reason !== 'string' || !item.reason) {
+      return invalidManualApplyResult('failed_reason_required', eventId, { index });
+    }
+  }
+
+  const eventEntryIds = new Set((deferred?.batch?.entries || []).map((entry) => entry.id).filter(Boolean));
+  for (const entryId of data.appliedEntryIds) {
+    if (eventEntryIds.size > 0 && !eventEntryIds.has(entryId)) {
+      return invalidManualApplyResult('applied_entry_id_not_in_event', eventId, { entryId });
+    }
+  }
+  for (const item of data.failed) {
+    if (eventEntryIds.size > 0 && !eventEntryIds.has(item.entryId)) {
+      return invalidManualApplyResult('failed_entry_id_not_in_event', eventId, { entryId: item.entryId });
+    }
+  }
+
+  if (data.status === 'done') {
+    if (data.failed.length > 0) {
+      return invalidManualApplyResult('done_result_has_failed_entries', eventId);
+    }
+    if (countManualApplyOps(deferred?.batch) > 0 && data.appliedEntryIds.length === 0) {
+      return invalidManualApplyResult('done_result_missing_applied_entry_ids', eventId);
+    }
+  }
+  if (data.status === 'partial' && data.appliedEntryIds.length === 0 && data.failed.length === 0) {
+    return invalidManualApplyResult('partial_result_has_no_entries', eventId);
+  }
+  if (data.status === 'error' && data.appliedEntryIds.length > 0) {
+    return invalidManualApplyResult('error_result_has_applied_entries', eventId);
+  }
+
+  return {
+    ok: true,
+    result: {
+      status: data.status,
+      message: typeof data.message === 'string' ? data.message : undefined,
+      appliedEntryIds: data.appliedEntryIds,
+      failed: data.failed,
+      files: data.files,
+      notes: data.notes,
+    },
+  };
+}
+
+function firstFailureReason(result) {
+  const first = Array.isArray(result?.failed) ? result.failed.find(Boolean) : null;
+  return first?.reason || first?.message || null;
+}
+
+function markChunkEntriesFailed(failedByEntry, chunk, reason) {
+  for (const entryId of chunk.entryIds) {
+    if (failedByEntry.has(entryId)) continue;
+    failedByEntry.set(entryId, { entryId, reason, candidates: [] });
+  }
+}
+
+export function splitManualApplyBatch(batch, maxOps) {
+  const totalOpCount = countManualApplyOps(batch);
+  if (totalOpCount <= maxOps) {
+    return [{
+      batch,
+      meta: null,
+      entryIds: new Set((batch?.entries || []).map((entry) => entry.id).filter(Boolean)),
+      opCountsByEntry: new Map((batch?.entries || []).map((entry) => [entry.id, Array.isArray(entry.ops) ? entry.ops.length : 0])),
+    }];
+  }
+
+  const rawChunks = [];
+  let current = createManualApplyChunkBuilder();
+  for (const entry of batch?.entries || []) {
+    const ops = entry.ops || [];
+    if (ops.length <= maxOps) {
+      if (current.opCount > 0 && current.opCount + ops.length > maxOps) {
+        rawChunks.push(current);
+        current = createManualApplyChunkBuilder();
+      }
+      for (const op of ops) addOpToManualApplyChunk(current, entry, op);
+      continue;
+    }
+    if (current.opCount > 0) {
+      rawChunks.push(current);
+      current = createManualApplyChunkBuilder();
+    }
+    for (const op of ops) {
+      if (current.opCount >= maxOps) {
+        rawChunks.push(current);
+        current = createManualApplyChunkBuilder();
+      }
+      addOpToManualApplyChunk(current, entry, op);
+    }
+  }
+  if (current.opCount > 0) rawChunks.push(current);
+
+  return rawChunks.map((chunk, index) => ({
+    batch: {
+      ...batch,
+      count: chunk.opCount,
+      entries: chunk.entries,
+      ops: chunk.ops,
+      candidates: filterManualApplyChunkCandidates(batch, chunk.refsByEntry),
+      context: {
+        ...(batch?.context || {}),
+        totalEntries: chunk.entries.length,
+        totalOps: chunk.opCount,
+        chunkIndex: index + 1,
+        chunkTotal: rawChunks.length,
+        totalApplyOps: totalOpCount,
+      },
+    },
+    meta: {
+      index: index + 1,
+      total: rawChunks.length,
+      opCount: chunk.opCount,
+      totalOpCount,
+    },
+    entryIds: new Set(chunk.entries.map((entry) => entry.id).filter(Boolean)),
+    opCountsByEntry: chunk.opCountsByEntry,
+  }));
+}
+
+function createManualApplyChunkBuilder() {
+  return {
+    entries: [],
+    entryById: new Map(),
+    entryIds: new Set(),
+    ops: [],
+    refsByEntry: new Map(),
+    opCountsByEntry: new Map(),
+    opCount: 0,
+  };
+}
+
+function addOpToManualApplyChunk(chunk, entry, op) {
+  let chunkEntry = chunk.entryById.get(entry.id);
+  if (!chunkEntry) {
+    chunkEntry = { ...entry, ops: [] };
+    chunk.entryById.set(entry.id, chunkEntry);
+    chunk.entryIds.add(entry.id);
+    chunk.entries.push(chunkEntry);
+  }
+  chunkEntry.ops.push(op);
+  chunk.ops.push({ ...op, entryId: op.entryId || entry.id });
+  if (!chunk.refsByEntry.has(entry.id)) chunk.refsByEntry.set(entry.id, new Set());
+  if (op.ref) chunk.refsByEntry.get(entry.id).add(op.ref);
+  chunk.opCountsByEntry.set(entry.id, (chunk.opCountsByEntry.get(entry.id) || 0) + 1);
+  chunk.opCount += 1;
+}
+
+function filterManualApplyChunkCandidates(batch, refsByEntry) {
+  return (batch?.candidates || []).filter((candidate) => {
+    const refs = refsByEntry.get(candidate.entryId);
+    if (!refs) return false;
+    if (!candidate.ref) return true;
+    return refs.has(candidate.ref);
+  });
+}
+
+export function snapshotApplyEventFiles(batch, cwd = process.cwd()) {
+  const snapshot = new Map();
+  for (const relativeFile of collectManualApplyFiles(batch, [], cwd)) {
+    const absolute = path.resolve(cwd, relativeFile);
+    try {
+      snapshot.set(relativeFile, {
+        exists: fs.existsSync(absolute),
+        content: fs.existsSync(absolute) ? fs.readFileSync(absolute, 'utf-8') : '',
+      });
+    } catch {
+      // If a file cannot be read before dispatch, do not attempt late rollback.
+    }
+  }
+  return snapshot;
+}
+
+export function manualApplyTransactionPath(cwd = process.cwd()) {
+  return path.join(getLiveDir(cwd), 'manual-edit-apply-transaction.json');
+}
+
+export function readManualApplyTransaction(cwd = process.cwd()) {
+  const file = manualApplyTransactionPath(cwd);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManualApplyTransaction({ cwd = process.cwd(), pageUrl = null, batch }) {
+  const file = manualApplyTransactionPath(cwd);
+  const files = collectManualApplyFiles(batch, [], cwd);
+  const transaction = {
+    version: 1,
+    id: randomUUID().replace(/-/g, '').slice(0, 8),
+    createdAt: new Date().toISOString(),
+    pageUrl,
+    entryIds: (batch?.entries || []).map((entry) => entry.id).filter(Boolean),
+    files: files.map((relativeFile) => {
+      const absolute = path.resolve(cwd, relativeFile);
+      const exists = fs.existsSync(absolute);
+      return {
+        file: relativeFile,
+        exists,
+        content: exists ? fs.readFileSync(absolute, 'utf-8') : '',
+      };
+    }),
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify(transaction, null, 2) + '\n', 'utf-8');
+  fs.renameSync(`${file}.tmp`, file);
+  return transaction;
+}
+
+export function clearManualApplyTransaction(cwd = process.cwd(), transactionId = null) {
+  const file = manualApplyTransactionPath(cwd);
+  if (!fs.existsSync(file)) return false;
+  if (transactionId) {
+    const existing = readManualApplyTransaction(cwd);
+    if (existing?.id && existing.id !== transactionId) return false;
+  }
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function rollbackManualApplyTransaction({
+  cwd = process.cwd(),
+  pageUrl = null,
+  reason = 'manual_edit_transaction_rollback',
+  recordManualEditActivity = null,
+} = {}) {
+  const transaction = readManualApplyTransaction(cwd);
+  if (!transaction) return null;
+  if (pageUrl && transaction.pageUrl && transaction.pageUrl !== pageUrl) return null;
+
+  let pendingIds = new Set();
+  try {
+    const buffer = readManualEditsBuffer(cwd);
+    pendingIds = new Set((buffer.entries || []).map((entry) => entry.id).filter(Boolean));
+  } catch {
+    pendingIds = new Set(transaction.entryIds || []);
+  }
+  const shouldRollback = (transaction.entryIds || []).some((id) => pendingIds.has(id));
+  if (!shouldRollback) {
+    clearManualApplyTransaction(cwd, transaction.id);
+    return { id: transaction.id, reason, rolledBackFiles: [], rollbackFailures: [], skipped: 'entries_not_pending' };
+  }
+
+  const rolledBackFiles = [];
+  const rollbackFailures = [];
+  for (const item of transaction.files || []) {
+    const relativeFile = normalizeProjectFile(item.file, cwd);
+    if (!relativeFile) continue;
+    const absolute = path.resolve(cwd, relativeFile);
+    try {
+      if (item.exists) {
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        fs.writeFileSync(absolute, item.content || '', 'utf-8');
+      } else if (fs.existsSync(absolute)) {
+        fs.rmSync(absolute);
+      }
+      rolledBackFiles.push(relativeFile);
+    } catch (err) {
+      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
+    }
+  }
+  clearManualApplyTransaction(cwd, transaction.id);
+  recordManualEditActivity?.('manual_edit_transaction_rolled_back', {
+    id: transaction.id,
+    pageUrl: transaction.pageUrl || null,
+    reason,
+    entryIds: transaction.entryIds || [],
+    rolledBackFiles: rolledBackFiles.map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean),
+    rollbackFailures: summarizeManualDiagnostics(rollbackFailures, cwd),
+  });
+  return { id: transaction.id, reason, rolledBackFiles, rollbackFailures };
+}
+
+export function collectManualApplyFiles(batch, extraFiles = [], cwd = process.cwd()) {
+  const files = [];
+  for (const entry of batch?.entries || []) {
+    for (const op of entry.ops || []) files.push(op.sourceHint?.file);
+  }
+  for (const candidate of batch?.candidates || []) {
+    files.push(candidate.sourceHint?.relativeFile, candidate.sourceHint?.file);
+    for (const item of candidate.textMatches || []) files.push(item.file);
+    for (const item of candidate.objectKeyMatches || []) files.push(item.file);
+    for (const item of candidate.locatorMatches || []) files.push(item.file);
+    for (const item of candidate.contextTextMatches || []) files.push(item.file);
+  }
+  files.push(...(extraFiles || []));
+  return [...new Set(files)]
+    .map((file) => normalizeProjectFile(file, cwd))
+    .filter(Boolean);
+}
+
+function normalizeProjectFile(file, cwd = process.cwd()) {
+  if (!file || typeof file !== 'string') return null;
+  const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
+  const relative = path.relative(cwd, absolute);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return relative;
+}
+
+export function rollbackApplySnapshot(
+  batch,
+  rollbackSnapshot,
+  extraFiles = [],
+  _reason = 'manual_edit_apply_snapshot_rollback',
+  cwd = process.cwd(),
+) {
+  const scope = collectManualApplyFiles(batch, extraFiles, cwd);
+  const rolledBackFiles = [];
+  const rollbackFailures = [];
+  for (const relativeFile of scope) {
+    const before = rollbackSnapshot?.get(relativeFile);
+    if (!before) continue;
+    const absolute = path.resolve(cwd, relativeFile);
+    try {
+      if (before.exists) {
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        fs.writeFileSync(absolute, before.content, 'utf-8');
+      } else if (fs.existsSync(absolute)) {
+        fs.rmSync(absolute);
+      }
+      rolledBackFiles.push(relativeFile);
+    } catch (err) {
+      rollbackFailures.push({ file: relativeFile, reason: 'restore_failed', message: err.message || String(err) });
+    }
+  }
+  return { rolledBackFiles, rollbackFailures };
+}
+
+function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
+  const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
+  return `live-poll.mjs --reply ${id} done --data '<json>'`;
+}
+
+export function buildManualApplyAgentAction(eventOrId = 'EVENT_ID') {
+  return {
+    kind: 'manual_edit_apply',
+    required: 'apply_source_edits_then_reply',
+    replyCommand: manualApplyReplyCommand(eventOrId),
+    warning: 'Polling only leases this work item; it does not commit source edits.',
+  };
+}
+
+export function summarizeManualApplyEvent(event = {}, batch = event.batch, cwd = process.cwd()) {
+  const entries = Array.isArray(batch?.entries) ? batch.entries : [];
+  const opCount = entries.reduce((sum, entry) => sum + (Array.isArray(entry.ops) ? entry.ops.length : 0), 0);
+  return {
+    pageUrl: event.pageUrl || null,
+    chunk: event.chunk || null,
+    entryCount: entries.length,
+    opCount,
+    files: collectManualApplyFiles(batch, [], cwd),
+  };
+}
+
+export function summarizeManualApplyFailures(failed, cwd = process.cwd()) {
+  if (!Array.isArray(failed)) return [];
+  return failed.slice(0, 20).map((item) => ({
+    id: item.id || item.entryId || null,
+    reason: item.reason || item.message || 'failed',
+    message: compactManualLogText(item.message, 300),
+    files: Array.isArray(item.files) ? item.files.slice(0, 12).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
+    checks: summarizeManualDiagnostics(item.checks, cwd),
+    failures: summarizeManualDiagnostics(item.failures, cwd),
+    candidates: summarizeManualDiagnostics(item.candidates, cwd),
+  }));
+}
+
+export function summarizeManualDiagnostics(items, cwd = process.cwd()) {
+  if (!Array.isArray(items) || items.length === 0) return undefined;
+  return items.slice(0, 12).map((item) => ({
+    reason: item.reason || item.kind || undefined,
+    detail: compactManualLogText(item.detail, 220),
+    message: compactManualLogText(item.message, 300),
+    file: summarizeManualLogFile(item.file || item.relativeFile, cwd),
+    line: item.line || undefined,
+    ref: compactManualLogText(item.ref, 180),
+    marker: compactManualLogText(item.marker, 120),
+    files: Array.isArray(item.files) ? item.files.slice(0, 8).map((file) => summarizeManualLogFile(file, cwd)).filter(Boolean) : undefined,
+  }));
+}
+
+export function summarizeManualLogFile(file, cwd = process.cwd()) {
+  if (!file || typeof file !== 'string') return undefined;
+  if (!path.isAbsolute(file)) return file;
+  const relative = path.relative(cwd, file);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
+}
+
+export function compactManualLogText(value, max = 200) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= max) return normalized;
+  return normalized.slice(0, max) + `... [truncated ${normalized.length - max} chars]`;
+}

.agents/skills/impeccable/scripts/live/manual-edit-routes.mjs

@@ -0,0 +1,357 @@
+import { validateEvent } from './event-validation.mjs';
+import {
+  countByPage as countPendingByPage,
+  readBuffer as readManualEditsBuffer,
+  removeEntries as removeManualEditEntries,
+  stageEntry as stageManualEditEntry,
+  truncateBuffer as truncateManualEditsBuffer,
+} from './manual-edits-buffer.mjs';
+import {
+  summarizeManualApplyFailures,
+  summarizeManualDiagnostics,
+  summarizeManualLogFile,
+} from './manual-apply.mjs';
+import { buildManualEditEvidence } from '../live-manual-edit-evidence.mjs';
+import { commitManualEdits } from '../live-commit-manual-edits.mjs';
+
+export function createManualEditRoutes({
+  getToken,
+  manualApply,
+  recordManualEditActivity,
+  getManualEditStatus,
+  chatAgentLikelyActive,
+  cwd = () => process.cwd(),
+  env = () => process.env,
+} = {}) {
+  const projectCwd = () => typeof cwd === 'function' ? cwd() : cwd || process.cwd();
+  const currentEnv = () => typeof env === 'function' ? env() : env || process.env;
+
+  return function handleManualEditRoute(req, res, url) {
+    const p = url.pathname;
+
+    // Save stages entries; Apply commits the staged page batch through the
+    // local AI copy-edit runner.
+    if (p === '/manual-edit-stash' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        let msg;
+        try { msg = JSON.parse(body); } catch {
+          sendJson(res, 400, { error: 'Invalid JSON' });
+          return;
+        }
+        if (msg.token !== getToken()) {
+          sendJson(res, 401, { error: 'Unauthorized' });
+          return;
+        }
+        const error = validateEvent({ ...msg, type: 'manual_edits' });
+        if (error) {
+          sendJson(res, 400, { error });
+          return;
+        }
+        try {
+          stageManualEditEntry(projectCwd(), {
+            id: msg.id,
+            pageUrl: msg.pageUrl,
+            element: msg.element,
+            ops: msg.ops,
+          });
+        } catch (err) {
+          sendJson(res, 500, { error: 'stash_write_failed', message: err.message });
+          return;
+        }
+        const { totalCount, perPage } = countPendingByPage(projectCwd());
+        const pendingCount = perPage[msg.pageUrl] || 0;
+        recordManualEditActivity('manual_edit_stashed', {
+          id: msg.id,
+          pageUrl: msg.pageUrl,
+          opCount: msg.ops.length,
+          pendingCount,
+          totalCount,
+          hintedFileCount: new Set((msg.ops || []).map((op) => summarizeManualLogFile(op.sourceHint?.file, projectCwd())).filter(Boolean)).size,
+        });
+        sendJson(res, 200, { ok: true, pendingCount, totalCount, perPage });
+      });
+      return true;
+    }
+
+    if (p === '/manual-edit-stash' && req.method === 'GET') {
+      const token = url.searchParams.get('token');
+      if (token !== getToken()) { res.writeHead(401); res.end('Unauthorized'); return true; }
+      const pageUrl = url.searchParams.get('pageUrl') || '';
+      const { totalCount, perPage } = countPendingByPage(projectCwd());
+      const buffer = readManualEditsBuffer(projectCwd());
+      const entriesForPage = pageUrl ? buffer.entries.filter((e) => e.pageUrl === pageUrl) : buffer.entries;
+      sendJson(res, 200, {
+        count: pageUrl ? (perPage[pageUrl] || 0) : totalCount,
+        totalCount,
+        perPage,
+        entries: entriesForPage,
+      });
+      return true;
+    }
+
+    if (p === '/manual-edit-commit' && req.method === 'POST') {
+      const token = url.searchParams.get('token');
+      if (token !== getToken()) { res.writeHead(401); res.end('Unauthorized'); return true; }
+      const pageUrl = url.searchParams.get('pageUrl');
+      const asyncMode = /^(1|true|yes)$/i.test(url.searchParams.get('async') || '');
+      const repairOnly = /^(1|true|yes)$/i.test(url.searchParams.get('repair') || '');
+      const existingTransaction = manualApply.readTransaction();
+      if (repairOnly && !existingTransaction) {
+        sendJson(res, 409, { error: 'manual_edit_repair_transaction_missing' });
+        return true;
+      }
+      const recoveredTransaction = repairOnly ? null : manualApply.rollbackTransaction({
+        pageUrl,
+        reason: 'manual_edit_commit_recovered_abandoned_transaction',
+      });
+      const before = getManualEditStatus();
+      const pendingCount = pageUrl ? (before.perPage[pageUrl] || 0) : before.totalCount;
+      recordManualEditActivity('manual_edit_commit_started', {
+        pageUrl,
+        repairOnly,
+        pendingCount,
+        totalCount: before.totalCount,
+        recoveredTransaction: recoveredTransaction ? {
+          id: recoveredTransaction.id,
+          reason: recoveredTransaction.reason,
+          skipped: recoveredTransaction.skipped,
+          rolledBackFiles: recoveredTransaction.rolledBackFiles,
+          rollbackFailures: summarizeManualDiagnostics(recoveredTransaction.rollbackFailures, projectCwd()),
+        } : null,
+        ...summarizePendingManualEditBatch(projectCwd(), pageUrl),
+      });
+      if (asyncMode) {
+        sendJson(res, 202, {
+          status: 'started',
+          pendingCount,
+          totalCount: before.totalCount,
+          perPage: before.perPage,
+        });
+      }
+      (async () => {
+        let result;
+        let routedProvider = 'subprocess';
+        let transaction = null;
+        let commitBatch = null;
+        try {
+          if (pendingCount > 0) {
+            const transactionBatch = buildManualEditEvidence({ cwd: projectCwd(), pageUrl });
+            commitBatch = transactionBatch;
+            if (!repairOnly && manualApply.countOps(transactionBatch) > 0) {
+              transaction = manualApply.writeTransaction({
+                pageUrl,
+                batch: transactionBatch,
+              });
+            } else if (repairOnly && existingTransaction) {
+              transaction = existingTransaction;
+            }
+          }
+          const envValue = currentEnv();
+          const requestedMode = (envValue.IMPECCABLE_LIVE_COPY_AGENT || 'auto').trim().toLowerCase();
+          const useChatRoute = requestedMode === 'chat'
+            || (requestedMode === 'auto' && chatAgentLikelyActive());
+          if (useChatRoute) {
+            routedProvider = 'chat';
+            const timeoutMs = Number(envValue.IMPECCABLE_LIVE_COPY_AGENT_TIMEOUT_MS || 120000);
+            result = await commitManualEdits({
+              cwd: projectCwd(),
+              pageUrl,
+              provider: 'chat',
+              env: envValue,
+              timeoutMs,
+              chatAvailable: chatAgentLikelyActive,
+              applyBatchToSource: (batch, context) => manualApply.pushBatchInChunksAndWait(batch, pageUrl, context),
+              repairOnly,
+              transactionId: transaction?.id || existingTransaction?.id || null,
+              batch: commitBatch,
+            });
+          } else {
+            const timeoutMs = Number(envValue.IMPECCABLE_LIVE_COPY_AGENT_TIMEOUT_MS || 120000);
+            const provider = ['codex', 'claude', 'mock'].includes(requestedMode) ? requestedMode : undefined;
+            result = await commitManualEdits({
+              cwd: projectCwd(),
+              pageUrl,
+              provider,
+              env: envValue,
+              timeoutMs,
+              chatAvailable: chatAgentLikelyActive,
+              repairOnly,
+              transactionId: transaction?.id || existingTransaction?.id || null,
+              batch: commitBatch,
+            });
+          }
+        } catch (err) {
+          if (transaction) {
+            manualApply.rollbackTransaction({
+              pageUrl,
+              reason: 'manual_edit_commit_exception',
+            });
+          }
+          const message = err.stderr?.toString?.() || err.message;
+          recordManualEditActivity('manual_edit_commit_failed', {
+            pageUrl,
+            provider: routedProvider,
+            error: 'manual_edit_commit_failed',
+            message,
+            transactionId: transaction?.id || null,
+          });
+          if (!asyncMode) {
+            sendJson(res, 500, {
+              error: 'manual_edit_commit_failed',
+              message,
+            });
+          }
+          return;
+        } finally {
+          if (transaction) {
+            const shouldKeepTransaction = result?.needsManualDecision === true;
+            if (!shouldKeepTransaction) manualApply.clearTransaction(transaction.id);
+          }
+        }
+        const { totalCount, perPage } = countPendingByPage(projectCwd());
+        if (result?.needsManualDecision) {
+          recordManualEditActivity('manual_edit_repair_needs_decision', {
+            pageUrl,
+            provider: routedProvider,
+            transactionId: transaction?.id || existingTransaction?.id || null,
+            repair: result.repair || null,
+            failed: summarizeManualApplyFailures(result.failed, projectCwd()),
+            files: Array.isArray(result.files) ? result.files.slice(0, 20).map((file) => summarizeManualLogFile(file, projectCwd())).filter(Boolean) : [],
+            remainingCount: pageUrl ? (perPage[pageUrl] || 0) : totalCount,
+            totalCount,
+          });
+        } else {
+          recordManualEditActivity('manual_edit_commit_done', {
+            pageUrl,
+            provider: routedProvider,
+            reason: result.reason || null,
+            repair: result.repair || null,
+            appliedCount: Array.isArray(result.applied) ? result.applied.length : 0,
+            failedCount: Array.isArray(result.failed) ? result.failed.length : 0,
+            failed: summarizeManualApplyFailures(result.failed, projectCwd()),
+            files: Array.isArray(result.files) ? result.files.slice(0, 20).map((file) => summarizeManualLogFile(file, projectCwd())).filter(Boolean) : [],
+            warnings: summarizeManualDiagnostics(result.warnings, projectCwd()),
+            rolledBackFiles: Array.isArray(result.rolledBackFiles) ? result.rolledBackFiles.slice(0, 20).map((file) => summarizeManualLogFile(file, projectCwd())).filter(Boolean) : [],
+            rollbackFailures: summarizeManualDiagnostics(result.rollbackFailures, projectCwd()),
+            unreportedFiles: Array.isArray(result.unreportedFiles) ? result.unreportedFiles.slice(0, 20).map((file) => summarizeManualLogFile(file, projectCwd())).filter(Boolean) : undefined,
+            noteCount: Array.isArray(result.notes) ? result.notes.length : 0,
+            cleared: result.cleared || 0,
+            remainingCount: pageUrl ? (perPage[pageUrl] || 0) : totalCount,
+            totalCount,
+          });
+        }
+        if (!asyncMode) {
+          sendJson(res, 200, { ...result, totalCount, perPage });
+        }
+      })();
+      return true;
+    }
+
+    if (p === '/manual-edit-repair-decision' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; });
+      req.on('end', () => {
+        let payload = {};
+        try { payload = body ? JSON.parse(body) : {}; } catch {
+          sendJson(res, 400, { error: 'Invalid JSON' });
+          return;
+        }
+        const token = payload.token || url.searchParams.get('token');
+        if (token !== getToken()) { res.writeHead(401); res.end('Unauthorized'); return; }
+        const pageUrl = payload.pageUrl || url.searchParams.get('pageUrl') || null;
+        const action = String(payload.action || url.searchParams.get('action') || '').trim().toLowerCase();
+        if (action !== 'rollback') {
+          sendJson(res, 400, { error: 'unsupported_manual_edit_repair_decision', action });
+          return;
+        }
+        const rollback = manualApply.rollbackTransaction({
+          pageUrl,
+          reason: 'manual_edit_user_requested_rollback',
+        });
+        const { totalCount, perPage } = countPendingByPage(projectCwd());
+        const response = {
+          action,
+          pageUrl,
+          rollback,
+          remainingCount: pageUrl ? (perPage[pageUrl] || 0) : totalCount,
+          totalCount,
+          perPage,
+        };
+        recordManualEditActivity('manual_edit_repair_rollback_done', response);
+        sendJson(res, 200, response);
+      });
+      return true;
+    }
+
+    if (p === '/manual-edit-discard' && req.method === 'POST') {
+      const token = url.searchParams.get('token');
+      if (token !== getToken()) { res.writeHead(401); res.end('Unauthorized'); return true; }
+      const pageUrl = url.searchParams.get('pageUrl');
+      let discarded;
+      let discardedEntries = [];
+      let canceledApplyEvents = [];
+      let transactionRollback = null;
+      try {
+        const buffer = readManualEditsBuffer(projectCwd());
+        transactionRollback = manualApply.rollbackTransaction({
+          pageUrl,
+          reason: 'manual_edit_discarded',
+        });
+        if (pageUrl) {
+          discardedEntries = buffer.entries.filter((entry) => entry.pageUrl === pageUrl);
+          discarded = removeManualEditEntries(projectCwd(), (entry) => entry.pageUrl === pageUrl);
+        } else {
+          discardedEntries = buffer.entries;
+          discarded = truncateManualEditsBuffer(projectCwd());
+        }
+        canceledApplyEvents = manualApply.cancelPendingEvents(pageUrl);
+      } catch (err) {
+        sendJson(res, 500, { error: 'discard_failed', message: err.message });
+        return true;
+      }
+      const { totalCount, perPage } = countPendingByPage(projectCwd());
+      recordManualEditActivity('manual_edit_discarded', {
+        pageUrl,
+        discarded,
+        canceledApplyIds: canceledApplyEvents.map((event) => event.id),
+        transactionRollback: transactionRollback ? {
+          id: transactionRollback.id,
+          rolledBackFiles: transactionRollback.rolledBackFiles?.map((file) => summarizeManualLogFile(file, projectCwd())).filter(Boolean) || [],
+          rollbackFailures: summarizeManualDiagnostics(transactionRollback.rollbackFailures, projectCwd()),
+          skipped: transactionRollback.skipped,
+        } : undefined,
+        totalCount,
+      });
+      sendJson(res, 200, { discarded, entries: discardedEntries, canceledApplyEvents, totalCount, perPage });
+      return true;
+    }
+
+    if (p === '/manual-edit' && req.method === 'POST') {
+      sendJson(res, 410, { error: '/manual-edit is removed; use /manual-edit-stash and /manual-edit-commit for staged copy edits.' });
+      return true;
+    }
+
+    return false;
+  };
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function summarizePendingManualEditBatch(cwd, pageUrl = null) {
+  try {
+    const buffer = readManualEditsBuffer(cwd);
+    const entries = (buffer.entries || [])
+      .filter((entry) => !pageUrl || entry.pageUrl === pageUrl);
+    return {
+      pendingEntryCount: entries.length,
+      pendingOpCount: entries.reduce((sum, entry) => sum + (entry.ops?.length || 0), 0),
+    };
+  } catch (err) {
+    return { pendingSummaryError: err.message || String(err) };
+  }
+}

.agents/skills/impeccable/scripts/live/manual-edits-buffer.mjs

@@ -12,7 +12,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { getLiveDir } from './impeccable-paths.mjs';
+import { getLiveDir } from '../lib/impeccable-paths.mjs';
 
 const BUFFER_VERSION = 1;
 const BUFFER_FILENAME = 'pending-manual-edits.json';

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

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { getLegacyLiveSessionsDir, getLiveSessionsDir } from './impeccable-paths.mjs';
+import { getLegacyLiveSessionsDir, getLiveSessionsDir } from '../lib/impeccable-paths.mjs';
 
 const COMPLETED_PHASES = new Set(['completed', 'discarded']);
 
@@ -106,6 +106,8 @@ function baseSnapshot(id) {
     phase: 'new',
     pageUrl: null,
     sourceFile: null,
+    previewFile: null,
+    previewMode: null,
     expectedVariants: 0,
     arrivedVariants: 0,
     visibleVariant: null,
@@ -177,8 +179,10 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
     case 'variants_ready':
     case 'agent_done':
       next.phase = event.carbonize === true ? 'carbonize_required' : 'variants_ready';
-      next.sourceFile = event.file ?? next.sourceFile;
-      next.arrivedVariants = event.arrivedVariants ?? (next.arrivedVariants ?? next.expectedVariants);
+      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
+      next.previewFile = event.previewFile ?? next.previewFile;
+      next.previewMode = event.previewMode ?? next.previewMode;
+      next.arrivedVariants = event.arrivedVariants ?? (next.expectedVariants || next.arrivedVariants || 0);
       next.pendingEventSeq = null;
       next.pendingEvent = null;
       if (event.carbonize === true) {
@@ -190,12 +194,19 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
       }
       break;
     case 'checkpoint':
+      if (COMPLETED_PHASES.has(next.phase)) {
+        next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
+        break;
+      }
       if ((event.revision ?? 0) >= (next.checkpointRevision ?? 0)) {
         next.phase = event.phase ?? next.phase;
         next.checkpointRevision = event.revision ?? next.checkpointRevision;
         next.activeOwner = event.owner ?? next.activeOwner;
         next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
         next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
+        next.sourceFile = event.sourceFile ?? next.sourceFile;
+        next.previewFile = event.previewFile ?? next.previewFile;
+        next.previewMode = event.previewMode ?? next.previewMode;
         if (event.paramValues) next.paramValues = { ...event.paramValues };
       } else {
         next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision });
@@ -223,6 +234,10 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
       break;
     case 'steer_done':
       next.phase = 'steer_done';
+      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
+      next.previewFile = event.previewFile ?? next.previewFile;
+      next.previewMode = event.previewMode ?? next.previewMode;
+      next.message = event.message ?? next.message;
       next.pendingEventSeq = null;
       next.pendingEvent = null;
       break;
@@ -238,6 +253,9 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
       break;
     case 'complete':
       next.phase = 'completed';
+      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
+      next.previewFile = event.previewFile ?? next.previewFile;
+      next.previewMode = event.previewMode ?? next.previewMode;
       next.pendingEventSeq = null;
       next.pendingEvent = null;
       break;

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

@@ -0,0 +1,826 @@
+/**
+ * Svelte live-mode component injection helpers.
+ *
+ * Variants are real .svelte components under node_modules/.impeccable-live/<session-id>/.
+ * The browser mounts them via Svelte 5 mount(); accept inlines the chosen
+ * variant back into the route source with props mapped to original bindings.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+
+export const SVELTE_COMPONENT_ROOT = 'node_modules/.impeccable-live';
+export const SVELTE_RUNTIME_FILE = `${SVELTE_COMPONENT_ROOT}/__runtime.js`;
+export const DEFERRED_ACCEPTS_FILE = '.impeccable/live/deferred-svelte-component-accepts.json';
+
+const MUSTACHE_RE = /\{([^{}]+)\}/g;
+
+export function shouldUseSvelteComponentInjection(filePath) {
+  if (/^(0|false|no)$/i.test(process.env.IMPECCABLE_LIVE_SVELTE_COMPONENT || '')) return false;
+  return path.extname(filePath).toLowerCase() === '.svelte';
+}
+
+export function componentSessionDir(id, cwd = process.cwd()) {
+  return path.join(cwd, SVELTE_COMPONENT_ROOT, id);
+}
+
+export function manifestPathForSession(id, cwd = process.cwd()) {
+  return path.join(componentSessionDir(id, cwd), 'manifest.json');
+}
+
+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');
+  return file;
+}
+
+/**
+ * Extract ordered unique mustache expressions from markup (not inside <!-- -->).
+ */
+export function extractMustacheExpressions(text) {
+  const expressions = [];
+  const seen = new Set();
+  const lines = String(text || '').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('<!--')) continue;
+    let match;
+    MUSTACHE_RE.lastIndex = 0;
+    while ((match = MUSTACHE_RE.exec(line)) !== null) {
+      const expr = match[1].trim();
+      if (!expr || seen.has(expr)) continue;
+      seen.add(expr);
+      expressions.push(expr);
+    }
+  }
+  return expressions;
+}
+
+export function buildPropContract(expressions) {
+  return expressions.map((expr, index) => {
+    const derived = derivePropName(expr, index);
+    return {
+      prop: derived,
+      expr,
+      placeholder: `{${expr}}`,
+    };
+  });
+}
+
+function derivePropName(expr, index) {
+  const tail = expr.match(/(?:\.|\[)(\w+)\s*\]?$/);
+  if (tail && tail[1] && /^[A-Za-z_$][\w$]*$/.test(tail[1])) {
+    return tail[1];
+  }
+  return `prop${index}`;
+}
+
+export function substituteExprsWithProps(markup, contract) {
+  let out = String(markup || '');
+  for (const entry of contract) {
+    out = out.split(entry.placeholder).join(`{${entry.prop}}`);
+  }
+  return out;
+}
+
+export function substitutePropsWithExprs(markup, contract) {
+  let out = String(markup || '');
+  for (const entry of contract) {
+    out = out.split(`{${entry.prop}}`).join(`{${entry.expr}}`);
+  }
+  return out;
+}
+
+export function parseSvelteComponentFile(content) {
+  const text = String(content || '');
+  const scriptMatch = text.match(/^([\s\S]*?)<script\b[^>]*>[\s\S]*?<\/script>/i);
+  const withoutScript = scriptMatch ? text.slice(scriptMatch[0].length) : text;
+  const styleMatch = withoutScript.match(/<style\b[^>]*>[\s\S]*?<\/style\s*>/i);
+  const styleBlock = styleMatch ? styleMatch[0] : '';
+  const markup = styleMatch
+    ? withoutScript.slice(0, styleMatch.index).trim()
+    : withoutScript.trim();
+  const cssLines = styleBlock
+    ? styleBlock
+      .replace(/^<style\b[^>]*>/i, '')
+      .replace(/<\/style\s*>$/i, '')
+      .split('\n')
+      .map((line) => line.trimEnd())
+    : [];
+  while (cssLines.length > 0 && cssLines[0].trim() === '') cssLines.shift();
+  while (cssLines.length > 0 && cssLines[cssLines.length - 1].trim() === '') cssLines.pop();
+  return { markup, cssLines, styleBlock };
+}
+
+function buildPropsScript(contract) {
+  if (contract.length === 0) {
+    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+  }
+  const names = contract.map((c) => c.prop).join(', ');
+  const typeFields = contract.map((c) => `    ${c.prop}: string;`).join('\n');
+  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+}
+
+function buildVariantStub(variantNum, originalWithProps, contract) {
+  const propsComment = contract.length > 0
+    ? `\n<!-- Props: ${contract.map((c) => `${c.prop} <- {${c.expr}}`).join(', ')} -->\n`
+    : '';
+  return `${buildPropsScript(contract)}${propsComment}${originalWithProps.trim()}\n\n<style>\n  /* Variant ${variantNum}: add scoped CSS here */\n</style>\n`;
+}
+
+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`;
+}
+
+export function scaffoldSvelteComponentSession({
+  id,
+  count,
+  sourceFile,
+  sourceStartLine,
+  sourceEndLine,
+  originalLines,
+  cwd = process.cwd(),
+}) {
+  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 manifest = {
+    id,
+    previewMode: 'svelte-component',
+    sourceFile: sourceFile.split(path.sep).join('/'),
+    sourceStartLine,
+    sourceEndLine,
+    count,
+    propContract: contract,
+    originalMarkup,
+    componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
+    runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
+  };
+
+  fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+
+  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');
+    }
+  }
+
+  return {
+    manifest,
+    manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
+    componentDir: manifest.componentDir,
+    propContract: contract,
+  };
+}
+
+export function scaffoldSvelteComponentInsertSession({
+  id,
+  count,
+  sourceFile,
+  insertLine,
+  position,
+  anchorStartLine,
+  anchorEndLine,
+  anchorLines,
+  cwd = process.cwd(),
+}) {
+  ensureRuntimeHelper(cwd);
+  const dir = componentSessionDir(id, cwd);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const anchorMarkup = (anchorLines || []).join('\n');
+  const manifest = {
+    id,
+    mode: 'insert',
+    previewMode: 'svelte-component',
+    sourceFile: sourceFile.split(path.sep).join('/'),
+    insertLine,
+    position,
+    anchorStartLine,
+    anchorEndLine,
+    originalMarkup: anchorMarkup,
+    anchorMarkup,
+    count,
+    propContract: [],
+    componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
+    runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
+  };
+
+  fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+
+  for (let n = 1; n <= count; n++) {
+    const variantFile = path.join(dir, `v${n}.svelte`);
+    if (!fs.existsSync(variantFile)) {
+      fs.writeFileSync(variantFile, buildInsertVariantStub(n), 'utf-8');
+    }
+  }
+
+  return {
+    manifest,
+    manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
+    componentDir: manifest.componentDir,
+    propContract: [],
+  };
+}
+
+export function findSvelteComponentManifest(id, cwd = process.cwd()) {
+  const direct = manifestPathForSession(id, 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 */ }
+  }
+  return null;
+}
+
+export function readManifest(manifestPath) {
+  const data = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  return {
+    ...data,
+    manifestPath,
+  };
+}
+
+export function resolveSourceFile(sourceFile, cwd = process.cwd()) {
+  if (!sourceFile || path.isAbsolute(sourceFile)) {
+    throw new Error('Invalid svelte-component source file');
+  }
+  const full = path.resolve(cwd, sourceFile);
+  const rel = path.relative(cwd, full);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('Svelte-component source file escapes project root');
+  }
+  if (!fs.existsSync(full)) {
+    throw new Error('Svelte-component source file not found: ' + sourceFile);
+  }
+  return full;
+}
+
+function appendCssToSvelteStyle(lines, cssLines) {
+  const closeIdx = findLastStyleCloseLine(lines);
+  const prepared = ['', ...cssLines.map((line) => (line.trim() === '' ? '' : '  ' + line.trimStart()))];
+  if (closeIdx === -1) {
+    return [...lines, '', '<style>', ...prepared.slice(1), '</style>'];
+  }
+  return [
+    ...lines.slice(0, closeIdx),
+    ...prepared,
+    ...lines.slice(closeIdx),
+  ];
+}
+
+function findLastStyleCloseLine(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (/<\/style\s*>/.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+function bakeParamValuesInCss(cssLines, paramValues) {
+  if (!paramValues || Object.keys(paramValues).length === 0) return cssLines;
+  return cssLines.map((line) => {
+    let out = line;
+    for (const [key, value] of Object.entries(paramValues)) {
+      const varName = `--p-${key}`;
+      out = out.replace(new RegExp(`var\\(${escapeRegExp(varName)}(?:,\\s*[^)]+)?\\)`, 'g'), String(value));
+    }
+    return out;
+  });
+}
+
+function sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues = null, rootTag = 'div') {
+  const css = String((cssLines || []).join('\n'));
+  if (!/data-impeccable-variant|impeccable-variant-ready/.test(css)) return cssLines;
+
+  const rules = parseCssRules(css);
+  const output = [];
+  for (const rule of rules) {
+    appendSanitizedCssRule(output, rule, variantNum, paramValues, rootTag);
+  }
+  return output.join('\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== '');
+}
+
+function appendSanitizedCssRule(output, rule, variantNum, paramValues, rootTag) {
+  const prelude = rule.prelude.trim();
+  const body = rule.body.trim();
+  if (!prelude || !body || /--impeccable-variant-ready\s*:/.test(body)) return;
+
+  if (/^@scope\b/i.test(prelude)) {
+    if (/data-impeccable-variant/.test(prelude) && !selectorHasVariant(prelude, variantNum)) return;
+    const inner = parseCssRules(body);
+    for (const innerRule of inner) {
+      const rewrittenPrelude = rewriteAcceptedSvelteSelector(innerRule.prelude, variantNum, paramValues, rootTag, true);
+      if (!rewrittenPrelude || /--impeccable-variant-ready\s*:/.test(innerRule.body)) continue;
+      output.push(formatCssRule(rewrittenPrelude, innerRule.body.trim()));
+    }
+    return;
+  }
+
+  const rewrittenPrelude = rewriteAcceptedSvelteSelector(prelude, variantNum, paramValues, rootTag, false);
+  if (!rewrittenPrelude) return;
+  output.push(formatCssRule(rewrittenPrelude, body));
+}
+
+function parseCssRules(css) {
+  const rules = [];
+  const text = String(css || '');
+  let i = 0;
+  while (i < text.length) {
+    while (i < text.length && /\s/.test(text[i])) i++;
+    const preludeStart = i;
+    while (i < text.length && text[i] !== '{') i++;
+    if (i >= text.length) break;
+    const prelude = text.slice(preludeStart, i).trim();
+    i++;
+    const bodyStart = i;
+    let depth = 1;
+    let quote = null;
+    let comment = false;
+    while (i < text.length && depth > 0) {
+      const ch = text[i];
+      const next = text[i + 1];
+      if (comment) {
+        if (ch === '*' && next === '/') {
+          comment = false;
+          i += 2;
+          continue;
+        }
+        i++;
+        continue;
+      }
+      if (quote) {
+        if (ch === '\\') {
+          i += 2;
+          continue;
+        }
+        if (ch === quote) quote = null;
+        i++;
+        continue;
+      }
+      if (ch === '/' && next === '*') {
+        comment = true;
+        i += 2;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        quote = ch;
+        i++;
+        continue;
+      }
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      i++;
+    }
+    const body = text.slice(bodyStart, Math.max(bodyStart, i - 1));
+    if (prelude) rules.push({ prelude, body });
+  }
+  return rules;
+}
+
+function rewriteAcceptedSvelteSelector(prelude, variantNum, paramValues, rootTag, fromScope) {
+  const selectors = splitSelectorList(prelude);
+  const rewritten = [];
+  for (const selector of selectors) {
+    const next = rewriteAcceptedSvelteSelectorPart(selector, variantNum, paramValues, rootTag, fromScope);
+    if (next) rewritten.push(next);
+  }
+  return rewritten.join(', ');
+}
+
+function rewriteAcceptedSvelteSelectorPart(selector, variantNum, paramValues, rootTag, fromScope) {
+  let out = selector.trim();
+  const hasVariant = /data-impeccable-variant/.test(out);
+  if (hasVariant && !selectorHasVariant(out, variantNum)) return '';
+  if (hasVariant) {
+    out = out.replace(variantSelectorRegex(variantNum), '');
+    out = out.replace(/\[data-impeccable-variant=(["']).*?\1\]/g, '');
+  }
+
+  const paramResult = rewriteParamSelectors(out, paramValues);
+  if (!paramResult.keep) return '';
+  out = paramResult.selector;
+
+  out = out
+    .replace(/:scope(?:\[[^\]]+\])?\s*>\s*/g, '')
+    .replace(/:scope(?:\[[^\]]+\])?/g, rootTag || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  out = out.replace(/^[>+~]\s*/, '').trim();
+  if (!out && (hasVariant || fromScope)) return rootTag || ':global(*)';
+  return out;
+}
+
+function rewriteParamSelectors(selector, paramValues) {
+  let keep = true;
+  const next = selector.replace(/\[data-p-([A-Za-z0-9_-]+)(?:=(["'])(.*?)\2)?\]/g, (_match, key, _quote, expected) => {
+    if (!paramValues || !Object.prototype.hasOwnProperty.call(paramValues, key)) return '';
+    const actual = paramValues[key];
+    if (expected != null && String(actual) !== String(expected)) {
+      keep = false;
+      return '';
+    }
+    if (expected == null && (actual === false || actual == null || actual === 'false' || actual === 'off' || actual === '0')) {
+      keep = false;
+      return '';
+    }
+    return '';
+  });
+  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);
+}
+
+function variantSelectorRegex(variantNum) {
+  return new RegExp(`\\[data-impeccable-variant=(["'])${escapeRegExp(String(variantNum))}\\1\\]`, 'g');
+}
+
+function formatCssRule(selector, body) {
+  return `${selector} { ${body.trim()} }`;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function inlineSvelteComponentAccept(manifest, variantNum, paramValues = null, cwd = process.cwd()) {
+  const sourceFile = resolveSourceFile(manifest.sourceFile, cwd);
+  const variantPath = path.join(cwd, manifest.componentDir, `v${variantNum}.svelte`);
+  const resultBase = {
+    file: manifest.sourceFile,
+    sourceFile: manifest.sourceFile,
+    previewMode: 'svelte-component',
+    componentDir: manifest.componentDir,
+    carbonize: false,
+  };
+  if (!fs.existsSync(variantPath)) {
+    return { handled: false, error: `Variant ${variantNum} not found`, ...resultBase };
+  }
+
+  const { markup, cssLines } = parseSvelteComponentFile(fs.readFileSync(variantPath, 'utf-8'));
+  if (manifest.mode === 'insert') {
+    return inlineSvelteComponentInsertAccept({
+      manifest,
+      markup,
+      cssLines,
+      variantNum,
+      paramValues,
+      sourceFile,
+      resultBase,
+      cwd,
+    });
+  }
+
+  const rootTag = matchOpeningTag(markup)?.tag || 'div';
+  const contract = manifest.propContract || [];
+  const mergedMarkup = mergeOriginalTopLevelAttrs(markup, manifest.originalMarkup || '');
+  const restoredMarkup = substitutePropsWithExprs(mergedMarkup, contract)
+    .split('\n')
+    .map((line) => line.trimEnd());
+
+  const sourceContent = fs.readFileSync(sourceFile, 'utf-8');
+  const sourceLines = sourceContent.split('\n');
+  const start = Number(manifest.sourceStartLine) - 1;
+  const end = Number(manifest.sourceEndLine) - 1;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end >= sourceLines.length) {
+    return { handled: false, error: 'Invalid source line range for ' + manifest.sourceFile, ...resultBase };
+  }
+
+  const indent = sourceLines[start].match(/^(\s*)/)?.[1] || '';
+  const indentedMarkup = restoredMarkup.map((line) => {
+    if (line.trim() === '') return '';
+    return indent + line.trimStart();
+  });
+
+  let newLines = [
+    ...sourceLines.slice(0, start),
+    ...indentedMarkup,
+    ...sourceLines.slice(end + 1),
+  ];
+
+  const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
+  const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
+  if (bakedCss.length > 0) {
+    newLines = appendCssToSvelteStyle(newLines, bakedCss);
+  }
+
+  try {
+    fs.writeFileSync(sourceFile, newLines.join('\n'), 'utf-8');
+  } catch (err) {
+    return { handled: false, error: 'Failed to write Svelte source: ' + err.message, ...resultBase };
+  }
+  removeSvelteComponentSession(manifest.id, cwd);
+
+  return {
+    handled: true,
+    ...resultBase,
+  };
+}
+
+function inlineSvelteComponentInsertAccept({
+  manifest,
+  markup,
+  cssLines,
+  variantNum,
+  paramValues,
+  sourceFile,
+  resultBase,
+  cwd,
+}) {
+  if (!svelteMarkupHasVisibleContent(markup)) {
+    return { handled: false, error: 'Accepted Svelte insert variant is empty', ...resultBase };
+  }
+  if (/\bdata-impeccable-[\w-]*\s*=/.test(markup)) {
+    return { handled: false, error: 'Accepted Svelte insert variant contains preview-only data-impeccable attributes', ...resultBase };
+  }
+
+  const rootTag = matchOpeningTag(markup)?.tag || 'div';
+  const restoredMarkup = String(markup || '')
+    .split('\n')
+    .map((line) => line.trimEnd());
+  const sourceContent = fs.readFileSync(sourceFile, 'utf-8');
+  const sourceLines = sourceContent.split('\n');
+  const insertIndex = Number(manifest.insertLine) - 1;
+  if (!Number.isInteger(insertIndex) || insertIndex < 0 || insertIndex > sourceLines.length) {
+    return { handled: false, error: 'Invalid insert line for ' + manifest.sourceFile, ...resultBase };
+  }
+
+  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();
+  });
+
+  let newLines = [
+    ...sourceLines.slice(0, insertIndex),
+    ...indentedMarkup,
+    ...sourceLines.slice(insertIndex),
+  ];
+
+  const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
+  const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
+  if (bakedCss.length > 0) {
+    newLines = appendCssToSvelteStyle(newLines, bakedCss);
+  }
+
+  try {
+    fs.writeFileSync(sourceFile, newLines.join('\n'), 'utf-8');
+  } catch (err) {
+    return { handled: false, error: 'Failed to write Svelte source: ' + err.message, ...resultBase };
+  }
+  removeSvelteComponentSession(manifest.id, cwd);
+
+  return {
+    handled: true,
+    ...resultBase,
+  };
+}
+
+function svelteMarkupHasVisibleContent(markup) {
+  const text = String(markup || '')
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length > 0) return true;
+  return /<(img|svg|canvas|video|audio|picture|input|button|select|textarea)\b/i.test(markup || '');
+}
+
+function mergeOriginalTopLevelAttrs(markup, originalMarkup) {
+  const variantOpen = matchOpeningTag(markup);
+  const originalOpen = matchOpeningTag(originalMarkup);
+  if (!variantOpen || !originalOpen) return markup;
+  if (variantOpen.tag.toLowerCase() !== originalOpen.tag.toLowerCase()) return markup;
+
+  const variantAttrs = parseAttrSegments(variantOpen.attrs);
+  const originalAttrs = parseAttrSegments(originalOpen.attrs);
+  const additions = [];
+  let attrs = variantOpen.attrs;
+
+  const originalClass = originalAttrs.get('class');
+  const variantClass = variantAttrs.get('class');
+  if (originalClass && variantClass) {
+    const merged = mergeStaticClassAttr(originalClass, variantClass);
+    if (merged) {
+      attrs = attrs.slice(0, variantClass.start) + merged + attrs.slice(variantClass.end);
+      variantAttrs.set('class', { ...variantClass, raw: merged });
+    }
+  } else if (originalClass && !variantClass) {
+    additions.push(originalClass.raw);
+  }
+
+  for (const [name, attr] of originalAttrs) {
+    if (name === 'class') continue;
+    if (!variantAttrs.has(name)) additions.push(attr.raw);
+  }
+
+  if (additions.length === 0 && attrs === variantOpen.attrs) return markup;
+  const nextOpen = variantOpen.prefix
+    + variantOpen.tag
+    + attrs
+    + additions.map((attr) => ' ' + attr.trim()).join('')
+    + variantOpen.close;
+  return markup.slice(0, variantOpen.index) + nextOpen + markup.slice(variantOpen.index + variantOpen.raw.length);
+}
+
+function matchOpeningTag(markup) {
+  const match = String(markup || '').match(/^(\s*<)([A-Za-z][\w:-]*)([^>]*?)(\/?>)/);
+  if (!match) return null;
+  return {
+    raw: match[0],
+    prefix: match[1],
+    tag: match[2],
+    attrs: match[3] || '',
+    close: match[4],
+    index: match.index || 0,
+  };
+}
+
+function parseAttrSegments(attrs) {
+  const out = new Map();
+  const re = /([A-Za-z_:][\w:.-]*)(?:\s*=\s*(?:"[^"]*"|'[^']*'|\{[^}]*\}|[^\s"'>=]+))?/g;
+  let match;
+  while ((match = re.exec(attrs))) {
+    const raw = match[0];
+    const name = match[1];
+    out.set(name, {
+      name,
+      raw,
+      start: match.index,
+      end: match.index + raw.length,
+    });
+  }
+  return out;
+}
+
+function mergeStaticClassAttr(originalClass, variantClass) {
+  const originalValue = originalClass.raw.match(/class\s*=\s*(["'])(.*?)\1/);
+  const variantValue = variantClass.raw.match(/class\s*=\s*(["'])(.*?)\1/);
+  if (!originalValue || !variantValue) return null;
+  const quote = variantValue[1];
+  const classes = [
+    ...variantValue[2].split(/\s+/),
+    ...originalValue[2].split(/\s+/),
+  ].filter(Boolean);
+  return `class=${quote}${[...new Set(classes)].join(' ')}${quote}`;
+}
+
+export function removeSvelteComponentSession(id, cwd = process.cwd()) {
+  const dir = componentSessionDir(id, cwd);
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } 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;
+    try {
+      fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
+    } catch { /* non-fatal */ }
+  }
+}
+
+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');
+}
+
+export function readDeferredAccepts(cwd = process.cwd()) {
+  const file = deferredAcceptsPath(cwd);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return { accepts: [] };
+  }
+}
+
+export function writeDeferredAccept(entry, cwd = process.cwd()) {
+  const file = deferredAcceptsPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const data = readDeferredAccepts(cwd);
+  data.accepts = (data.accepts || []).filter((item) => item.id !== entry.id);
+  data.accepts.push({ ...entry, createdAt: new Date().toISOString() });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+export function applyDeferredSvelteComponentAccepts(cwd = process.cwd()) {
+  const file = deferredAcceptsPath(cwd);
+  const data = readDeferredAccepts(cwd);
+  const pending = Array.isArray(data.accepts) ? data.accepts : [];
+  const results = [];
+  const remaining = [];
+  for (const entry of pending) {
+    try {
+      const manifest = findSvelteComponentManifest(entry.id, cwd);
+      if (!manifest) {
+        results.push({ id: entry.id, ok: false, error: 'manifest not found' });
+        remaining.push(entry);
+        continue;
+      }
+      const result = inlineSvelteComponentAccept(
+        manifest,
+        entry.variantNum,
+        entry.paramValues || null,
+        cwd,
+      );
+      results.push({ id: entry.id, ok: result.handled !== false, result });
+      if (result.handled === false) remaining.push(entry);
+    } catch (err) {
+      results.push({ id: entry.id, ok: false, error: err.message });
+      remaining.push(entry);
+    }
+  }
+  if (remaining.length > 0) {
+    fs.writeFileSync(file, JSON.stringify({ accepts: remaining }, null, 2) + '\n', 'utf-8');
+  } else {
+    try { fs.rmSync(file, { force: true }); } catch {}
+  }
+  return { applied: results.filter((r) => r.ok).length, failed: results.filter((r) => !r.ok).length, results };
+}
+
+export function buildSvelteComponentCssAuthoring(count) {
+  const variantNumbers = Array.from({ length: count }, (_, i) => i + 1);
+  return {
+    mode: 'svelte-component',
+    styleTag: null,
+    strategy: 'component-style-block',
+    rulePattern: '.semantic-class { ... }',
+    selectorExamples: variantNumbers.map(() => '.expense-row { padding: 22px; }'),
+    requirements: [
+      'Write each variant as a real Svelte component file (v1.svelte, v2.svelte, ...).',
+      'Keep the prop names from propContract; bind dynamic text with {propName}, not literal snapshot text.',
+      'Put variant CSS in the component <style> block using semantic class selectors.',
+      'Author param-driven CSS against var(--p-<id>, default) and [data-p-<id>] using :global(...) so the runtime knob values reach the mounted root.',
+      'Declare params in componentDir/params.json keyed by variant number (e.g. {"1": [...], "2": [...]}), NOT as a data-impeccable-params attribute.',
+      'Do not use @scope or data-impeccable-variant selectors in component files.',
+      'Do not edit the route source file during generation; only edit files under componentDir.',
+    ],
+    forbidden: [
+      'Do not use @scope blocks in Svelte component variants.',
+      'Do not copy live DOM snapshot text into markup when propContract provides bindings.',
+      'Do not add data-impeccable-* attributes inside component files. Svelte parses { in attribute values as an expression, so data-impeccable-params with JSON breaks the build; use componentDir/params.json instead.',
+    ],
+    paramsFile: 'params.json',
+  };
+}

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

@@ -0,0 +1,274 @@
+/**
+ * SvelteKit live-mode adapter.
+ *
+ * SvelteKit must not be patched through src/app.html. That file is a document
+ * template, not framework-owned component chrome. The adapter keeps SvelteKit
+ * work limited to mounting a dev-only shadow host from +layout.svelte; the
+ * actual live UI remains the shared plain-DOM browser chrome.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot.svelte';
+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';";
+
+export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
+  const appHtml = findSvelteKitAppHtml(cwd, config);
+  if (!appHtml) return null;
+  const hasTemplateMarkers = fileIncludes(path.join(cwd, appHtml), '%sveltekit.body%')
+    && fileIncludes(path.join(cwd, appHtml), '%sveltekit.head%');
+  if (!hasTemplateMarkers) return null;
+
+  const hasSvelteConfig = fs.existsSync(path.join(cwd, 'svelte.config.js'))
+    || fs.existsSync(path.join(cwd, 'svelte.config.mjs'))
+    || fs.existsSync(path.join(cwd, 'svelte.config.cjs'))
+    || fs.existsSync(path.join(cwd, 'svelte.config.ts'));
+  const hasKitPackage = packageHasSvelteKit(cwd);
+  if (!hasSvelteConfig && !hasKitPackage) return null;
+
+  return {
+    appHtml,
+    layoutFile: findSvelteKitLayout(cwd),
+    rootComponent: SVELTE_LIVE_ROOT_COMPONENT,
+  };
+}
+
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('SvelteKit live adapter requires a numeric port');
+  }
+  const detected = detectSvelteKitProject(cwd, config);
+  if (!detected) return null;
+
+  ensureSvelteLiveRootComponent(cwd, Number(port));
+
+  const layoutRel = detected.layoutFile;
+  const layoutAbs = path.join(cwd, layoutRel);
+  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);
+  fs.writeFileSync(layoutAbs, after, 'utf-8');
+
+  return {
+    file: layoutRel,
+    adapter: 'sveltekit',
+    inserted: after !== before || !layoutExisted,
+    appHtmlUntouched: true,
+    rootComponent: SVELTE_LIVE_ROOT_COMPONENT,
+  };
+}
+
+export function removeSvelteKitLiveAdapter({ cwd = process.cwd(), config = null } = {}) {
+  const detected = detectSvelteKitProject(cwd, config);
+  if (!detected) return null;
+
+  const layoutAbs = path.join(cwd, detected.layoutFile);
+  let removed = false;
+  if (fs.existsSync(layoutAbs)) {
+    const before = fs.readFileSync(layoutAbs, 'utf-8');
+    const after = unpatchSvelteLayout(before);
+    if (after !== before) {
+      fs.writeFileSync(layoutAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const rootAbs = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
+  if (fs.existsSync(rootAbs)) {
+    fs.rmSync(rootAbs, { force: true });
+    removed = true;
+  }
+
+  pruneEmptyDir(path.dirname(rootAbs), path.join(cwd, 'src'));
+
+  return {
+    file: detected.layoutFile,
+    adapter: 'sveltekit',
+    removed,
+    appHtmlUntouched: true,
+    rootComponent: SVELTE_LIVE_ROOT_COMPONENT,
+  };
+}
+
+export function patchSvelteLayout(content) {
+  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;
+    }
+  }
+
+  if (!out.includes(SVELTE_LAYOUT_MARKER_OPEN)) {
+    const block = `${SVELTE_LAYOUT_MARKER_OPEN}\n<ImpeccableLiveRoot />\n${SVELTE_LAYOUT_MARKER_CLOSE}\n`;
+    const renderMatch = out.match(/\{@render\s+children(?:\?\.)?\(\)\s*\}/);
+    const slotMatch = out.match(/<slot\s*\/?>/);
+    const match = renderMatch || slotMatch;
+    if (match) {
+      out = out.slice(0, match.index) + block + out.slice(match.index);
+    } else {
+      out = out.replace(/\s*$/, '\n\n' + block);
+    }
+  }
+
+  return out;
+}
+
+export function unpatchSvelteLayout(content) {
+  let out = String(content || '');
+  const blockRe = new RegExp(
+    '([ \\t]*)' + escapeRegExp(SVELTE_LAYOUT_MARKER_OPEN)
+    + '\\n<ImpeccableLiveRoot\\s*/>\\n'
+    + escapeRegExp(SVELTE_LAYOUT_MARKER_CLOSE)
+    + '\\n?',
+    '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, '');
+  return out.replace(/\n{3,}/g, '\n\n');
+}
+
+export function ensureSvelteLiveRootComponent(cwd, port) {
+  const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  return file;
+}
+
+export function buildSvelteLiveRootComponent(port) {
+  return `<script>
+  import { onMount } from 'svelte';
+
+  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const HOST_ID = 'impeccable-live-root';
+
+  onMount(() => {
+    let host = document.querySelector('impeccable-live-root#' + HOST_ID) || document.getElementById(HOST_ID);
+    if (!host) {
+      host = document.createElement('impeccable-live-root');
+      host.id = HOST_ID;
+      document.body.appendChild(host);
+    }
+
+    host.dataset.impeccableLiveAdapter = 'sveltekit';
+    host.style.setProperty('all', 'initial', 'important');
+    host.style.setProperty('display', 'block', 'important');
+    host.style.setProperty('position', 'fixed', 'important');
+    host.style.setProperty('top', '0', 'important');
+    host.style.setProperty('left', '0', 'important');
+    host.style.setProperty('width', '0', 'important');
+    host.style.setProperty('height', '0', 'important');
+    host.style.setProperty('overflow', 'visible', 'important');
+    host.style.setProperty('z-index', '2147483000', 'important');
+    host.style.setProperty('pointer-events', 'none', 'important');
+
+    const root = host.shadowRoot || host.attachShadow({ mode: 'open' });
+    if (!root.querySelector('style[data-impeccable-live-reset]')) {
+      const reset = document.createElement('style');
+      reset.dataset.impeccableLiveReset = 'true';
+      reset.textContent = ':host, :host *, * { box-sizing: border-box; }';
+      root.appendChild(reset);
+    }
+
+    window.__IMPECCABLE_LIVE_ADAPTER__ = 'sveltekit';
+    window.__IMPECCABLE_LIVE_UI_ROOT__ = root;
+    window.__IMPECCABLE_LIVE_CHROME_MOUNT__ = {
+      adapter: 'sveltekit',
+      version: 1,
+      host,
+      root,
+    };
+
+    const script = document.createElement('script');
+    script.src = LIVE_URL;
+    script.async = true;
+    script.dataset.impeccableLiveScript = 'true';
+    document.head.appendChild(script);
+
+    return () => {
+      script.remove();
+      if (window.__IMPECCABLE_LIVE_UI_ROOT__ === root) delete window.__IMPECCABLE_LIVE_UI_ROOT__;
+      if (window.__IMPECCABLE_LIVE_CHROME_MOUNT__?.root === root) delete window.__IMPECCABLE_LIVE_CHROME_MOUNT__;
+      if (window.__IMPECCABLE_LIVE_ADAPTER__ === 'sveltekit') delete window.__IMPECCABLE_LIVE_ADAPTER__;
+    };
+  });
+</script>
+`;
+}
+
+function findSvelteKitAppHtml(cwd, config) {
+  const files = Array.isArray(config?.files) ? config.files : ['src/app.html'];
+  for (const rel of files) {
+    if (rel.includes('*')) continue;
+    const normalized = rel.split(path.sep).join('/');
+    if (!normalized.endsWith('app.html')) continue;
+    const abs = path.join(cwd, normalized);
+    if (fs.existsSync(abs)) return normalized;
+  }
+  const fallback = 'src/app.html';
+  return fs.existsSync(path.join(cwd, fallback)) ? fallback : null;
+}
+
+function findSvelteKitLayout(cwd) {
+  const candidates = [
+    'src/routes/+layout.svelte',
+    'src/routes/(app)/+layout.svelte',
+  ];
+  for (const rel of candidates) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return 'src/routes/+layout.svelte';
+}
+
+function defaultSvelteLayout() {
+  return `<script>\n  let { children } = $props();\n</script>\n\n{@render children?.()}\n`;
+}
+
+function packageHasSvelteKit(cwd) {
+  const file = path.join(cwd, 'package.json');
+  if (!fs.existsSync(file)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const deps = {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+      ...(pkg.peerDependencies || {}),
+    };
+    return Boolean(deps['@sveltejs/kit'] || deps['@sveltejs/vite-plugin-svelte'] || deps.svelte);
+  } catch {
+    return false;
+  }
+}
+
+function fileIncludes(file, text) {
+  try {
+    return fs.readFileSync(file, 'utf-8').includes(text);
+  } catch {
+    return false;
+  }
+}
+
+function pruneEmptyDir(dir, stopDir) {
+  let current = dir;
+  while (current.startsWith(stopDir) && current !== stopDir) {
+    try {
+      if (fs.readdirSync(current).length > 0) return;
+      fs.rmdirSync(current);
+      current = path.dirname(current);
+    } catch {
+      return;
+    }
+  }
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -0,0 +1,180 @@
+/**
+ * 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

@@ -0,0 +1,36 @@
+/**
+ * Canonical design-command vocabulary for Live Mode: each command's value, human
+ * label, and SVG icon. Icons stack above the chip label; strokes use currentColor
+ * so the icon recolors when its chip is selected.
+ *
+ * Single source of truth, consumed by:
+ *   - skill/scripts/live/event-validation.mjs — re-exports VISUAL_ACTIONS.
+ *   - skill/scripts/live-browser.js — the real picker. It is served raw and
+ *     injected as an IIFE, so it cannot import this at runtime; live-server.mjs
+ *     serializes LIVE_COMMANDS into window.__IMPECCABLE_VOCAB__ alongside the
+ *     token/port, and live-browser.js builds its ICONS + ACTIONS from that.
+ *   - site/components/LiveDemoPalette.astro — the marketing demo palette (imported
+ *     at build time).
+ *
+ * Add, rename, or reorder a verb here and all three follow.
+ */
+
+const ICON_ATTRS = 'width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" style="display:block"';
+
+export const LIVE_COMMANDS = [
+  { value: 'impeccable', label: 'Freeform',  icon: `<svg ${ICON_ATTRS}><path d="M4 20l4-1L18 9l-3-3L5 16z"/><path d="M14 7l3 3"/></svg>` },
+  { value: 'bolder',     label: 'Bolder',    icon: `<svg ${ICON_ATTRS}><rect x="6" y="12" width="4" height="7" rx="0.5"/><rect x="14" y="5" width="4" height="14" rx="0.5"/></svg>` },
+  { value: 'quieter',    label: 'Quieter',   icon: `<svg ${ICON_ATTRS}><rect x="6" y="5" width="4" height="14" rx="0.5"/><rect x="14" y="12" width="4" height="7" rx="0.5"/></svg>` },
+  { value: 'distill',    label: 'Distill',   icon: `<svg ${ICON_ATTRS}><path d="M4 5h16l-6 8v7l-4-2v-5z"/></svg>` },
+  { value: 'polish',     label: 'Polish',    icon: `<svg ${ICON_ATTRS}><path d="M15 3l1 3 3 1-3 1-1 3-1-3-3-1 3-1z"/><path d="M7 13l0.6 1.8 1.8 0.6-1.8 0.6-0.6 1.8-0.6-1.8-1.8-0.6 1.8-0.6z"/></svg>` },
+  { value: 'typeset',    label: 'Typeset',   icon: `<svg ${ICON_ATTRS}><path d="M5 6h14" stroke-width="2.6"/><path d="M5 12h9" stroke-width="1.9"/><path d="M5 18h5" stroke-width="1.3"/></svg>` },
+  { value: 'colorize',   label: 'Colorize',  icon: `<svg ${ICON_ATTRS}><circle cx="9" cy="10" r="5"/><circle cx="15" cy="10" r="5"/><circle cx="12" cy="15" r="5"/></svg>` },
+  { value: 'layout',     label: 'Layout',    icon: `<svg ${ICON_ATTRS}><rect x="3" y="4" width="8" height="16" rx="0.5"/><rect x="13" y="4" width="8" height="7" rx="0.5"/><rect x="13" y="13" width="8" height="7" rx="0.5"/></svg>` },
+  { value: 'adapt',      label: 'Adapt',     icon: `<svg ${ICON_ATTRS}><rect x="2.5" y="5" width="12" height="11" rx="1"/><line x1="2.5" y1="19" x2="14.5" y2="19"/><rect x="16.5" y="8" width="5" height="11" rx="1"/></svg>` },
+  { value: 'animate',    label: 'Animate',   icon: `<svg ${ICON_ATTRS}><path d="M3 18c4-4 6-10 10-10"/><path d="M13 8c3 0 5 5 8 10"/><circle cx="13" cy="8" r="1.6" fill="currentColor" stroke="none"/></svg>` },
+  { value: 'delight',    label: 'Delight',   icon: `<svg ${ICON_ATTRS}><path d="M12 3l2 6 6 2-6 2-2 6-2-6-6-2 6-2z"/></svg>` },
+  { value: 'overdrive',  label: 'Overdrive', icon: `<svg ${ICON_ATTRS}><path d="M13 3L5 13h5l-1 8 9-12h-6z"/></svg>` },
+];
+
+// Action values accepted by the live event protocol, in palette order.
+export const VISUAL_ACTIONS = LIVE_COMMANDS.map((c) => c.value);

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

@@ -6,7 +6,7 @@
  *   node <scripts_path>/pin.mjs pin <command>
  *   node <scripts_path>/pin.mjs unpin <command>
  *
- * `pin audit` creates a lightweight /audit skill that redirects to /impeccable audit.
+ * `pin audit` creates a lightweight audit skill that redirects to Impeccable's audit workflow.
  * `unpin audit` removes that shortcut.
  *
  * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
@@ -14,7 +14,7 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { basename, join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -25,6 +25,8 @@ const HARNESS_DIRS = [
   '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
 ];
 
+const CODEX_HARNESSES = new Set(['.codex', '.agents']);
+
 // Valid sub-command names
 const VALID_COMMANDS = [
   'craft', 'init', 'extract', 'document', 'shape',
@@ -87,8 +89,12 @@ function loadCommandMetadata() {
 /**
  * Generate a pinned skill's SKILL.md content.
  */
-function generatePinnedSkill(command, metadata) {
-  const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
+function commandPrefixForSkillsDir(skillsDir) {
+  return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
+}
+
+function generatePinnedSkill(command, metadata, commandPrefix) {
+  const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}impeccable ${command}.`;
   const hint = metadata[command]?.argumentHint || '[target]';
 
   return `---
@@ -100,9 +106,9 @@ user-invocable: true
 
 ${PIN_MARKER}
 
-This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
+This is a pinned shortcut for \`${commandPrefix}impeccable ${command}\`.
 
-Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
+Invoke ${commandPrefix}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
 `;
 }
 
@@ -118,10 +124,11 @@ function pin(command, projectRoot) {
     return false;
   }
 
-  const content = generatePinnedSkill(command, metadata);
   let created = 0;
 
   for (const skillsDir of harnessDirs) {
+    const commandPrefix = commandPrefixForSkillsDir(skillsDir);
+    const content = generatePinnedSkill(command, metadata, commandPrefix);
     // Check if skill already exists (and isn't a pin)
     const skillDir = join(skillsDir, command);
     if (existsSync(skillDir)) {
@@ -143,7 +150,7 @@ function pin(command, projectRoot) {
 
   if (created > 0) {
     console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
-    console.log(`You can now use /${command} directly.`);
+    console.log('Use the pinned command directly in each harness.');
   }
 
   return created > 0;
@@ -177,7 +184,7 @@ function unpin(command, projectRoot) {
 
   if (removed > 0) {
     console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
-    console.log(`Use /impeccable ${command} to access it.`);
+    console.log(`Use Impeccable's '${command}' workflow directly to access it.`);
   } else {
     console.log(`No pinned '${command}' shortcut found.`);
   }

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

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

.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "description": "Impeccable design detector: runs after Edit/Write/MultiEdit on UI files and surfaces findings as system reminders.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
+            "timeout": 5,
+            "statusMessage": "Checking UI changes"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/impeccable/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 3.5.0
+version: 3.9.1
 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]"
 license: Apache 2.0
 allowed-tools:
   - Bash(npx impeccable *)
+  - Bash(node .claude/skills/impeccable/scripts/*)
 ---
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
@@ -15,11 +16,12 @@ Designs and iterates production-grade frontend interfaces. Real working code, co
 
 You MUST do these steps before proceeding:
 
-1. Run `node .claude/skills/impeccable/scripts/context.mjs` once per session. If you've already seen its output in this conversation, do not re-run it. The script either prints the project's PRODUCT.md (and DESIGN.md when present) as a markdown block, or tells you it's missing. Follow whatever it prints. **If it reports `NO_PRODUCT_MD`, stop and follow `reference/init.md` before doing anything else.** If the output ends with an `UPDATE_AVAILABLE` directive, follow it (ask the user once about updating, then continue). It never blocks the current task.
-2. If the user invoked a sub-command (`craft`, `shape`, `audit`, `polish`, ...), you MUST read `reference/<command>.md` next. Non-optional. The reference defines the command's flow; without it you will skip steps the user expects.
+1. Run `node .claude/skills/impeccable/scripts/context.mjs` once per session; if the runtime shows this skill's loaded base directory, run `node <skill-base-dir>/scripts/context.mjs` instead. Keep cwd/workdir at the user's project, not the skill directory. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and append `--target <path>` to the same command. If you've already seen its output in this conversation, do not re-run it. The script either prints the project's PRODUCT.md (and DESIGN.md when present) as a markdown block, or tells you it's missing. Follow whatever it prints. **If it reports `NO_PRODUCT_MD`:** divert into `reference/init.md` first when the user invoked `init`, `teach`, `craft`, or `shape`, or when their wording clearly maps to one of those from-scratch build flows (for example: "build/create/make a landing page", "design a new app", or "shape a feature"). Captured product context is the point of those flows. For any other command, a scoped evaluate / refine / enhance / fix / iterate request against existing code, do **not** divert into init. The existing code is the context: proceed with the requested command, infer the register from the surface in focus (step 4), and offer `/impeccable init` once as a suggestion the user can take later. A missing PRODUCT.md must never block a scoped request. If the output ends with an `UPDATE_AVAILABLE` directive, follow it (ask the user once about updating, then continue). It never blocks the current task.
+2. If the user invoked a sub-command (`craft`, `shape`, `audit`, `polish`, ...), you MUST read the command's reference next: **`reference/<command>.md`, or the native variant from the Commands table** (e.g. `reference/audit.native.md`) **when the project platform is native** (`ios` / `android` / `adaptive`, per the `context.mjs` directive). One file, not both. Non-optional. The reference defines the command's flow; without it you will skip steps the user expects.
 3. Familiarize yourself with any existing design system, conventions, and components in the code. Read at least one project file (CSS / tokens / theme / a representative component or page). **Required even when you've loaded a sub-command reference in step 2.** Don't reinvent the wheel; use what's there when it works, branch out when the UX wins.
 4. Read the matching register reference. **This is non-optional; skipping it produces generic output.** If the project is marketing, a landing page, a campaign, long-form content, or a portfolio (design IS the product), read `reference/brand.md`. If it is app UI, admin, a dashboard, or a tool (design SERVES the product), read `reference/product.md`. Pick by first match: (1) task cue ("landing page" vs "dashboard"); (2) surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md.
-5. **If the project is brand-new (no existing CSS tokens / theme / committed brand colors found in step 3)**, run `node .claude/skills/impeccable/scripts/palette.mjs` to receive a brand seed color and composition guidance. This is the anchor for your primary brand color. Compose the rest of the palette (bg, surface, ink, accent, muted) around it per the script's instructions. Use OKLCH throughout. **Skip this step only if step 3 found committed brand colors in existing tokens; in that case identity-preservation wins.**
+5. **If PRODUCT.md's `## Platform` is `ios` or `android`**, also read `reference/<platform>.md` (HIG / Material 3 conventions). `adaptive` (cross-platform, ships both) reads both files. `web`, absent, or unrecognized: nothing extra to read. `context.mjs` prints the directive when one applies.
+6. **If the project is brand-new (no existing CSS tokens / theme / committed brand colors found in step 3)**, run `node .claude/skills/impeccable/scripts/palette.mjs` to receive a brand seed color and composition guidance. This is the anchor for your primary brand color. Compose the rest of the palette (bg, surface, ink, accent, muted) around it per the script's instructions. Use OKLCH throughout. **Skip this step only if step 3 found committed brand colors in existing tokens; in that case identity-preservation wins.**
 
 ## Design guidance
 
@@ -35,10 +37,7 @@ Produce ready-to-ship, production-grade code, not prototypes or starting points.
 #### Typography
 
 - Cap body line length at 65–75ch.
-- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
-- Cap font-family count at 3 (display + body + optional mono). More than 3 reads as indecision, not richness. One well-tuned family with weight contrast usually beats three competing typefaces.
 - Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights.
-- No all-caps body copy. Reserve uppercase for short labels (≤4 words), section eyebrows (used sparingly per the Absolute bans), and badges. Sentences in ALL CAPS are unreadable at body sizes.
 - Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing.
 - Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed".
 - Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans.
@@ -65,15 +64,6 @@ Produce ready-to-ship, production-grade code, not prototypes or starting points.
 
 - Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context.
 
-### Copy
-
-- Every word earns its place. No restated headings, no intros that repeat the title.
-- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
-- **No aphoristic-cadence body copy as a default voice.** Don't fall into the rhythm of "serious statement, then punchy short negation" as the page's recurring voice. If three or more section copy blocks on the page land on a short rebuttal-shaped sentence, rewrite. Specific, not aphoristic.
-- **No marketing buzzwords.** The streamline / empower / supercharge / leverage / unleash / transform / seamless / world-class / enterprise-grade / next-generation / cutting-edge / game-changer / mission-critical family of phrases. Pick a specific noun and a verb that describes what the product literally does.
-- Button labels: verb + object. "Save changes" beats "OK"; "Delete project" beats "Yes". The label should say what will happen.
-- Link text needs standalone meaning. "View pricing plans" beats "Click here"; screen readers announce links out of context.
-
 ### New projects only (when no prior work exists)
 
 #### Color & Theme
@@ -120,7 +110,7 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
 | `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
 | `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
-| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) · native: [reference/audit.native.md](reference/audit.native.md) |
 | `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
 | `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
 | `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
@@ -134,34 +124,34 @@ If someone could look at this interface and say "AI made that" without doubt, it
 | `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
 | `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
 | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
-| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) · native: [reference/adapt.native.md](reference/adapt.native.md) |
 | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
 | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
 
-Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
+Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
 
 ### Routing rules
 
-1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` you are already in init (setup), so finish that and skip this. Otherwise run `node .claude/skills/impeccable/scripts/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
+1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` the project has no captured context yet, so lead the menu with `/impeccable init` as the top recommendation (one line on why) and still show the rest below; don't silently jump into init. Otherwise run `node .claude/skills/impeccable/scripts/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
 
    Reason over the signals; there is no score to obey:
    - `setup.hasDesign` false while `setup.hasCode` true → `document` (capture the visual system).
    - `critique.latest` is `null` → the project has never been critiqued; for a set-up project with a real surface, offering `/impeccable critique <surface>` is a strong default.
    - `critique.latest` with a low `score` or non-zero `p0` / `p1` → `polish` (it reads that snapshot as its backlog), or re-run `critique` if the snapshot looks stale.
    - `git.changedFiles` pointing at one surface → scope `audit` or `polish` to those files specifically, naming them.
-   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`.
+   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`. **`live` and the bundled `detect.mjs` are web-only.** If `setup.platform` is `ios`, `android`, or `adaptive`, don't lead with either; the browser overlay and the HTML rule engine don't apply to native app code.
    - Otherwise group by intent exactly as init's "Recommend starting points" step does (build new / improve what's there / iterate visually), tailored to `setup.register`.
 
-   **If `scan.targets` is non-empty, run `node .claude/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
+   **If `scan.targets` is non-empty and `setup.platform` is not `ios`/`android`/`adaptive`, run `node .claude/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx; it reads HTML/CSS, so skip it for native projects). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
 
    Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
-2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
-3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
+2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file (on native platforms, the table's native variant; Setup step 2's one-file rule) and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference (same native-variant rule) and proceed as if invoked. If two commands could fit, ask once which.
 4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
 
 Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `/impeccable`.
 
-If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
+If the first word is `craft` or `shape`, or routing rule 3 clearly maps the user's intent to either command, setup still runs first, but the matching reference ([reference/craft.md](reference/craft.md) or [reference/shape.md](reference/shape.md)) owns the rest of the flow. Both are from-scratch build flows: if setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
 
 `teach` is a deprecated alias for `init`: if the user types it, load [reference/init.md](reference/init.md) and proceed as if they ran `init`.
 
@@ -173,4 +163,8 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r
 node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
 ```
 
-Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+
+## Hooks
+
+`/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `/impeccable hooks` with any argument.

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

@@ -2,6 +2,7 @@
 
 Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
+**Web only** (mobile web included). Native platforms (`ios` / `android` / `adaptive`) route to [adapt.native.md](adapt.native.md) instead; if the project is native, switch to it now.
 
 ---
 

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

@@ -0,0 +1,58 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+Adapt an existing **native** design (`ios` / `android` / `adaptive`) to a different context: another device class, orientation, platform, or origin. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context, inside the platform conventions of [ios.md](ios.md) / [android.md](android.md); read the target platform's reference before planning if Setup hasn't already.
+
+## Assess Adaptation Challenge
+
+1. **Source context**: what was it designed for, and what assumptions did it make? (Phone-only? Portrait-only? One platform's idioms? A website?)
+2. **Target context**: which device class (phone, tablet, foldable), orientation, platform, and usage posture (one-handed on the go vs two-handed at rest)?
+3. **What breaks**: navigation that doesn't fit the target, layouts that stretch instead of restructure, gestures or controls that don't exist there?
+
+## Adaptation Strategies
+
+### Phone → Tablet (iPad / large screens)
+
+- **Restructure, don't stretch.** A scaled-up phone UI on a tablet is the failure mode. Use size classes (iOS) / window size classes (Android) to switch structure.
+- **Navigation changes shape**: tab bar stays or becomes a sidebar on iPad; Android navigation bar becomes a rail or drawer on expanded width.
+- **Use the width**: split view / master-detail (list + detail side by side), multi-column grids, popovers where phones used sheets.
+- **Multitasking is a size, not an edge case**: iPad Split View and Android multi-window can hand you a phone-width window on a tablet; size-class-driven layout handles both for free.
+
+### Orientation & foldables
+
+- Landscape restructures (side-by-side panes, repositioned controls); never clip or letterbox. Lock orientation only when the task truly demands it.
+- Foldables (Android): react to posture and hinge via window size classes; test folded, unfolded, and tabletop.
+
+### Platform → platform (iOS ↔ Android)
+
+Translate idioms; never transplant them:
+
+| iOS | Android |
+|---|---|
+| Tab bar | Navigation bar / rail / drawer |
+| Edge-swipe back, back chevron | Predictive Back gesture / button |
+| Switch, segmented control, system pickers | Material switch, chips, Material pickers |
+| Action sheet | Bottom sheet / Material dialog |
+| SF Symbols, SF Pro, Dynamic Type | Material Symbols, Roboto, sp scaling |
+| Semantic system colors, materials | Material color roles, tonal elevation |
+| System push/sheet transitions | Container transform, shared-axis, fade-through |
+
+Rebuild navigation and controls in the target's vocabulary; carry over the brand's expressive layer (palette intent, type accent, motion personality) through the target's theming system.
+
+### Web → native (porting a website or web app)
+
+Reconform, don't reflow. Replace web navigation with the platform's model, HTML-shaped controls with platform controls, hover affordances with touch-first ones, and px-based type with Dynamic Type / sp. Then treat the result to the full platform reference; the slop test there is the acceptance bar.
+
+## Implement & Verify
+
+- Drive structure from **size classes / window size classes**, never from device-model checks.
+- Respect safe areas and window insets in every new configuration (notch, hinge, status bar, keyboard).
+- Test on simulators for breadth, then real hardware for truth: at least one phone and one tablet per shipped platform, both orientations, split-screen where supported.
+
+When the adaptation feels native to each context, hand off to `/impeccable polish` for the final pass.
+
+**NEVER**:
+- Ship a stretched phone layout on a tablet
+- Port one platform's controls or navigation onto the other
+- Hide core functionality on smaller devices (if it matters, make it work)
+- Lock orientation to dodge a layout bug
+- Trust simulators alone (posture, gestures, and performance need hardware)

.claude/skills/impeccable/reference/android.md

@@ -0,0 +1,40 @@
+# Android platform
+
+For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.
+
+On native, register narrows. Material Design 3 governs structure, navigation, and interaction whatever the register; brand expresses through Material's theming (color roles, type scale, shape, motion). A Material-everywhere cross-platform app that also ships to iPhone still owes iOS its OS guarantees on that hardware: safe-area insets, Reduce Motion, edge-swipe back.
+
+## The Android slop test
+
+Would a fluent Android user trust this app, or trip on off-spec components? The most common tell is an iOS app wearing Android's skin: a bottom-only navigation copied from iPhone, a back arrow that ignores the system Back gesture, Cupertino-shaped switches and dialogs. Material 3 is the rulebook; follow its components and theme the brand through it.
+
+## Layout & structure
+
+- **Material navigation, matched to size.** Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet.
+- **System Back always works.** Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture.
+- **Edge-to-edge with window insets.** Apply the status bar, navigation bar, display cutout, and IME insets so content never hides behind system bars or the keyboard.
+- **Top app bar for screen context**; pair with a FAB when the screen has a single primary action.
+
+## Touch targets
+
+- **48×48 dp minimum** for every touch target, with at least 8 dp between them.
+
+## Typography
+
+- **Material type scale.** Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen.
+- **Roboto is the system face**; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent.
+- **sp units, never fixed px**, so type follows the system font-size setting.
+
+## Color & theming
+
+- **Material color roles** (primary, on-primary, surface, surface-variant, secondary-container, outline, error). Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.
+- **Dynamic Color (Material You)** where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback.
+- **Dark theme is a first-class scheme.** Design and test it; never a quick invert.
+- **Tonal elevation.** Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows.
+
+## Components & motion
+
+- **Material components.** Buttons (filled / tonal / outlined / text), FAB, switches, chips, snackbars, bottom sheets, Material dialogs, navigation bar/rail/drawer. Never port iOS controls or invent equivalents.
+- **One FAB, one primary action.** Never stack FABs or spend one on a secondary task.
+- **Snackbars for transient feedback** (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt.
+- **Material motion patterns.** Container transform, shared-axis, fade-through, with standard easing and durations; honor the system Remove animations setting with a crossfade or instant cut.

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

@@ -10,6 +10,8 @@ Brand: motion is part of the voice; one well-rehearsed entrance beats scattered
 
 Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
+Native (`ios` / `android` / `adaptive`): implementation follows the Motion section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): system transitions and OS Reduce Motion, never the web tooling below.
+
 ---
 
 ## Assess Animation Opportunities

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

@@ -2,6 +2,8 @@ Run systematic **technical** quality checks and generate a comprehensive report.
 
 This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
 
+**Web only.** Native platforms (`ios` / `android` / `adaptive`) route to [audit.native.md](audit.native.md) instead; if the project is native, switch to it now.
+
 ## Diagnostic Scan
 
 Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.

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

@@ -0,0 +1,139 @@
+Run systematic **technical** quality checks on a native app (`ios` / `android` / `adaptive`) and generate a comprehensive report. Don't fix issues; document them for other commands to address.
+
+This is a code-level audit, not a design critique. Audit from source (SwiftUI / UIKit / Compose / React Native / Flutter); no browser tooling or `detect.mjs` applies. Score against the platform reference(s): [ios.md](ios.md) / [android.md](android.md), both for `adaptive`. Read them before scoring if Setup hasn't already. The report skeleton mirrors [audit.md](audit.md); keep the two in sync when changing it.
+
+## Diagnostic Scan
+
+Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
+
+### 1. Accessibility (VoiceOver / TalkBack)
+
+**Check for**:
+- **Missing labels**: interactive elements without accessibility labels, traits/roles, or state announcements
+- **Reading and focus order**: illogical traversal, unreachable controls, focus lost on navigation
+- **Text scaling**: fixed point sizes defeating Dynamic Type (iOS) or px instead of sp (Android); layouts that clip or overlap at large sizes
+- **Touch targets**: below 44 pt (iOS) / 48 dp (Android), or crammed without spacing
+- **Reduce Motion ignored**: parallax and large slides with no crossfade alternative
+- **Contrast**: text failing contrast in either appearance, light or dark
+
+**Score 0-4**: 0=Screen reader unusable, 1=Major gaps (unlabeled controls, no scaling), 2=Partial (labels exist, order or scaling breaks), 3=Good (minor gaps), 4=Excellent (labeled, ordered, scales cleanly, Reduce Motion honored)
+
+### 2. Performance
+
+**Check for**:
+- **Slow startup**: heavy work on launch before first frame
+- **Unvirtualized lists**: long content without FlatList / LazyColumn / List recycling
+- **Main-thread jank**: synchronous work in scroll or gesture paths, dropped frames on 60/120 Hz
+- **Wasted rendering**: unnecessary re-renders (React Native) or recompositions (Compose); missing memoization/keys
+- **Image handling**: full-size images decoded for thumbnails, no caching
+- **App weight**: bloated JS bundle or binary, unused dependencies
+
+**Score 0-4**: 0=Janky everywhere, 1=Major problems (unvirtualized lists, slow launch), 2=Partial, 3=Good (minor improvements possible), 4=Excellent (fast launch, smooth scroll, lean)
+
+### 3. Appearance & Theming
+
+**Check for**:
+- **Hard-coded colors**: raw hex instead of semantic system colors (iOS) / Material color roles (Android) / design tokens
+- **Broken dark appearance**: missing dark variants, poor contrast in dark, quick inverts
+- **Dynamic Color** (Android 12+): no static fallback scheme, or ignored where it fits
+- **Off-platform materials**: hand-rolled blur/glassmorphism instead of system materials or tonal elevation
+
+**Score 0-4**: 0=Hard-coded everything, 1=Minimal tokens, 2=Partial (tokens exist, inconsistently used), 3=Good (minor hard-coded values), 4=Excellent (semantic throughout, both appearances first-class)
+
+### 4. Platform Conformance (CRITICAL)
+
+Score against the loaded platform reference(s), including their slop tests. **Check for**:
+- **Broken system gestures**: edge-swipe back disabled (iOS), predictive Back hijacked (Android)
+- **Inset violations**: content under the notch, Dynamic Island, home indicator, status bar, or keyboard
+- **Off-platform navigation**: custom global nav, overloaded tab bars, iOS patterns on Android or vice versa
+- **Web-shaped controls**: HTML-style buttons, custom toggles, hover-dependent affordances
+- **Icon drift**: mixed icon sets instead of SF Symbols / Material Symbols
+- **AI tells**: the shared absolute bans still apply (AI palette, gradient text, hero metrics)
+
+**Score 0-4**: 0=Web port (nothing native), 1=Heavy violations (3-4 kinds), 2=Some (1-2 noticeable), 3=Mostly conformant (subtle issues), 4=Fully native (a fluent user trusts every screen)
+
+### 5. Adaptivity
+
+**Check for**:
+- **Stretched phone layouts**: tablet/iPad rendering a scaled-up phone UI instead of using size classes / window size classes
+- **Orientation breakage**: landscape clipping, ignored, or locked without reason
+- **Keyboard/IME handling**: inputs hidden behind the keyboard, no inset adjustment
+- **Multitasking**: iPad Split View / Android multi-window breaking layout
+- **Foldables**: hinge-unaware layouts on posture change (Android)
+
+**Score 0-4**: 0=One screen size only, 1=Major breakage (landscape or tablet broken), 2=Partial, 3=Good (minor edge cases), 4=Excellent (adapts across sizes, orientations, and windowing)
+
+## Generate Report
+
+### Audit Health Score
+
+| # | Dimension | Score | Key Finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | ? | [most critical issue or "--"] |
+| 2 | Performance | ? | |
+| 3 | Appearance & Theming | ? | |
+| 4 | Platform Conformance | ? | |
+| 5 | Adaptivity | ? | |
+| **Total** | | **??/20** | **[Rating band]** |
+
+**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
+
+### Platform Conformance Verdict
+**Start here.** Pass/fail: does this read as a native app or a ported website? List specific violations. Be brutally honest.
+
+### Executive Summary
+- Audit Health Score: **??/20** ([rating band])
+- Total issues found (count by severity: P0/P1/P2/P3)
+- Top 3-5 critical issues
+- Recommended next steps
+
+### Detailed Findings by Severity
+
+Tag every issue with **P0-P3 severity**:
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or platform-guideline violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
+
+For each issue, document:
+- **[P?] Issue name**
+- **Location**: Screen, file, line
+- **Category**: Accessibility / Performance / Theming / Conformance / Adaptivity
+- **Impact**: How it affects users
+- **Guideline**: The HIG / Material rule it violates (if applicable)
+- **Recommendation**: How to fix it
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+
+### Patterns & Systemic Issues
+
+Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
+- "Hard-coded colors appear in 15+ screens, should use semantic colors"
+- "Touch targets consistently below 44 pt throughout the tab bar and list rows"
+
+### Positive Findings
+
+Note what's working well: good practices to maintain and replicate.
+
+## Recommended Actions
+
+List recommended commands in priority order (P0 first, then P1, then P2):
+
+1. **[P?] `/command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `/command-name`**: Brief description (specific context)
+
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `/impeccable audit` after fixes to see your score improve.
+
+**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
+
+**NEVER**:
+- Report issues without explaining impact (why does this matter?)
+- Provide generic recommendations (be specific and actionable)
+- Skip positive findings (celebrate what works)
+- Forget to prioritize (everything can't be P0)
+- Report false positives without verification

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

@@ -1,12 +1,12 @@
-When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type.
+When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact by making the existing design language more decisive, specific, and committed.
 
 ---
 
 ## Register
 
-Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV.
+Brand: "bolder" means distinctive. Express a stronger point of view through hierarchy, pacing, proportion, copy, evidence, and one committed visual idea.
 
-Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
+Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, sharper information density, and more decisive prioritization. The amplification is in clarity, not drama.
 
 ---
 
@@ -15,98 +15,105 @@ Product: "bolder" rarely means theatrics; those undermine trust. It means strong
 Analyze what makes the design feel too safe or boring:
 
 1. **Identify weakness sources**:
-   - **Generic choices**: System fonts, basic colors, standard layouts
-   - **Timid scale**: Everything is medium-sized with no drama
-   - **Low contrast**: Everything has similar visual weight
-   - **Static**: No motion, no energy, no life
-   - **Predictable**: Standard patterns with no surprises
-   - **Flat hierarchy**: Nothing stands out or commands attention
+   - **Generic choices**: The page could belong to any product in the category.
+   - **Timid scale**: Everything is medium-sized with no clear lead.
+   - **Low contrast**: Important and supporting elements have similar visual weight.
+   - **Static**: The surface has no meaningful moment of emphasis.
+   - **Predictable**: The composition follows a default pattern without a point of view.
+   - **Flat hierarchy**: Nothing stands out or commands attention.
 
 2. **Understand the context**:
-   - What's the brand personality? (How far can we push?)
-   - What's the purpose? (Marketing can be bolder than financial dashboards)
-   - Who's the audience? (What will resonate?)
-   - What are the constraints? (Brand guidelines, accessibility, performance)
+   - What is the brand personality?
+   - What is the purpose of this surface?
+   - Who is the audience?
+   - What design system, tokens, components, and visual conventions already exist?
 
 If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
 
-**CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
+**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random noise.
 
 **WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
 
+## Design-System Lock
+
+If the project has `DESIGN.md`, tokens, theme variables, or established component styles, treat that system as the boundary. Make the existing language stronger before adding new language.
+
+Do not invent new colors, gradients, radii, shadows, fonts, decorative backgrounds, or effects just because the request says "bolder." A bolder pass should usually change emphasis, proportion, rhythm, density, contrast, copy, artifact specificity, and layout relationships while staying inside the documented system.
+
+If the existing system is genuinely too limited to express the bolder direction, stop and ask the user before expanding it. Name the exact additions, the role each would play, and why the current system cannot do the job. If the user approves expansion, update the design system or tokens alongside the implementation.
+
 ## Plan Amplification
 
 Create a strategy to increase impact while maintaining coherence:
 
-- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing)
-- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
-- **Risk budget**: How experimental can we be? Push boundaries within constraints.
-- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast)
+- **Focal point**: Pick one thing the viewer should remember, then make the rest support it.
+- **System levers**: Identify which existing tokens, components, layout patterns, and copy structures can carry more weight.
+- **Risk budget**: Decide how far the surface can push while still feeling like the same product or brand.
+- **Hierarchy amplification**: Increase contrast between primary, secondary, and tertiary content instead of making every element louder.
 
 **IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
 
 ## Amplify the Design
 
-Systematically increase impact across these dimensions:
+Systematically increase impact through intention, not a menu of effects:
 
 ### Typography Amplification
-- **Replace generic fonts**: Swap system fonts for distinctive choices (see the parent skill's typography guidelines and the [Reference Material section of typeset.md](typeset.md#reference-material) for inspiration)
-- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x)
-- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400
-- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default)
+- Strengthen the existing type hierarchy before changing typefaces.
+- Make important text meaningfully more dominant, and make supporting text quieter.
+- Use weight, measure, spacing, and line breaks to sharpen the point of view.
+- Add or replace fonts only after user-approved design-system expansion.
 
-### Color Intensification
-- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
-- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop
-- **Dominant color strategy**: Let one bold color own 60% of the design
-- **Sharp accents**: High-contrast accent colors that pop
-- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
-- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue)
+### Color Amplification
+- Use the existing palette more decisively before adding colors.
+- Shift the proportion, placement, and contrast of documented colors to clarify meaning.
+- Treat any new color, gradient, or tint ramp as a design-system expansion that requires user approval.
+- Keep color tied to hierarchy, state, or brand meaning; do not use it as surface decoration.
 
-### Spatial Drama
-- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings
-- **Break the grid**: Let hero elements escape containers and cross boundaries
-- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry
-- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px)
-- **Overlap**: Layer elements intentionally for depth
+### Spatial Amplification
+- Change proportion, density, alignment, and sequencing so the composition has a stronger point of view.
+- Create clearer contrast between dense evidence and open breathing room.
+- Let layout express priority and narrative order before adding ornament.
+- Preserve responsive behavior and avoid text overflow at every breakpoint.
 
-### Visual Effects
-- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
-- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
-- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop)
-- **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
-- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
+### Surface Amplification
+- Use existing surface, border, radius, and shadow rules more deliberately.
+- Remove timid half-measures: either give an element a clear role or simplify it.
+- Add texture, depth, illustration, or decorative treatments only when already established by the system or explicitly approved.
+- Make real product artifacts, imagery, data, or copy carry attention before reaching for effects.
 
 ### Motion & Animation
-- **Hero moment**: One signature entrance, once. Not on every visit and not on every section.
-- **Micro-interactions**: Satisfying hover effects, click feedback, state changes.
-- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect).
-- **Bolder ≠ scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
+- Design one meaningful moment of emphasis when motion genuinely supports the point.
+- Make interaction feedback feel more decisive without becoming distracting.
+- Keep transitions smooth and intentional.
+- **Bolder != scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
 
 ### Composition Boldness
-- **Hero moments**: Create clear focal points with dramatic treatment
-- **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements
-- **Full-bleed elements**: Use full viewport width/height for impact
-- **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits
+- Make the dominant idea unmistakable.
+- Use layout tension, sequencing, contrast, and restraint to create a stronger read.
+- Let the page's structure communicate priority before adding decorative layers.
+- If every element is louder, the composition is not bolder; it is flatter.
 
 **NEVER**:
-- Add effects randomly without purpose (chaos ≠ bold)
-- Sacrifice readability for aesthetics (body text must be readable)
-- Make everything bold (then nothing is bold; you need contrast)
-- Ignore accessibility (bold design must still meet WCAG standards)
-- Overwhelm with motion (animation fatigue is real)
-- Copy trendy aesthetics blindly (bold means distinctive, not derivative)
+- Add undocumented design-system primitives without user approval
+- Add effects randomly without purpose
+- Hide weak hierarchy behind decoration
+- Sacrifice readability for aesthetics
+- Make everything bold; contrast is the point
+- Ignore accessibility
+- Overwhelm with motion
+- Copy trendy aesthetics blindly
 
 ## Verify Quality
 
 Ensure amplification maintains usability and coherence:
 
+- **System-faithful**: Did the pass make the existing design language stronger before adding anything new?
+- **No undocumented drift**: Are new colors, gradients, shadows, radii, fonts, and effects either absent or explicitly approved and documented?
 - **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
 - **Still functional**: Can users accomplish tasks without distraction?
 - **Coherent**: Does everything feel intentional and unified?
-- **Memorable**: Will users remember this experience?
-- **Performant**: Do all these effects run smoothly?
-- **Accessible**: Does it still meet accessibility standards?
+- **Memorable**: Will users remember this experience for the intended reason?
+- **Performant and accessible**: Does the result stay fast, readable, responsive, and WCAG-conscious?
 
 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
 

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

@@ -60,7 +60,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg
 - Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige.
 - Palette IS voice. A calm brand and a restless brand should not share palette mechanics.
 - When the strategy is Committed or Drenched, color carries the brand. Don't hedge with neutrals around the edges. Commit.
-- Don't converge across projects. If the last brand surface was restrained-on-cream, this one is not.
+- Don't converge across projects. Each brand surface differentiates from the last.
 - When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette.
 
 ## Layout
@@ -74,7 +74,7 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg
 
 Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landing page without any imagery reads as incomplete, not as restrained. A solid-color rectangle where a hero image should go is worse than a representative stock photo.
 
-**When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
+**When the brief implies imagery, you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. If the approved comp or brief is image-led, ship real project assets, generated raster assets, or a credible canvas/SVG/WebGL scene. Do not replace photographic, architectural, product, or place imagery with generic CSS panels, decorative diagrams, cards, bullets, or copy.
 
 - **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. **Verify the URLs before referencing them.** If you have an image-search MCP, web-fetch tool, or browser access, use it to find real photo IDs and confirm they resolve. Guessed IDs (even ones that look real) often 404 and ship as broken-image placeholders. Without a verification path, pick fewer photos you're confident exist over more that you guessed; never substitute colored `<div>` placeholders.
 - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".

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

@@ -5,8 +5,9 @@ Resolve one stable target, run two independent assessments, synthesize a design
 ### Hard Invariants
 
 - Assessment A (design review) and Assessment B (detector/browser evidence) are both required.
+- Assessment A and B MUST run as two isolated sub-agents whenever a sub-agent/Task tool is exposed. Running them inline in this context is "possible" but is NOT permitted; it is a degraded run. Inline is allowed ONLY when no sub-agent tool exists (or the user declined, on harnesses that ask).
+- If you degrade for any reason, the report's first line MUST be a banner: `⚠️ DEGRADED: single-context (<reason>)`. A silent degraded critique is a failed critique.
 - Assessment A must finish before detector findings enter the parent synthesis context. Detector output is deterministic, but it still anchors judgment.
-- If sub-agents are unavailable, fall back sequentially: finish and record Assessment A first, then run Assessment B, then synthesize.
 - A skipped detector is a failed critique run unless `detect.mjs` is missing or crashes after a real attempt.
 - Viewable targets require browser inspection when available.
 - Any local server started only for critique visualization must run in the background, have a recorded stop method, and be stopped before final reporting unless the user asks to keep it.
@@ -27,7 +28,13 @@ Resolve one stable target, run two independent assessments, synthesize a design
 
 ### Assessment Orchestration
 
-Delegate Assessment A and Assessment B to separate sub-agents when possible. They must not see each other's output. Do not show findings to the user until synthesis.
+Delegate Assessment A and Assessment B to separate sub-agents. They must not see each other's output. Do not show findings to the user until synthesis.
+
+Sub-agent gate (all harnesses):
+- Unless a harness-specific gate below overrides this, spawn A and B as two isolated, parallel sub-agents whenever a sub-agent/Task tool is exposed. This is the default and is mandatory; do not run them inline because it is faster.
+- "Unavailable" means exactly one thing: no sub-agent/Task tool is exposed in this session (or, on harnesses that ask, the user declined). It does not mean inconvenient.
+- If and only if sub-agents are unavailable, fall back sequentially: finish and record Assessment A, then run Assessment B, then synthesize, and emit the degraded banner.
+- Whichever path you take, declare it in the report header (see Report header provenance). Skipping sub-agents without the banner is the most common failure of this command.
 
 If browser automation is available, each assessment creates its own new tab. Never reuse an existing tab, even if it is already at the right URL.
 
@@ -61,7 +68,7 @@ node .claude/skills/impeccable/scripts/detect.mjs --json [target]
 
 Browser visualization is required for a viewable target when browser automation is available. Use a localhost dev/static URL for local files; avoid `file://` unless the available browser explicitly supports this workflow. Overlay flow:
 
-1. Create a fresh tab and navigate.
+1. Create a fresh tab and navigate. Prefer the harness's native/browser-canvas screenshot path before hand-rolling a Playwright/Puppeteer script; only fall back to a custom script when no native browser tool is exposed.
 2. Preflight mutable injection by setting `document.title` and appending a `<script>` tag. Read-only evaluate APIs do not count.
 3. If mutation is unavailable, skip live server, browser presentation, and injection; report fallback signal.
 4. If mutation is available, start `node .claude/skills/impeccable/scripts/live-server.mjs --background`, present the browser if supported, label `[Human]`, scroll top, inject `http://localhost:PORT/detect.js`, wait 2-3 seconds, read `impeccable` console messages, then stop the live server.
@@ -79,6 +86,12 @@ The chat response is the primary user-facing deliverable. Present the full struc
 
 Structure your feedback as a design director would:
 
+#### Report header provenance
+
+The report's first line MUST declare how the assessments were run, so a degraded run is never silent:
+- Dual-agent: `Method: dual-agent (A: <agent-id> · B: <agent-id>)`
+- Degraded: `⚠️ DEGRADED: single-context (<reason, e.g. no sub-agent tool exposed>)`
+
 #### Design Health Score
 > *Consult the [Heuristics Scoring Guide](#heuristics-scoring-guide) section below.*
 

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

@@ -1,6 +1,6 @@
 Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
 
-DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): YAML frontmatter carrying machine-readable design tokens, followed by a markdown body with exactly six sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
+DESIGN.md follows the [official DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md): YAML frontmatter carrying machine-readable design tokens, followed by a markdown body with exactly six sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
 
 ## The frontmatter: token schema
 

.claude/skills/impeccable/reference/hooks.md

@@ -0,0 +1,92 @@
+# /impeccable hooks
+
+Manage the **design detector hook** for the current project.
+
+The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code, Codex, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
+
+This command toggles the hook **per project** by editing `.impeccable/config.json` (the unified Impeccable config; hook runtime settings live under its `hook` key, and shared detector ignores live under `detector`). Per-developer overrides, including the install consent decision (`hook.consent`) the CLI records, live in the gitignored `.impeccable/config.local.json`. Set `hook.enabled: false` to turn the hook off, `hook.quiet: true` to silence the clean/pending acks, or `hook.auditLog` to a file path for an NDJSON log. The legacy `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, and `IMPECCABLE_HOOK_LOG` env vars are still honored and override these config values when set.
+
+Declare server-side template extensions under **`detector.extensions`** when the project uses Blade, Twig, ERB, or Handlebars files; the hook skips them otherwise because they sit outside the built-in extension list. One entry per extension, `{ "ext": ".blade.php", "engine": "html" }`. `engine` picks the analyzer (`html` for markup templates, `text` for JS/TS/CSS-like files) and defaults to `html`. Match against the end of the filename, so double extensions like `.blade.php` and `.html.erb` work. Config only adds extensions; the built-in list always applies.
+
+Manual `npx impeccable detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `npx impeccable detect --no-config ...` for a raw detector run that ignores project config/context. Use `npx impeccable ignores ...` for direct CLI CRUD on the same detector ignores.
+
+Supported harnesses: Claude Code (`.claude/settings.local.json` in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared `settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project), Cursor (`.cursor/hooks.json` in the project), and GitHub Copilot (`.github/hooks/impeccable.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once `.github/hooks/impeccable.json` is committed to the repository's default branch.
+
+On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
+
+## Routing
+
+The first argument is the action. Defaults to `status`.
+
+| Action | What it does |
+|---|---|
+| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
+| `on` | Set `enabled: true` in `.impeccable/config.json`, record local hook consent as accepted, and install/repair provider hook manifests when the skill is installed. |
+| `off` | Set `enabled: false` in `.impeccable/config.json`. |
+| `ignore-rule <id>` | Append `<id>` to `detector.ignoreRules`; for `overused-font`, requires `--all-values`. |
+| `ignore-file <glob>` | Append `<glob>` to `detector.ignoreFiles`. |
+| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/config.json`. |
+| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/config.local.json`. |
+| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
+
+## Flow
+
+1. Resolve the action from the user's argument. If no action was given, default to `status`.
+2. Invoke the admin script and pass the user's output through verbatim:
+
+   ```bash
+   node .claude/skills/impeccable/scripts/hook-admin.mjs <action> [args...]
+   ```
+
+3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`."
+4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
+5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/config.json`; add `--local` only when the user explicitly asks for a private exception.
+6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
+
+## Intentional findings
+
+The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.
+
+Prefer the narrowest exception:
+
+- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/config.json` by default.
+- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` when the user confirms the specific value. Do not use `ignore-rule overused-font` for a specific font.
+- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
+- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
+- Prefer config ignores (the commands above) by default; they keep suppressions in one reviewable place. Reach for an inline comment only when the waiver must travel with a single file that leaves the repo (a generated/exported standalone document, an emailed HTML file). The supported marker is `impeccable-disable <rule>` (whole file) or `impeccable-disable-line` / `impeccable-disable-next-line` (one line), in any comment syntax, with an optional reason after `:` or `--`. The detector honors it by default; `--no-inline-ignores` or `--no-config` bypasses it.
+
+Example value-specific exception:
+
+```bash
+node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
+```
+
+Example intentional motion exception:
+
+```bash
+node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-value bounce-easing bounce-ball --shared --reason "User confirmed ball bounce animation is intentional"
+```
+
+Example whole-rule font exception:
+
+```bash
+node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
+```
+
+Example file-scoped exception:
+
+```bash
+node .claude/skills/impeccable/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
+```
+
+## Constraints
+
+- Never modify `.impeccable/config.json` or `.impeccable/config.local.json` by hand from this command. Always go through `hook-admin.mjs` so writes stay validated and the file shape stays consistent. One exception: `detector.extensions` has no admin action, so when the user asks to cover a template stack, edit that one field in `.impeccable/config.json` directly and leave the rest of the file untouched.
+- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
+- Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
+- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, and `.github/hooks/impeccable.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/impeccable.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
+
+## Failure modes
+
+- If `.impeccable/config.json` or `.impeccable/config.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `hook-admin.mjs status` will show malformed files as ignored.
+- If the user asks to "disable the hook" globally, lead with `/impeccable hooks off` (persistent for this project; writes `hook.enabled: false` to config). The legacy `IMPECCABLE_HOOK_DISABLED=1` env var also works as a one-shot override that follows the shell.

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

@@ -3,7 +3,7 @@
 The setup command for a project. One codebase crawl feeds everything it writes:
 
 - **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
-- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md). Answers "how it looks".
 - **`.impeccable/live/config.json`** (live mode): pre-configured so `/impeccable live` boots straight into variant mode with no first-time detour.
 
 It closes by pointing the user at the best command to run next. Every other impeccable command reads PRODUCT.md and DESIGN.md before doing any work.
@@ -16,6 +16,7 @@ Decision tree:
 - **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
 - **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `/impeccable document` for DESIGN.md.
 - **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
+- **PRODUCT.md exists but has no `## Platform` section (legacy)**: add it the same way, but only when the project is native (`ios` / `android` / `adaptive`) or the user wants it explicit; a missing field already means `web`.
 - **Both exist**: STOP and call the AskUserQuestion tool to clarify. Ask which file to refresh. Skip the one the user doesn't want changed.
 - **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
 
@@ -41,26 +42,34 @@ Also form a **register hypothesis** from what you find:
 
 Register is a hypothesis at this point, not a decision; Step 3 confirms it.
 
+Also form a **platform hypothesis**:
+
+- Native signals: React Native / Expo (`react-native`, `expo`), Flutter (`pubspec.yaml`, `flutter`), SwiftUI / UIKit (`.swift`, `.xcodeproj`, an `ios/` app target), Jetpack Compose / Android (`build.gradle`, an `android/` app module, `AndroidManifest.xml`). An `ios/` and/or `android/` directory that is a real app target, not just a Capacitor/Cordova wrapper around a website.
+- Web signals (the default): a web framework (Vite, Next, Nuxt, SvelteKit, Astro), an HTML entry, a CSS/Tailwind setup, no native app target.
+
+Values: `web` / `ios` / `android` / `adaptive` (one codebase, ships both, adapts per OS). Mobile web is still `web`. Like register, this is a hypothesis; Step 3 confirms it.
+
 Note what you've learned and what remains unclear. Also note any rough edges worth a follow-up command (thin hierarchy, flat or gray palette, missing error/empty states, dull copy); Step 7 turns these into concrete recommendations without re-analyzing.
 
 ## Step 3: Ask strategic questions (for PRODUCT.md)
 
-STOP and call the AskUserQuestion tool to clarify. Ask only about what you couldn't infer from the codebase.
+STOP and call the AskUserQuestion tool to clarify. Ask about anything the codebase doesn't answer with strong, explicit evidence.
 
 ### Interview mode, not confirmation mode
 
 If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
 
-- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
-- Ask **2-3 questions per round**, then wait for answers.
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop: one question at a time, with lettered options where the crawl suggests likely answers, waiting for each answer before the next.
+- Keep skill vocabulary (register, belief ladder, anti-references) out of question text; ask for the thing in words the user would use. For the brand register, ask like a magazine editor profiling the brand: curious and narrative, drawing out the story, the feel, and what a visitor should come to believe.
+- Ask in focused rounds and wait for answers between them. Keep **one topic per question**; add rounds rather than fold several topics into one either-or choice. Options obey the same rule: an option answers only the question asked; never write a compound option that bundles a feeling with a business outcome or names an additional audience.
 - Use inferred answers as hypotheses or options, not as finished facts.
 - Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
-- Round 1 should establish register, users/purpose, and desired outcome.
-- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+- Round 1 should establish register, platform, users, purpose, positioning, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs, plus conversion & proof for the brand register.
 
 ### Minimum viable interview
 
-Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
+Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, **platform confirmation** (`web` / `ios` / `android` / `adaptive`), users, purpose, positioning, brand personality, anti-references, and accessibility needs (plus conversion & proof for the brand register) unless each answer is directly discoverable from repo context. Never let the template's default `web` stand unconfirmed for a native or cross-platform repo. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
 
 ### Register (ask first; it shapes everything below)
 
@@ -68,20 +77,42 @@ Every design task is either **brand** (marketing, landing, campaign, long-form c
 
 If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
 
-If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and call the AskUserQuestion tool to clarify. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and call the AskUserQuestion tool to clarify. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default. Settle the default before drafting any register-dependent questions; never batch brand-only questions (Conversion & proof) into the same round as the question that decides the register.
+
+### Platform (ask right after register)
+
+Every project targets **web** (includes responsive mobile web), **ios**, **android**, or **adaptive** (one codebase, ships both, adapts per OS: Flutter, React Native, KMP). Platform picks the native rulebook: HIG for `ios`, Material 3 for `android`, both for `adaptive`, none for `web`.
+
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [web / ios / android / adaptive] project. Does that match?"* For cross-platform apps, decide by the **design language the app renders**, not the toolchain: one look on both platforms (Flutter's Material-everywhere default) takes that platform's value; genuine per-OS adaptation (Cupertino on iOS, Material on Android) is `adaptive`. When in doubt, `web`.
+
+A monorepo shipping both a website and a native app gets a PRODUCT.md per app, each with its own `## Platform`; the root PRODUCT.md carries the primary surface's platform.
 
 ### Users & Purpose
 - Who uses this? What's their context when using it?
 - What job are they trying to get done?
-- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
+- What is this for? A purpose stated in README or docs is a hypothesis, not strong evidence; confirm it, don't transcribe it.
+- What does success look like?
+- If more than one kind of user is plausible, confirm a primary and secondary audience; don't manufacture a split that isn't there. An audience implied by another answer (a success metric, a CTA) is still unconfirmed; ask before writing it as secondary.
+- If the surface speaks to a different audience than the people who use the product, ask the user to name both.
+- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency) Ask this standalone; don't fold emotions into the success question.
 - For product: what workflow are they in? What's the primary task on any given screen?
 
+### Positioning
+- In one line, what does this do that nothing else does? The single strategic claim every screen reinforces.
+
 ### Brand & Personality
 - How would you describe the brand personality in 3 words?
 - Reference sites or apps that capture the right feel? What specifically about them?
   - Push for specific named references with the *specific* thing about them that fits this brand, not generic "modern" adjectives or category-bucket lanes.
 - What should this explicitly NOT look like? Any anti-references?
 
+### Conversion & proof (brand register only)
+- What's the primary CTA?
+- What's the secondary fallback, for visitors not ready for the primary?
+- The one line a visitor should remember after 10 seconds.
+- What must the visitor believe, in order, before taking the primary CTA? (The template's belief ladder.)
+- What proof is on hand? Ask the user to hand over any testimonials, case studies, press, or client/partner logos they already have. If you can receive files directly, collect them; otherwise create `.impeccable/assets/proof/` and ask the user to add files there. Reference supplied files by path; record text proof inline.
+
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
@@ -90,7 +121,7 @@ Skip questions where the answer is already clear. **Do NOT ask about colors, fon
 
 ## Step 4: Write PRODUCT.md
 
-Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing. Confirmed means what the user actually said yes to; do not pad a confirmed answer with extras they never picked (additional anti-references, audiences, roadmap claims, a WCAG level), whether drawn from the crawl, another answer, or your own option text. If an extra belongs in the doc, ask about it first.
 
 Synthesize into a strategic document:
 
@@ -101,12 +132,26 @@ Synthesize into a strategic document:
 
 product
 
+## Platform
+
+web
+
 ## Users
-[Who they are, their context, the job to be done]
+[Who they are, their context, the job to be done. Primary audience; a secondary audience or a surface-vs-user split only when they apply.]
 
 ## Product Purpose
 [What this product does, why it exists, what success looks like]
 
+## Positioning
+[The single strategic claim every screen reinforces. Not a visual rule, not an anti-reference.]
+
+## Conversion & proof
+[Brand register only. Product register: omit this section entirely, heading included.]
+- Primary and secondary CTA: [...]
+- The line a visitor remembers after 10 seconds: [...]
+- Belief ladder: [...]
+- Proof on hand: [testimonials, case studies, press, or logos, referenced by path]
+
 ## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
@@ -120,7 +165,9 @@ product
 [WCAG level, known user needs, considerations]
 ```
 
-Register is either `brand` or `product` as a bare value. No prose, no commentary.
+Register is either `brand` or `product` as a bare value. No prose, no commentary. Platform is `web`, `ios`, `android`, or `adaptive`, also a bare value; omit the section only on legacy files you're leaving untouched, otherwise write `web` explicitly.
+
+Write fields as prose, and use bold sparingly: only where a word carries a decision, never as a label lead-in on every line.
 
 Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
 
@@ -137,6 +184,8 @@ If the user prefers to skip, mention they can run `/impeccable document` any tim
 
 ## Step 6: Configure live mode (when code exists)
 
+**Skip this step when the platform is native** (`ios` / `android` / `adaptive`): live mode drives a browser overlay. A hybrid wrapper or Expo web target serving HTML doesn't change that.
+
 If the project has code with HTML entries and a dev server (the same "code exists" condition that puts `/impeccable document` in scan mode), pre-configure live mode now. You already identified the framework and the served HTML entry in Step 2, so this is nearly free, and it spares the user the first-time setup detour when they later run `/impeccable live`.
 
 **Skip this step for empty / pre-implementation projects** (nothing to inject into yet). Tell the user live mode will configure itself the first time they run it once there's code.
@@ -154,16 +203,16 @@ Writing the config file is harmless and needs no consent; only the CSP **source-
 ## Step 7: Recommend starting points, then wrap up
 
 Summarize tersely:
-- Register captured (brand / product)
+- Register captured (brand / product) and platform captured (web / ios / android / adaptive)
 - What was written (PRODUCT.md, DESIGN.md, live config, or a subset)
 - The 3-5 strategic principles from PRODUCT.md that will guide future work
 - If DESIGN.md or live config is pending, one line on how to set it up later
 
-Then recommend the **best commands to run next**, drawn from what your Step 2 crawl already surfaced. Do not run a fresh analysis here; surface observations you already have. Tailor to register and to what you saw, offer the 2-4 most relevant (not a menu dump), and give the exact command to type. Group by intent:
+Then recommend the **best commands to run next**, drawn from what your Step 2 crawl already surfaced. Do not run a fresh analysis here; surface observations you already have. Tailor to register **and platform**, offer the 2-4 most relevant (not a menu dump), and give the exact command to type. Group by intent:
 
 - **Build something new**: `/impeccable craft <feature>` (shape, then build end-to-end) or `/impeccable shape <feature>` (plan first). Lead with this for empty or early-stage projects.
 - **Improve what's there**: name the specific surface. `/impeccable critique <page>` for a scored UX review; `/impeccable audit <area>` for a11y / perf / responsive checks; `/impeccable polish <component>` for a pre-ship pass. When the crawl flagged a specific weakness, point the matching command at it: thin hierarchy or spacing → `layout`, flat or gray palette → `colorize`, missing error / empty states → `harden` or `onboard`, dull or unclear copy → `clarify`.
-- **Iterate visually**: `/impeccable live` (configured in Step 6) to pick elements in the browser and generate variants in place.
+- **Iterate visually** (web only): `/impeccable live` (configured in Step 6) to pick elements in the browser and generate variants in place. **Skip this group for native platforms.**
 
 The full command menu is one bare `/impeccable` away; keep this list short and pointed.
 

.claude/skills/impeccable/reference/ios.md

@@ -0,0 +1,45 @@
+# iOS platform
+
+For native iOS / iPadOS apps: SwiftUI, UIKit, React Native, Expo, Flutter shipping to Apple hardware.
+
+On native, register narrows. HIG conformance governs structure, navigation, and interaction whatever the register; brand expresses through the expressive layer the platform provides (tint, type, motion, content). Calm, Duolingo, and Spotify carry strong identity entirely inside HIG conventions.
+
+## The iOS slop test
+
+Would a fluent iPhone user trust this app, or pause at off-spec controls? The tell is "ported from a website": reinvented navigation bars, custom back gestures, web-shaped buttons, hover-dependent affordances. Default to the platform's components; depart only for a reason the user would thank you for.
+
+## Layout & structure
+
+- **Safe area.** Lay out inside the safe-area insets. No controls under the notch, Dynamic Island, home indicator, or rounded corners.
+- **System navigation.** Tab bar for 2–5 top-level sections (sections, never actions), navigation stack for hierarchy, sheet for self-contained tasks. No custom global nav, no mixed metaphors.
+- **Edge-swipe back stays alive.** The left-edge back gesture is muscle memory; never disable or overlay it.
+- **Large titles** on top-level screens, collapsing to inline on scroll. Deep detail screens stay inline.
+
+## Touch targets
+
+- **44×44 pt minimum** for every tappable control, with breathing room between adjacent targets.
+
+## Typography
+
+- **Dynamic Type.** Use the system text styles (Large Title through Caption) so text follows the user's reading size. No hard-coded point sizes.
+- **San Francisco carries the UI.** Body, labels, and controls stay on SF Pro / SF Compact; a brand face may appear in display moments.
+- **11 pt floor**; Body is 17 pt.
+
+## Color & materials
+
+- **Semantic system colors** (label, secondaryLabel, systemBackground, separator, tint). They adapt to Dark Mode and increased contrast automatically; raw hex breaks there.
+- **Dark Mode is a first-class appearance.** Design and test both.
+- **One tint color** drives interactive elements; decoration is not its job.
+- **System materials** for blur and translucency behind bars and sheets; no hand-rolled glassmorphism.
+
+## Components & controls
+
+- **Platform controls.** Switch, segmented control, stepper, system pickers, action sheets, alerts, context menus, swipe actions. Reinventing these for flavor is the most common native slop.
+- **SF Symbols** for iconography: baseline-aligned, Dynamic Type-aware, weight and scale variants. Don't mix in a web icon set.
+- **Deliberate modality.** Sheet for a focused dismissible sub-task, full-screen cover for immersion. Clear Cancel/Done; honor swipe-to-dismiss unless data loss requires a guard.
+- **Grouped/inset lists** for settings-shaped content; no bespoke card stacks.
+
+## Motion
+
+- **System transitions.** Push slides, sheets rise, dismiss reverses the entrance. Custom transitions that fight the navigation model disorient.
+- **Honor Reduce Motion.** Crossfade instead of parallax and large slides.

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

@@ -8,11 +8,33 @@ Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-b
 
 Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
 
+Native (`ios` / `android` / `adaptive`): structure follows the Layout section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): platform navigation, insets, and touch targets, never the CSS tooling below.
+
+---
+
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the layout assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, documented spacing scale when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (layout assessment)**: give it the full [Assess Current Layout](#assess-current-layout) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to layout:
+
+```bash
+node .claude/skills/impeccable/scripts/detect.mjs --json --scope layout [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The detector abstains on arbitrary Tailwind spacing (`gap-[13px]`, `p-[7px]`) and ad-hoc `z-index` stacks, so when the project documents a spacing scale, also grep `gap-\[`, `p[trblxy]?-\[`, `m[trblxy]?-\[`, `z-\[` and judge those hits against it. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a monotone grid with uniform spacing passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
 ---
 
 ## Assess Current Layout
 
-Analyze what's weak about the current spatial design:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak about the current spatial design:
 
 1. **Spacing**:
    - Is spacing consistent or arbitrary? (Random padding/margin values)
@@ -138,6 +160,8 @@ Create a systematic plan:
 - **Consistency**: Is the spacing system applied uniformly?
 - **Responsiveness**: Does the layout adapt gracefully across screen sizes?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the rhythm and hierarchy land, hand off to `/impeccable polish` for the final pass.
 
 ## Live-mode signature params

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

@@ -8,7 +8,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR
 
 Execute in order. No step skipped, no step reordered.
 
-1. `live.mjs`: boot.
+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`.
 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). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
 
@@ -111,7 +111,9 @@ node .claude/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 
 The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Load `brand.md` or `product.md` (freeform only, no action sub-command). Write all variants in one edit, then `--reply done`.
 
-On accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
+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.
 
 ### Replace mode (default)
 
@@ -149,6 +151,25 @@ If `--text` matches multiple candidates equally well, wrap exits with `{ error:
 
 Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
 
+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 the Svelte component path go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, so a `data-impeccable-params='[{…}]'` attribute on a component element fails to compile (`Expected token }`). Declare params for this path in `componentDir/params.json`, keyed by variant number, using the exact param 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"}
+  ]
+}
+```
+
+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.
+
 `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.
@@ -340,7 +361,7 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
 
 **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:
+**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the Svelte `svelte-component` path, do not use this attribute** (Svelte can't compile `{` inside an attribute value). Declare params in `componentDir/params.json` keyed by variant number instead (see the Svelte component paragraph in the wrap section). The param schema below is identical for both paths.
 
 ```html
 <div data-impeccable-variant="1" data-impeccable-params='[
@@ -454,7 +475,7 @@ Do these five steps in the current thread, synchronously, before the next poll.
 1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
 2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
 3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
-4. **Unwrap the accepted content.** Delete the `<div data-impeccable-variant="N" style="display: contents">` that wraps it. Drop `data-impeccable-params` and any `data-p-*` attributes from it; those are live-mode plumbing, not source.
+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, run `live-complete.mjs --id SESSION_ID`, verify it reports `phase: "completed"`, then poll again.

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

@@ -10,9 +10,29 @@ Product: system fonts and familiar sans stacks are legitimate here. One well-tun
 
 ---
 
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents whenever a sub-agent/Task tool is exposed: one for the typography assessment, one for the mechanical pre-scan. If the harness needs explicit user permission for sub-agents, stop and ask before proceeding. Isolation is the point: detector output anchors visual judgment toward what the scan can see, so neither sub-agent gets the other's output. Each assessment runs in its own sub-agent; running either one in this context when a sub-agent tool exists is not permitted, even when it is faster; the fallback below is only for sessions with no sub-agent tool. Give each a self-contained prompt (target files, register, **DESIGN.md** content when present, and its instructions below); do not assume it can read this file.
+
+**Sub-agent A (typography assessment)**: give it the full [Assess Current Typography](#assess-current-typography) checklist below, verbatim, in its prompt. It works through every item and returns per-item findings citing file, selector, or value.
+
+**Sub-agent B (mechanical pre-scan)**: run the bundled detector scoped to type:
+
+```bash
+node .claude/skills/impeccable/scripts/detect.mjs --json --scope type [target files or dirs]
+```
+
+A missing `node` on PATH is not permission to skip: hunt for a runtime (`command -v node`, nvm or Homebrew paths, the harness's own bundled node) and run it by full path. If none exists, halt the scan and report that Node must be installed (the parent relays this to the user); do **not** substitute grep for the detector or proceed unscanned. The scan checks literal font sizes against the **DESIGN.md** ramp but abstains on `em`, `%`, `clamp()`, and line-heights, so also grep `font-size\s*:`, `fontSize`, `text-\[`, `leading-\[` and judge those hits against the spec. Return the findings JSON plus the grep verdicts.
+
+**If no sub-agent tool is exposed (or the user declined)**: run both yourself, assessment first, pre-scan second, so the deterministic findings can't anchor the visual judgment. Keep that order even when the scan feels quicker to start with.
+
+**Synthesize** once both are done: merge into a single findings list, noting where they agree and what each caught alone. Fix every finding, or list it as a deliberate exception for the user to accept. A clean scan is a floor, not a verdict: a generic font stack at a flat scale passes every detector rule, which is exactly what the assessment exists to catch. State in your final summary which path ran (parallel sub-agents or single-context fallback).
+
+---
+
 ## Assess Current Typography
 
-Analyze what's weak or generic about the current type:
+This checklist is sub-agent A's brief (on the fallback path, work through it yourself before the pre-scan). Analyze what's weak or generic about the current type:
 
 1. **Font choices**:
    - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
@@ -109,6 +129,8 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
+Answer each item above by citing the file, selector, or value that satisfies it; never a bare yes. Then re-run the pre-scan and fix until the count of unresolved items and unaccepted findings is zero.
+
 When the type carries the hierarchy on its own, hand off to `/impeccable polish` for the final pass.
 
 ## Live-mode signature params

.claude/skills/impeccable/scripts/cleanup-deprecated.mjs

@@ -1,284 +0,0 @@
-#!/usr/bin/env node
-/**
- * Cleans up deprecated Impeccable skill files, symlinks, and
- * skills-lock.json entries left over from previous versions.
- *
- * Safe to run repeatedly -- it is a no-op when nothing needs cleaning.
- *
- * Usage (from the project root):
- *   node {{scripts_path}}/cleanup-deprecated.mjs
- *
- * What it does:
- *   1. Finds every harness-specific skills directory (.claude/skills,
- *      .cursor/skills, .agents/skills, etc.).
- *   2. For each deprecated skill name (with and without i- prefix),
- *      checks if the directory exists and its SKILL.md mentions
- *      "impeccable" (to avoid deleting unrelated user skills).
- *   3. Deletes confirmed matches (files, directories, or symlinks).
- *   4. Removes the corresponding entries from skills-lock.json.
- */
-
-import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-// Skills that were renamed, merged, or folded in v2.0, v2.1, and v3.0.
-const DEPRECATED_NAMES = [
-  // v2.0 renames
-  'frontend-design',    // renamed to impeccable
-  'teach-impeccable',   // folded into /impeccable init
-  // v2.1 merges
-  'arrange',            // renamed to layout
-  'normalize',          // merged into polish
-  'onboard',            // merged into harden
-  'extract',            // merged into /impeccable extract
-  // v3.0 consolidation: all standalone skills -> /impeccable sub-commands
-  'adapt',
-  'animate',
-  'audit',
-  'bolder',
-  'clarify',
-  'colorize',
-  'critique',
-  'delight',
-  'distill',
-  'harden',
-  'layout',
-  'optimize',
-  'overdrive',
-  'polish',
-  'quieter',
-  'shape',
-  'typeset',
-];
-
-// All known harness directories that may contain a skills/ subfolder.
-const HARNESS_DIRS = [
-  '.claude', '.cursor', '.gemini', '.codex', '.agents',
-  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
-];
-
-// Per-skill fingerprints for SKILL.md bodies that never mentioned
-// "impeccable" in their v2.x source. Used as a last-resort match
-// when no skills-lock.json exists and the word heuristic fails.
-// The strings are lifted verbatim from the v2.x frontmatter
-// descriptions, so collisions with hand-written user skills are
-// vanishingly unlikely.
-const SKILL_FINGERPRINTS = {
-  harden: 'Make interfaces production-ready: error handling, empty states',
-  optimize: 'Diagnoses and fixes UI performance across loading speed',
-};
-
-/**
- * Walk up from startDir until we find a directory that looks like a
- * project root (has package.json, .git, or skills-lock.json).
- */
-export function findProjectRoot(startDir = process.cwd()) {
-  let dir = resolve(startDir);
-  const { root } = { root: '/' };
-  while (dir !== root) {
-    if (
-      existsSync(join(dir, 'package.json')) ||
-      existsSync(join(dir, '.git')) ||
-      existsSync(join(dir, 'skills-lock.json'))
-    ) {
-      return dir;
-    }
-    const parent = resolve(dir, '..');
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return resolve(startDir);
-}
-
-/**
- * Load skills-lock.json from the project root, or null if missing/unreadable.
- */
-export function loadLock(projectRoot) {
-  const lockPath = join(projectRoot, 'skills-lock.json');
-  if (!existsSync(lockPath)) return null;
-  try {
-    return JSON.parse(readFileSync(lockPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check whether a skill directory belongs to Impeccable. Three layered
- * signals, in order of reliability:
- *   1. Lock source equals "pbakaus/impeccable" (authoritative).
- *   2. SKILL.md body contains the word "impeccable".
- *   3. SKILL.md body contains a per-skill fingerprint (for harden and
- *      optimize, whose v2.x SKILL.md never mentioned the pack name).
- */
-export function isImpeccableSkill(skillDir, { skillName, lock } = {}) {
-  // 1. Authoritative: the lock file claims this skill is ours.
-  if (skillName && lock?.skills?.[skillName]?.source === 'pbakaus/impeccable') {
-    return true;
-  }
-  const skillMd = join(skillDir, 'SKILL.md');
-  if (!existsSync(skillMd)) return false;
-  let content;
-  try {
-    content = readFileSync(skillMd, 'utf-8');
-  } catch {
-    return false;
-  }
-  // 2. Word-level content heuristic.
-  if (/impeccable/i.test(content)) return true;
-  // 3. Per-skill fingerprint for old skills that never mentioned the pack.
-  //    Strip the i- prefix so both `harden` and `i-harden` resolve to the
-  //    same fingerprint entry.
-  const unprefixed = skillName?.startsWith('i-') ? skillName.slice(2) : skillName;
-  const fingerprint = unprefixed && SKILL_FINGERPRINTS[unprefixed];
-  if (fingerprint && content.includes(fingerprint)) return true;
-  return false;
-}
-
-/**
- * Build the full list of names to check: each deprecated name, plus
- * its i-prefixed variant.
- */
-export function buildTargetNames() {
-  const names = [];
-  for (const name of DEPRECATED_NAMES) {
-    names.push(name);
-    names.push(`i-${name}`);
-  }
-  return names;
-}
-
-/**
- * Find every skills directory across all harness dirs in the project.
- * Returns absolute paths that exist on disk.
- */
-export function findSkillsDirs(projectRoot) {
-  const dirs = [];
-  for (const harness of HARNESS_DIRS) {
-    const candidate = join(projectRoot, harness, 'skills');
-    if (existsSync(candidate)) {
-      dirs.push(candidate);
-    }
-  }
-  return dirs;
-}
-
-/**
- * Remove deprecated skill directories/symlinks from all harness dirs.
- * Reads skills-lock.json so the authoritative "source" field can
- * drive deletion even when SKILL.md never mentions impeccable.
- * Returns an array of paths that were deleted.
- */
-export function removeDeprecatedSkills(projectRoot, lock) {
-  if (lock === undefined) lock = loadLock(projectRoot);
-  const targets = buildTargetNames();
-  const skillsDirs = findSkillsDirs(projectRoot);
-  const deleted = [];
-
-  for (const skillsDir of skillsDirs) {
-    for (const name of targets) {
-      const skillPath = join(skillsDir, name);
-
-      // Use lstat to detect symlinks (existsSync follows symlinks and
-      // returns false for dangling ones).
-      let stat;
-      try {
-        stat = lstatSync(skillPath);
-      } catch {
-        continue; // does not exist at all
-      }
-
-      if (stat.isSymbolicLink()) {
-        // Symlink: check the target if it's alive, otherwise treat
-        // dangling symlinks to deprecated names as safe to remove.
-        const targetAlive = existsSync(skillPath);
-        const isMatch = targetAlive
-          ? isImpeccableSkill(skillPath, { skillName: name, lock })
-          : true;
-        if (isMatch) {
-          unlinkSync(skillPath);
-          deleted.push(skillPath);
-        }
-        continue;
-      }
-
-      // Regular directory -- verify it belongs to impeccable
-      if (isImpeccableSkill(skillPath, { skillName: name, lock })) {
-        rmSync(skillPath, { recursive: true, force: true });
-        deleted.push(skillPath);
-      }
-    }
-  }
-
-  return deleted;
-}
-
-/**
- * Remove deprecated entries from skills-lock.json.
- * Only removes entries whose source is "pbakaus/impeccable".
- * Returns the list of removed skill names.
- */
-export function cleanSkillsLock(projectRoot) {
-  const lockPath = join(projectRoot, 'skills-lock.json');
-  if (!existsSync(lockPath)) return [];
-
-  let lock;
-  try {
-    lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
-  } catch {
-    return [];
-  }
-
-  if (!lock.skills || typeof lock.skills !== 'object') return [];
-
-  const targets = buildTargetNames();
-  const removed = [];
-
-  for (const name of targets) {
-    const entry = lock.skills[name];
-    if (!entry) continue;
-    // Only remove if it belongs to impeccable
-    if (entry.source === 'pbakaus/impeccable') {
-      delete lock.skills[name];
-      removed.push(name);
-    }
-  }
-
-  if (removed.length > 0) {
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
-  }
-
-  return removed;
-}
-
-/**
- * Run the full cleanup. Returns a summary object.
- *
- * Order matters: read the lock and delete directories first, then
- * strip lock entries. Otherwise the authoritative signal is gone by
- * the time directory deletion runs.
- */
-export function cleanup(projectRoot) {
-  const root = projectRoot || findProjectRoot();
-  const lock = loadLock(root);
-  const deletedPaths = removeDeprecatedSkills(root, lock);
-  const removedLockEntries = cleanSkillsLock(root);
-  return { deletedPaths, removedLockEntries, projectRoot: root };
-}
-
-// CLI entry point
-if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
-  const result = cleanup();
-  if (result.deletedPaths.length === 0 && result.removedLockEntries.length === 0) {
-    console.log('No deprecated Impeccable skills found. Nothing to clean up.');
-  } else {
-    if (result.deletedPaths.length > 0) {
-      console.log(`Removed ${result.deletedPaths.length} deprecated skill(s):`);
-      for (const p of result.deletedPaths) console.log(`  - ${p}`);
-    }
-    if (result.removedLockEntries.length > 0) {
-      console.log(`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`);
-      for (const name of result.removedLockEntries) console.log(`  - ${name}`);
-    }
-  }
-}

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Context-signals gatherer for the bare `{{command_prefix}}impeccable`
+ * Context-signals gatherer for the bare Impeccable invocation
  * (no-argument) path. Collects cheap, deterministic signals about the current
  * project and emits them as JSON.
  *
@@ -21,8 +21,8 @@ import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { loadContext, extractRegister } from './context.mjs';
-import { getCritiqueDir } from './impeccable-paths.mjs';
+import { loadContext, extractRegister, extractPlatform } from './context.mjs';
+import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 /** Is there code here at all, or just context files / an empty repo? */
 function hasCode(cwd) {
@@ -197,6 +197,7 @@ export async function gatherSignals(cwd = process.cwd()) {
       designPath: ctx.designPath,
       hasCode: hasCode(cwd),
       register: extractRegister(ctx.product),
+      platform: extractPlatform(ctx.product),
     },
     critique: { latest: latestCritique(cwd) },
     git,

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

@@ -1,15 +1,18 @@
 /**
  * Context loader: prints PRODUCT.md (and DESIGN.md if present) as one
- * markdown block on stdout, or exits with empty stdout when no PRODUCT.md
- * is found anywhere. The skill keys off "empty stdout" to branch into the
- * init flow.
+ * markdown block on stdout, or prints a `NO_PRODUCT_MD:` message when no
+ * PRODUCT.md is found anywhere. The skill keys off that message to branch:
+ * from-scratch build commands (init / teach / craft / shape) and clear
+ * build/shape intent divert into the init flow, while scoped commands proceed
+ * using the existing code as context.
  *
  * Path resolution (first match wins):
- *   1. cwd, if PRODUCT.md or DESIGN.md is there
- *   2. .agents/context/ then docs/
- *   3. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
+ *   1. Active project root, if PRODUCT.md or DESIGN.md is there
+ *   2. Active project .agents/context/ then docs/
+ *   3. Monorepo root context, using the same order, as a per-file fallback
+ *   4. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
  *      escape hatch, only consulted when defaults are empty
- *   4. cwd as a "nothing found" default
+ *   5. Active project root as a "nothing found" default
  *
  * `resolveContextDir()` and `loadContext()` are also exported for the
  * server-side scripts (live.mjs, live-server.mjs) that need the structured
@@ -19,15 +22,31 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parseTargetOptions } from './lib/target-args.mjs';
+import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
 
 const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
 const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
 const FALLBACK_DIRS = ['.agents/context', 'docs'];
+const MONOREPO_MARKER_FILES = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json'];
+const MONOREPO_FALLBACK_PROJECT_DIRS = ['apps', 'packages'];
+const WORKSPACE_DISCOVERY_IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.turbo',
+  '.cache',
+  'coverage',
+]);
 
 // ─── Update check ──────────────────────────────────────────────────────────
 // Piggyback a lightweight skill-version check on the once-per-session boot.
 // When a newer skill ships, append an UPDATE_AVAILABLE directive so the agent
-// can offer `npx impeccable skills update`. Everything here is best-effort and
+// can offer `npx impeccable update`. Everything here is best-effort and
 // silent on failure: a network problem, sandbox, or missing cache must never
 // block context output or print an error.
 
@@ -38,41 +57,623 @@ const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // throttle the network poll to o
 const RENOTIFY_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // don't re-surface the same version for a week
 const FETCH_TIMEOUT_MS = 1200;
 
-export function resolveContextDir(cwd = process.cwd()) {
-  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-    return cwd;
-  }
-  for (const rel of FALLBACK_DIRS) {
-    const candidate = path.resolve(cwd, rel);
-    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-      return candidate;
-    }
-  }
-  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
-  if (envDir && envDir.trim()) {
-    const trimmed = envDir.trim();
-    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  }
-  return cwd;
+export function resolveContextDir(cwd = process.cwd(), options = {}) {
+  return resolveContext(cwd, options).contextDir;
 }
 
-export function loadContext(cwd = process.cwd()) {
-  const contextDir = resolveContextDir(cwd);
-  const productPath = firstExisting(contextDir, PRODUCT_NAMES);
-  const designPath = firstExisting(contextDir, DESIGN_NAMES);
+export function loadContext(cwd = process.cwd(), options = {}) {
+  const resolved = resolveContext(cwd, options);
+  const absCwd = path.resolve(cwd);
+  const productPath = resolved.productPath;
+  const designPath = resolved.designPath;
   const product = productPath ? safeRead(productPath) : null;
   const design = designPath ? safeRead(designPath) : null;
   return {
     hasProduct: !!product,
     product,
-    productPath: productPath ? path.relative(cwd, productPath) : null,
+    productPath: productPath ? path.relative(absCwd, productPath) : null,
     hasDesign: !!design,
     design,
-    designPath: designPath ? path.relative(cwd, designPath) : null,
-    contextDir,
+    designPath: designPath ? path.relative(absCwd, designPath) : null,
+    contextDir: resolved.contextDir,
+    productContextDir: productPath ? path.dirname(productPath) : null,
+    designContextDir: designPath ? path.dirname(designPath) : null,
+    projectRoot: resolved.projectRoot,
+    repoRoot: resolved.repoRoot,
+    isMonorepo: resolved.isMonorepo,
   };
 }
 
+function resolveContext(cwd = process.cwd(), options = {}) {
+  const absCwd = path.resolve(cwd);
+  const project = resolveProject(absCwd, options);
+  const projectContextDir = resolveLocalContextDir(project.projectRoot);
+  const rootContextDir = project.isMonorepo && project.repoRoot !== project.projectRoot
+    ? resolveLocalContextDir(project.repoRoot)
+    : null;
+
+  let productPath =
+    (projectContextDir ? firstExisting(projectContextDir, PRODUCT_NAMES) : null)
+    || (rootContextDir ? firstExisting(rootContextDir, PRODUCT_NAMES) : null);
+  let designPath =
+    (projectContextDir ? firstExisting(projectContextDir, DESIGN_NAMES) : null)
+    || (rootContextDir ? firstExisting(rootContextDir, DESIGN_NAMES) : null);
+
+  let envContextDir = null;
+  if (!productPath && !designPath) {
+    envContextDir = resolveEnvContextDir(absCwd);
+    if (envContextDir) {
+      productPath = firstExisting(envContextDir, PRODUCT_NAMES);
+      designPath = firstExisting(envContextDir, DESIGN_NAMES);
+    }
+  }
+
+  return {
+    contextDir: productPath
+      ? path.dirname(productPath)
+      : designPath
+        ? path.dirname(designPath)
+        : envContextDir || project.projectRoot,
+    productPath,
+    designPath,
+    projectRoot: project.projectRoot,
+    repoRoot: project.repoRoot,
+    isMonorepo: project.isMonorepo,
+    targetDir: project.targetDir,
+  };
+}
+
+export function resolveProjectRoot(cwd = process.cwd(), options = {}) {
+  return resolveProject(cwd, options).projectRoot;
+}
+
+export function resolveTargetSelection(cwd = process.cwd(), options = {}) {
+  if (hasTargetOption(options)) return null;
+  const project = resolveProject(cwd);
+  if (
+    !project.isMonorepo
+    || !project.projectRoot
+    || !project.repoRoot
+    || path.resolve(project.projectRoot) !== path.resolve(project.repoRoot)
+  ) {
+    return null;
+  }
+  const targetCandidates = discoverTargetCandidates(project.repoRoot);
+  // No discoverable child apps (e.g. `workspaces: ["."]`, a root-only workspace,
+  // or a marker file with no apps/packages children): there is nothing to choose,
+  // so treat the repo root as the active project rather than blocking on an empty
+  // selection prompt that the user cannot answer.
+  if (targetCandidates.length === 0) return null;
+  return {
+    targetPath: null,
+    projectRoot: project.projectRoot,
+    repoRoot: project.repoRoot,
+    targetCandidates,
+  };
+}
+
+function resolveProject(cwd = process.cwd(), options = {}) {
+  const absCwd = path.resolve(cwd);
+  const targetDir = resolveTargetDir(absCwd, options);
+  let repoRoot = findMonorepoRoot(targetDir);
+  if (!repoRoot && targetDir !== absCwd) {
+    const cwdRepoRoot = findMonorepoRoot(absCwd);
+    if (cwdRepoRoot && isPathInside(targetDir, cwdRepoRoot)) {
+      repoRoot = cwdRepoRoot;
+    }
+  }
+  if (!repoRoot) {
+    return {
+      targetDir,
+      projectRoot: absCwd,
+      repoRoot: absCwd,
+      isMonorepo: false,
+    };
+  }
+  return {
+    targetDir,
+    projectRoot: resolveWorkspaceProjectRoot(repoRoot, targetDir) || repoRoot,
+    repoRoot,
+    isMonorepo: true,
+  };
+}
+
+function isPathInside(candidate, root) {
+  const rel = path.relative(root, candidate);
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function resolveLocalContextDir(root) {
+  if (firstExisting(root, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+    return root;
+  }
+  for (const rel of FALLBACK_DIRS) {
+    const candidate = path.resolve(root, rel);
+    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function resolveEnvContextDir(cwd) {
+  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
+  if (!envDir || !envDir.trim()) return null;
+  const trimmed = envDir.trim();
+  return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+}
+
+function resolveTargetDir(cwd, options = {}) {
+  const targetPath = options && typeof options === 'object' ? options.targetPath : null;
+  if (!targetPath || !String(targetPath).trim()) return cwd;
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+  try {
+    const stat = fs.statSync(abs);
+    return stat.isDirectory() ? abs : path.dirname(abs);
+  } catch {
+    return path.extname(abs) ? path.dirname(abs) : abs;
+  }
+}
+
+function findMonorepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const homeDir = path.resolve(os.homedir());
+  while (true) {
+    if (dir === homeDir) return null;
+    // isMonorepoRoot is checked before hasGitBoundary on purpose: a workspace
+    // root that also carries its own .git is still recognized. The trade-off is
+    // deliberate — a directory with a monorepo *marker* but no workspace patterns
+    // and no apps/packages children is not a monorepo root, so its .git stops
+    // traversal and a further-up root is not searched. The nested .git is treated
+    // as an independent project boundary, which is the intended isolation.
+    if (isMonorepoRoot(dir)) return dir;
+    if (hasGitBoundary(dir)) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function isMonorepoRoot(dir) {
+  if (readWorkspacePatterns(dir).some((pattern) => !normalizeWorkspacePattern(pattern).startsWith('!'))) return true;
+  if (!MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(dir, file)))) return false;
+  return hasFallbackWorkspaceChildren(dir);
+}
+
+function hasGitBoundary(dir) {
+  return fs.existsSync(path.join(dir, '.git'));
+}
+
+function hasFallbackWorkspaceChildren(dir) {
+  for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
+    const base = path.join(dir, name);
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    if (entries.some((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))) return true;
+  }
+  return false;
+}
+
+function discoverTargetCandidates(repoRoot) {
+  const roots = new Map();
+  const patterns = readWorkspacePatterns(repoRoot);
+  for (const pattern of patterns) {
+    for (const root of discoverRootsForPattern(repoRoot, pattern)) {
+      roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
+    }
+  }
+  if (MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(repoRoot, file)))) {
+    for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
+      const base = path.join(repoRoot, name);
+      let entries;
+      try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+        const root = path.join(base, entry.name);
+        roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
+      }
+    }
+  }
+  return [...roots.entries()]
+    .filter(([rel]) => rel && !rel.startsWith('..'))
+    // Honor negated workspace patterns (e.g. "!packages/internal"). resolveWorkspaceProjectRoot
+    // sends an excluded package back to the repo root, so an excluded folder must not appear as a
+    // selectable target — choosing it would silently resolve to the root instead.
+    .filter(([rel]) => !isExcludedByWorkspacePattern(rel.split('/').filter(Boolean), patterns))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([rel, root]) => {
+      const targetExample = findTargetExample(repoRoot, root);
+      return {
+        name: path.basename(root),
+        path: rel,
+        targetExample,
+        ...resolveCandidateContextSummary(repoRoot, root, targetExample),
+      };
+    });
+}
+
+function resolveCandidateContextSummary(repoRoot, projectRoot, targetPath) {
+  const ctx = resolveContext(repoRoot, { targetPath });
+  return {
+    productStatus: contextSourceStatus(ctx.productPath, repoRoot, projectRoot),
+    productPath: contextSourcePath(ctx.productPath, repoRoot),
+    designStatus: contextSourceStatus(ctx.designPath, repoRoot, projectRoot),
+    designPath: contextSourcePath(ctx.designPath, repoRoot),
+  };
+}
+
+// Selection candidates surface one of four statuses: 'child' (a canonical
+// PRODUCT.md/DESIGN.md directly in the app root), 'inherited' (resolved from the
+// repo root in a monorepo), 'missing' (no file found), and 'fallback'. 'fallback'
+// intentionally covers two non-canonical locations: a file inside the project
+// root but in a subdirectory (FALLBACK_DIRS, e.g. `.agents/context/`), and a file
+// outside both the project and repo roots (IMPECCABLE_CONTEXT_DIR override).
+function contextSourceStatus(filePath, repoRoot, projectRoot) {
+  if (!filePath) return 'missing';
+  const absPath = path.resolve(filePath);
+  const absProjectRoot = path.resolve(projectRoot);
+  const absRepoRoot = path.resolve(repoRoot);
+  if (isPathInsideOrEqual(absPath, absProjectRoot)) {
+    return path.dirname(absPath) === absProjectRoot ? 'child' : 'fallback';
+  }
+  if (absProjectRoot !== absRepoRoot && isPathInsideOrEqual(absPath, absRepoRoot)) {
+    return 'inherited';
+  }
+  return 'fallback';
+}
+
+function contextSourcePath(filePath, repoRoot) {
+  if (!filePath) return null;
+  const rel = path.relative(repoRoot, filePath);
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+    return rel.split(path.sep).join('/');
+  }
+  return filePath;
+}
+
+function discoverRootsForPattern(repoRoot, rawPattern) {
+  const pattern = normalizeWorkspacePattern(rawPattern);
+  if (!pattern || pattern.startsWith('!')) return [];
+  const segments = pattern.split('/').filter(Boolean);
+  if (!segments.length) return [];
+  const firstGlobIndex = segments.findIndex((segment) => segment.includes('*'));
+  const literalPrefix = firstGlobIndex === -1 ? segments : segments.slice(0, firstGlobIndex);
+  const base = path.join(repoRoot, ...literalPrefix);
+  if (!fs.existsSync(base)) return [];
+  if (segments.includes('**')) {
+    const packageRoots = [];
+    walkDirs(base, (dir) => {
+      if (dir !== base && isCandidateProjectRoot(dir)) packageRoots.push(dir);
+    });
+    if (packageRoots.length) return packageRoots;
+    return directChildDirs(base);
+  }
+  return expandSimplePattern(repoRoot, segments);
+}
+
+function expandSimplePattern(repoRoot, patternSegments, index = 0, current = repoRoot) {
+  if (index >= patternSegments.length) return fs.existsSync(current) ? [current] : [];
+  const segment = patternSegments[index];
+  if (!segment.includes('*')) {
+    return expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, segment));
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const roots = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+    if (!segmentMatches(segment, entry.name)) continue;
+    roots.push(...expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, entry.name)));
+  }
+  return roots;
+}
+
+function directChildDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))
+      .map((entry) => path.join(dir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+function walkDirs(root, visit) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
+    const dir = path.join(root, entry.name);
+    visit(dir);
+    walkDirs(dir, visit);
+  }
+}
+
+function isCandidateProjectRoot(dir) {
+  return !!(
+    fs.existsSync(path.join(dir, 'package.json'))
+    || firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
+    || fs.existsSync(path.join(dir, 'src'))
+    || fs.existsSync(path.join(dir, 'app'))
+    || fs.existsSync(path.join(dir, 'pages'))
+    || fs.existsSync(path.join(dir, 'public'))
+  );
+}
+
+function isIgnoredWorkspaceDiscoveryDir(name) {
+  return name.startsWith('.') || WORKSPACE_DISCOVERY_IGNORED_DIRS.has(name);
+}
+
+function findTargetExample(repoRoot, projectRoot) {
+  const examples = [
+    'src/App.jsx',
+    'src/App.tsx',
+    'src/main.jsx',
+    'src/main.tsx',
+    'src/index.jsx',
+    'src/index.ts',
+    'app/page.tsx',
+    'pages/index.tsx',
+    'public/index.html',
+  ];
+  for (const rel of examples) {
+    const abs = path.join(projectRoot, rel);
+    if (fs.existsSync(abs)) return path.relative(repoRoot, abs).split(path.sep).join('/');
+  }
+  return path.relative(repoRoot, projectRoot).split(path.sep).join('/');
+}
+
+function resolveWorkspaceProjectRoot(repoRoot, targetDir) {
+  const rel = path.relative(repoRoot, targetDir);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return repoRoot;
+  const relSegments = rel.split(path.sep).filter(Boolean);
+  const patterns = readWorkspacePatterns(repoRoot);
+  const excluded = isExcludedByWorkspacePattern(relSegments, patterns);
+  if (!excluded) {
+    for (const pattern of patterns) {
+      const projectRoot = projectRootFromWorkspacePattern(repoRoot, relSegments, pattern);
+      if (projectRoot) return projectRoot;
+    }
+  }
+  if (excluded) return repoRoot;
+  if (
+    relSegments.length >= 2
+    && MONOREPO_FALLBACK_PROJECT_DIRS.includes(relSegments[0])
+  ) {
+    return path.join(repoRoot, relSegments[0], relSegments[1]);
+  }
+  const nearest = nearestProjectLikeRoot(repoRoot, targetDir);
+  if (nearest) return nearest;
+  return repoRoot;
+}
+
+function isExcludedByWorkspacePattern(relSegments, patterns) {
+  return patterns.some((rawPattern) => {
+    const pattern = normalizeWorkspacePattern(rawPattern);
+    if (!pattern.startsWith('!')) return false;
+    return workspacePatternMatchesRel(pattern.slice(1), relSegments);
+  });
+}
+
+function nearestProjectLikeRoot(repoRoot, targetDir) {
+  let dir = path.resolve(targetDir);
+  const stop = path.resolve(repoRoot);
+  while (dir && dir !== stop) {
+    if (
+      firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
+      || fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function nearestPackageRootBetween(repoRoot, targetDir, stopDir) {
+  let dir = path.resolve(targetDir);
+  const stop = path.resolve(stopDir || repoRoot);
+  const root = path.resolve(repoRoot);
+  while (dir && dir !== stop && isPathInsideOrEqual(dir, root)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function isPathInsideOrEqual(candidate, root) {
+  return path.resolve(candidate) === path.resolve(root) || isPathInside(candidate, root);
+}
+
+function workspacePatternMatchesRel(pattern, relSegments) {
+  const patternSegments = normalizeWorkspacePattern(pattern).split('/').filter(Boolean);
+  if (!patternSegments.length) return false;
+  if (patternSegments.includes('**')) {
+    const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
+    const literalPrefix = firstGlobIndex === -1
+      ? patternSegments
+      : patternSegments.slice(0, firstGlobIndex);
+    if (relSegments.length < literalPrefix.length + 1) return false;
+    for (let i = 0; i < literalPrefix.length; i++) {
+      if (!segmentMatches(literalPrefix[i], relSegments[i])) return false;
+    }
+    return true;
+  }
+  if (relSegments.length < patternSegments.length) return false;
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!segmentMatches(patternSegments[i], relSegments[i])) return false;
+  }
+  return true;
+}
+
+function readWorkspacePatterns(repoRoot) {
+  return [
+    ...readPackageWorkspaces(repoRoot),
+    ...readPnpmWorkspaces(repoRoot),
+    ...readLernaWorkspaces(repoRoot),
+  ].filter(Boolean);
+}
+
+function readPackageWorkspaces(repoRoot) {
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const workspaces = pkg?.workspaces;
+  if (Array.isArray(workspaces)) return workspaces;
+  if (Array.isArray(workspaces?.packages)) return workspaces.packages;
+  return [];
+}
+
+function readLernaWorkspaces(repoRoot) {
+  const lerna = readJson(path.join(repoRoot, 'lerna.json'));
+  return Array.isArray(lerna?.packages) ? lerna.packages : [];
+}
+
+function readPnpmWorkspaces(repoRoot) {
+  try {
+    const body = fs.readFileSync(path.join(repoRoot, 'pnpm-workspace.yaml'), 'utf-8');
+    const patterns = [];
+    let inPackages = false;
+    for (const line of body.split(/\r?\n/)) {
+      const trimmed = stripYamlInlineComment(line).trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const flowMatch = trimmed.match(/^packages:\s*\[(.*)\]\s*$/);
+      if (flowMatch) {
+        patterns.push(...parseYamlFlowList(flowMatch[1]));
+        inPackages = false;
+        continue;
+      }
+      if (/^packages:\s*$/.test(trimmed)) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages && /^[A-Za-z0-9_-]+:\s*/.test(trimmed)) break;
+      if (inPackages) {
+        const match = trimmed.match(/^-\s*(.+)$/);
+        if (match) patterns.push(unquoteYamlValue(match[1]));
+      }
+    }
+    return patterns;
+  } catch {
+    return [];
+  }
+}
+
+function stripYamlInlineComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if ((ch === '"' || ch === "'") && line[i - 1] !== '\\') {
+      quote = quote === ch ? null : quote || ch;
+      continue;
+    }
+    if (ch === '#' && !quote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseYamlFlowList(body) {
+  const items = [];
+  let quote = null;
+  let current = '';
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if ((ch === '"' || ch === "'") && body[i - 1] !== '\\') {
+      quote = quote === ch ? null : quote || ch;
+      current += ch;
+      continue;
+    }
+    if (ch === ',' && !quote) {
+      const value = unquoteYamlValue(current);
+      if (value) items.push(value);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  const value = unquoteYamlValue(current);
+  if (value) items.push(value);
+  return items;
+}
+
+function unquoteYamlValue(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^['"]|['"]$/g, '');
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function projectRootFromWorkspacePattern(repoRoot, relSegments, rawPattern) {
+  const pattern = normalizeWorkspacePattern(rawPattern);
+  if (!pattern || pattern.startsWith('!')) return null;
+  const patternSegments = pattern.split('/').filter(Boolean);
+  if (!patternSegments.length) return null;
+  if (patternSegments.includes('**')) {
+    return projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments);
+  }
+  if (relSegments.length < patternSegments.length) return null;
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!segmentMatches(patternSegments[i], relSegments[i])) return null;
+  }
+  return path.join(repoRoot, ...relSegments.slice(0, patternSegments.length));
+}
+
+function projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments) {
+  const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
+  const literalPrefix = firstGlobIndex === -1
+    ? patternSegments
+    : patternSegments.slice(0, firstGlobIndex);
+  if (relSegments.length < literalPrefix.length + 1) return null;
+  for (let i = 0; i < literalPrefix.length; i++) {
+    if (!segmentMatches(literalPrefix[i], relSegments[i])) return null;
+  }
+  const prefixDir = path.join(repoRoot, ...literalPrefix);
+  const targetDir = path.join(repoRoot, ...relSegments);
+  const packageRoot = nearestPackageRootBetween(repoRoot, targetDir, prefixDir);
+  if (packageRoot) return packageRoot;
+  return path.join(repoRoot, ...relSegments.slice(0, literalPrefix.length + 1));
+}
+
+function normalizeWorkspacePattern(pattern) {
+  return String(pattern || '')
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
+function segmentMatches(patternSegment, relSegment) {
+  if (patternSegment === '*') return true;
+  if (!patternSegment.includes('*')) return patternSegment === relSegment;
+  const re = new RegExp(`^${escapeRegExp(patternSegment).replace(/\\\*/g, '[^/]*')}$`);
+  return re.test(relSegment);
+}
+
 function firstExisting(dir, names) {
   for (const name of names) {
     const abs = path.join(dir, name);
@@ -89,24 +690,64 @@ function safeRead(p) {
   }
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Read the first non-empty line under a bare `## <heading>` section of
+ * PRODUCT.md (e.g. `## Register`, `## Platform`). Returns null when the
+ * section is absent. The heading match is exact (`\s*$`) so near-miss
+ * headings like `## Register guidelines` don't shadow the real field.
+ */
+export function extractSectionValue(product, heading) {
+  if (!product) return null;
+  const headingRe = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'i');
+  const lines = product.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (headingRe.test(lines[i].trim())) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const next = lines[j].trim();
+        // A new heading before any value means the section is empty.
+        if (/^#{1,6}\s/.test(next)) return null;
+        if (next) return next;
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
  * for a `## Register` section and reading the first non-empty line that
  * follows it. Returns null when the file is legacy / register-less.
  */
 export function extractRegister(product) {
-  if (!product) return null;
-  const lines = product.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Register\b/i.test(lines[i].trim())) {
-      for (let j = i + 1; j < lines.length; j++) {
-        const next = lines[j].trim();
-        if (!next) continue;
-        const word = next.toLowerCase();
-        if (word === 'brand' || word === 'product') return word;
-        return null;
-      }
-    }
+  const word = (extractSectionValue(product, 'Register') || '').toLowerCase();
+  return word === 'brand' || word === 'product' ? word : null;
+}
+
+/**
+ * Pull the platform (`web`, `ios`, `android`, or `adaptive`) out of PRODUCT.md
+ * by looking for a `## Platform` section and reading the first non-empty line
+ * that follows it. `adaptive` is for cross-platform apps (Flutter, React
+ * Native) that ship both iOS and Android from one codebase; a line that names
+ * both targets (e.g. `ios, android`) is also read as `adaptive`. Returns null
+ * when the file is legacy / platform-less, which the skill treats as `web`
+ * (the default the general rules already assume).
+ */
+export function extractPlatform(product) {
+  const value = (extractSectionValue(product, 'Platform') || '').toLowerCase();
+  if (!value) return null;
+  if (value === 'web' || value === 'ios' || value === 'android' || value === 'adaptive') return value;
+  // A short list naming both native targets (`ios, android`, `ios and
+  // android`) = adaptive. Only list separators and the two platform words may
+  // appear; anything else (prose, negations) is unrecognized and falls
+  // through to the CLI's WARNING path.
+  const tokens = value.split(/[\s,+&/]+/).filter(t => t && t !== 'and');
+  if (tokens.length >= 2 && tokens.every(t => t === 'ios' || t === 'android')
+    && tokens.includes('ios') && tokens.includes('android')) {
+    return 'adaptive';
   }
   return null;
 }
@@ -172,8 +813,8 @@ function buildUpdateDirective(localVersion, latestVersion) {
     `UPDATE_AVAILABLE: A newer Impeccable skill is available ` +
     `(installed v${localVersion}, latest v${latestVersion}). ` +
     `Before continuing, ask the user once: "A newer Impeccable (v${latestVersion}) is available. ` +
-    `Update now? It runs \`npx impeccable skills update\`." ` +
-    `If they agree, run \`npx impeccable skills update\` (the update applies to the next session, not this one). ` +
+    `Update now? It runs \`npx impeccable update\`." ` +
+    `If they agree, run \`npx impeccable update\` (the update applies to the next session, not this one). ` +
     `Either way, continue the current task without waiting, and do not raise this again.`
   );
 }
@@ -184,9 +825,23 @@ function buildUpdateDirective(localVersion, latestVersion) {
  * the user's home dir) and re-surfaces a given version at most once per week so
  * the agent never nags. Opt out entirely with IMPECCABLE_NO_UPDATE_CHECK=1.
  */
+// Read the unified config's top-level `updateCheck` (local overrides shared).
+// Inlined rather than importing hook-lib so the boot path stays lightweight.
+function updateCheckDisabledByConfig(cwd = process.cwd()) {
+  let value;
+  for (const name of ['config.json', 'config.local.json']) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', name), 'utf-8'));
+      if (raw && typeof raw === 'object' && typeof raw.updateCheck === 'boolean') value = raw.updateCheck;
+    } catch { /* missing or malformed: ignore */ }
+  }
+  return value === false;
+}
+
 async function computeUpdateDirective(now = Date.now()) {
   try {
     if (process.env.IMPECCABLE_NO_UPDATE_CHECK) return null;
+    if (updateCheckDisabledByConfig()) return null;
     const localVersion = readLocalSkillVersion();
     if (!localVersion) return null;
 
@@ -219,7 +874,24 @@ async function computeUpdateDirective(now = Date.now()) {
 }
 
 async function cli() {
-  const ctx = loadContext(process.cwd());
+  let cliOptions;
+  try {
+    cliOptions = parseCliOptions(process.argv.slice(2));
+  } catch (err) {
+    if (err?.name === 'TargetArgError') {
+      process.stderr.write(`${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const targetProvided = hasTargetOption(cliOptions);
+  const targetExists = targetProvided ? pathExistsForTarget(process.cwd(), cliOptions.targetPath) : null;
+  const selection = resolveTargetSelection(process.cwd(), cliOptions);
+  if (selection) {
+    process.stdout.write(buildTargetSelectionDirective(selection) + '\n');
+    process.exit(0);
+  }
+  const ctx = loadContext(process.cwd(), cliOptions);
   const updateDirective = await computeUpdateDirective();
 
   if (!ctx.hasProduct) {
@@ -227,9 +899,16 @@ async function cli() {
     // — cheap models miss the empty case more often than the explicit one.
     const parts = [
       'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
-      'Stop the current task, load reference/init.md, and follow its ' +
-      'instructions to write PRODUCT.md before resuming.',
+      'Follow SKILL.md Setup step 1: for `init`, `teach`, `craft`, `shape`, ' +
+      'or wording that clearly maps to a from-scratch build/shape flow, load ' +
+      'reference/init.md and write PRODUCT.md first; for any other (scoped) ' +
+      'command against existing code, proceed using the code as context and ' +
+      `offer \`${IMPECCABLE_COMMAND} init\` as a suggestion (do not block).`,
     ];
+    parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
+    if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
+      parts.push(buildMissingTargetDirective());
+    }
     if (updateDirective) parts.push(updateDirective);
     process.stdout.write(parts.join('\n\n---\n\n') + '\n');
     process.exit(0);
@@ -238,15 +917,93 @@ async function cli() {
   if (ctx.hasDesign) {
     parts.push(`# DESIGN.md\n\n${ctx.design.trim()}`);
   }
+  parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
+  if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
+    parts.push(buildMissingTargetDirective());
+  }
   const register = extractRegister(ctx.product);
   const next = register
     ? `NEXT STEP: This project's register is \`${register}\`. You MUST now read \`reference/${register}.md\` before producing any design output.`
     : `NEXT STEP: You MUST now read the matching register reference (\`reference/brand.md\` or \`reference/product.md\`) before producing any design output. Pick based on PRODUCT.md above.`;
   parts.push(next);
+  const platform = extractPlatform(ctx.product);
+  const nativeRefs =
+    platform === 'adaptive' ? ['ios', 'android'] : platform === 'ios' || platform === 'android' ? [platform] : [];
+  if (nativeRefs.length) {
+    const refList = nativeRefs.map(p => `\`reference/${p}.md\``).join(' and ');
+    const label = platform === 'adaptive' ? '`adaptive` (both iOS and Android)' : `\`${platform}\``;
+    parts.push(
+      `NEXT STEP: This project targets ${label}. Also read ${refList} for native conventions, in addition to the register reference.`,
+    );
+  } else if (!platform) {
+    // A `## Platform` section that names something we don't recognize (a
+    // toolchain like `flutter`, a typo) would otherwise silently fall back to
+    // web — the wrong default exactly when the user tried to say "native".
+    const rawPlatform = extractSectionValue(ctx.product, 'Platform');
+    if (rawPlatform) {
+      parts.push(
+        `WARNING: PRODUCT.md's \`## Platform\` value \`${rawPlatform}\` is not recognized; treating the project as \`web\`. Valid values are \`web\`, \`ios\`, \`android\`, or \`adaptive\` (cross-platform, ships both). If this project is native, fix the field (name the design language the app renders, not the toolchain) and surface it to the user.`,
+      );
+    }
+  }
   if (updateDirective) parts.push(updateDirective);
   process.stdout.write(parts.join('\n\n---\n\n') + '\n');
 }
 
+function parseCliOptions(args) {
+  return parseTargetOptions(args, { strict: true });
+}
+
+function hasTargetOption(options) {
+  return !!(options && typeof options.targetPath === 'string' && options.targetPath.trim());
+}
+
+function pathExistsForTarget(cwd, targetPath) {
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+  return fs.existsSync(abs);
+}
+
+function buildResolvedContextDirective(ctx, options, { targetExists = null } = {}) {
+  const targetPath = hasTargetOption(options) ? options.targetPath : null;
+  return `RESOLVED_CONTEXT:\n${JSON.stringify({
+    targetPath,
+    ...(targetPath ? { targetExists } : {}),
+    projectRoot: ctx.projectRoot,
+    repoRoot: ctx.repoRoot,
+    productPath: ctx.productPath,
+    designPath: ctx.designPath,
+  }, null, 2)}`;
+}
+
+function shouldWarnMissingTarget(ctx, targetProvided, targetExists = null) {
+  if (ctx.isMonorepo && targetProvided && targetExists === false) return true;
+  return !!(
+    ctx.isMonorepo
+    && (!targetProvided || targetExists === false)
+    && ctx.projectRoot
+    && ctx.repoRoot
+    && path.resolve(ctx.projectRoot) === path.resolve(ctx.repoRoot)
+  );
+}
+
+function buildMissingTargetDirective() {
+  const script = process.argv[1] || 'context.mjs';
+  return (
+    'MONOREPO_TARGET_REQUIRED: This is a monorepo and context.mjs ran without --target. ' +
+    'If the user named a file, route, or child app, do not answer from this output. ' +
+    `Rerun \`node ${script} --target <path>\` and answer from that run's RESOLVED_CONTEXT fields.`
+  );
+}
+
+function buildTargetSelectionDirective(selection) {
+  return (
+    `TARGET_SELECTION_REQUIRED:\n${JSON.stringify(selection, null, 2)}\n\n` +
+    'Show each app with its productStatus/productPath and designStatus/designPath so the user can see child overrides, inherited root files, fallback files, or missing files before choosing. ' +
+    'Ask the user which app Impeccable should use, then rerun Impeccable helper commands from that child app cwd using this same scripts directory. ' +
+    'Use `--target <path>` only as a fallback when changing cwd is not possible, or when the user explicitly named a file/path.'
+  );
+}
+
 // Run cli() only when this module is the entry point. Compare realpaths
 // rather than endsWith(): a loose suffix match also fires for unrelated
 // scripts like `load-context.mjs`, and realpath tolerates symlinked

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

@@ -2,11 +2,11 @@
 /**
  * Critique persistence helper.
  *
- * Each run of /impeccable critique writes a per-target snapshot to
+ * Each critique run writes a per-target snapshot to
  *   .impeccable/critique/<timestamp>__<slug>.md
  * with a small YAML frontmatter carrying the score + P0/P1 counts.
  *
- * /impeccable polish reads the latest matching snapshot at start as its
+ * The polish workflow reads the latest matching snapshot at start as its
  * fix backlog. No other skill auto-reads critique output.
  *
  * The slug is derived mechanically from the *resolved* primary artifact
@@ -28,7 +28,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { getCritiqueDir } from './impeccable-paths.mjs';
+import { getCritiqueDir } from './lib/impeccable-paths.mjs';
 
 const SLUG_MAX = 50;
 

.claude/skills/impeccable/scripts/detector/browser/injected/index.mjs

@@ -660,6 +660,7 @@ if (IS_BROWSER) {
       if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
       if (el.closest('[id^="impeccable-live-"]')) continue;
       if (el === document.body || el === document.documentElement) continue;
+      if (!isRenderedForBrowserRule(el)) continue;
 
       const tag = el.tagName.toLowerCase();
       const style = getComputedStyle(el);
@@ -1091,6 +1092,7 @@ if (IS_BROWSER) {
       return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'stale selector' };
     }
     if (!el) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing element' };
+    if (!isRenderedForBrowserRule(el)) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'hidden element' };
 
     const blockingReason = (candidate.reasons || []).find(reason =>
       reason === 'background-clip text' ||
@@ -1222,6 +1224,7 @@ if (IS_BROWSER) {
           category: ap ? ap.category : 'quality',
           severity: ap?.severity || 'warning',
           detail: f.detail || f.snippet,
+          ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
           description: ap ? ap.description : '',
         };
@@ -1258,10 +1261,203 @@ if (IS_BROWSER) {
     return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
   }
 
+  const DESIGN_COLOR_TOLERANCE = 6;
+  const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
+  const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
+
+  function normalizeBrowserFontName(value) {
+    return String(value || '')
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .replace(/\+/g, ' ')
+      .replace(/\s+/g, ' ')
+      .toLowerCase();
+  }
+
+  function browserPrimaryFont(stack) {
+    if (!stack || /var\(/i.test(stack)) return '';
+    return String(stack || '')
+      .split(',')
+      .map(normalizeBrowserFontName)
+      .find(font => font && !GENERIC_FONTS.has(font)) || '';
+  }
+
+  function browserDesignSystemConfig() {
+    const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
+    if (!raw?.present) return null;
+    const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
+    const allowedColors = (raw.allowedColors || [])
+      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
+      .map(color => ({ r: color.r, g: color.g, b: color.b }));
+    const allowedRadii = (raw.allowedRadii || [])
+      .map(Number)
+      .filter(px => Number.isFinite(px));
+    return {
+      present: true,
+      hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
+      allowedFonts,
+      hasColors: raw.hasColors === true && allowedColors.length > 0,
+      allowedColors,
+      hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
+      allowedRadii,
+      hasPillRadius: raw.hasPillRadius === true,
+    };
+  }
+
+  function browserColorsClose(a, b) {
+    if (!a || !b) return false;
+    return Math.max(
+      Math.abs(a.r - b.r),
+      Math.abs(a.g - b.g),
+      Math.abs(a.b - b.b),
+    ) <= DESIGN_COLOR_TOLERANCE;
+  }
+
+  function isBrowserDesignColorAllowed(raw, designSystem) {
+    if (!designSystem?.hasColors) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
+    if (text.includes('var(')) return true;
+    const parsed = parseAnyColor(text);
+    if (!parsed) return true;
+    if ((parsed.a ?? 1) <= 0.05) return true;
+    return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
+  }
+
+  function isBrowserTransparentCss(value) {
+    const text = String(value || '').trim().toLowerCase();
+    if (!text || text === 'transparent') return true;
+    const parsed = parseAnyColor(text);
+    return parsed ? (parsed.a ?? 1) <= 0.05 : false;
+  }
+
+  function isBrowserDesignRadiusAllowed(raw, designSystem) {
+    if (!designSystem?.hasRadii) return true;
+    const text = String(raw || '').trim().toLowerCase();
+    if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
+    if (text.includes('var(') || text.includes('%')) return true;
+    const px = resolveLengthPx(text, 16);
+    if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
+    if (designSystem.hasPillRadius && px >= 99) return true;
+    return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
+  }
+
+  function browserRadiusTokens(value) {
+    return String(value || '')
+      .replace(/\s*\/\s*/g, ' ')
+      .split(/\s+/)
+      .map(token => token.trim())
+      .filter(Boolean);
+  }
+
+  function browserHasDirectText(el) {
+    return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
+  }
+
+  function browserSampleText(el) {
+    const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
+    return text ? ` "${text.slice(0, 40)}"` : '';
+  }
+
+  function shouldSkipDesignElement(el) {
+    const tag = el.tagName?.toLowerCase?.() || '';
+    return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
+  }
+
+  function checkElementDesignSystemDOM(el, designSystem, seen) {
+    if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
+    const findings = [];
+    const tag = el.tagName?.toLowerCase?.() || 'unknown';
+    const style = getComputedStyle(el);
+
+    if (designSystem.hasFonts && browserHasDirectText(el)) {
+      const font = browserPrimaryFont(style.fontFamily || '');
+      if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
+          ignoreValue: font,
+        });
+      }
+    }
+
+    if (designSystem.hasColors) {
+      const colorChecks = [];
+      if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
+      if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
+      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
+        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
+          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
+        }
+      }
+      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
+
+      for (const [kind, raw] of colorChecks) {
+        const label = String(raw || '').trim().replace(/\s+/g, ' ');
+        if (isBrowserDesignColorAllowed(label, designSystem)) continue;
+        const key = `${kind}:${label}`;
+        if (seen.colors.has(key)) continue;
+        seen.colors.add(key);
+        findings.push({
+          type: 'design-system-color',
+          detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
+          ignoreValue: label,
+        });
+      }
+    }
+
+    if (designSystem.hasRadii) {
+      for (const token of browserRadiusTokens(style.borderRadius || '')) {
+        if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
+        if (seen.radii.has(token)) continue;
+        seen.radii.add(token);
+        findings.push({
+          type: 'design-system-radius',
+          detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
+          ignoreValue: token,
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  function decodeBrowserGoogleFamily(value) {
+    const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
+    try {
+      return decodeURIComponent(family);
+    } catch {
+      return family;
+    }
+  }
+
+  function checkBrowserDesignSystemSources(designSystem, seen) {
+    if (!designSystem?.hasFonts) return [];
+    const findings = [];
+    for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
+      const href = link.getAttribute('href') || '';
+      for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
+        const display = decodeBrowserGoogleFamily(match[1]);
+        const font = normalizeBrowserFontName(display);
+        if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
+        seen.fonts.add(font);
+        findings.push({
+          type: 'design-system-font',
+          detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
+          ignoreValue: display,
+        });
+      }
+    }
+    return findings;
+  }
+
   function collectBrowserFindings() {
     const groupMap = new Map();
     const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
     const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
+    const designSystem = browserDesignSystemConfig();
+    const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
     // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
     // real browser env (detector page, live overlay, extension) running every
     // check is free, so we always surface them; the gating is purely a CLI
@@ -1292,6 +1488,7 @@ if (IS_BROWSER) {
         ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
         ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
+        ...checkElementDesignSystemDOM(el, designSystem, designSeen),
       ].filter(f => _ruleOk(f.type));
 
       addBrowserFindings(groupMap, el, findings);
@@ -1308,6 +1505,13 @@ if (IS_BROWSER) {
 
     const pageLevelFindings = [];
 
+    const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
+      .filter(f => _ruleOk(f.type));
+    if (designSourceFindings.length > 0) {
+      pageLevelFindings.push(...designSourceFindings);
+      addBrowserFindings(groupMap, document.body, designSourceFindings);
+    }
+
     const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
     if (typoFindings.length > 0) {
       pageLevelFindings.push(...typoFindings);
@@ -1437,13 +1641,20 @@ if (IS_BROWSER) {
     return true;
   }
 
-  function postSerializedFindings(groupMap) {
+  function scanResultMeta(options = {}) {
+    const scanId = options.scanId;
+    if (typeof scanId !== 'string' && typeof scanId !== 'number') return {};
+    return { scanId: String(scanId) };
+  }
+
+  function postSerializedFindings(groupMap, options = {}) {
     if (!EXTENSION_MODE) return;
     const allFindings = browserFindingsFromMap(groupMap);
     window.postMessage({
       source: 'impeccable-results',
       findings: serializeFindings(allFindings),
       count: allFindings.length,
+      ...scanResultMeta(options),
     }, '*');
   }
 
@@ -1497,7 +1708,7 @@ if (IS_BROWSER) {
             rememberVisualContrastAnalysis(result);
             const added = addVisualContrastResult(groupMap, result, { decorate: true });
             if (added) {
-              postSerializedFindings(groupMap);
+              postSerializedFindings(groupMap, options);
               window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-resolved', {
                 detail: {
                   selector: result.selector,
@@ -1565,7 +1776,7 @@ if (IS_BROWSER) {
     overlayIndex = 0;
   }
 
-  function renderBrowserFindings(collected) {
+  function renderBrowserFindings(collected, options = {}) {
     const { allFindings, pageLevelFindings } = collected;
 
     for (const { el, findings } of allFindings) {
@@ -1585,6 +1796,7 @@ if (IS_BROWSER) {
         source: 'impeccable-results',
         findings: serializeFindings(allFindings),
         count: allFindings.length,
+        ...scanResultMeta(options),
       }, '*');
     }
 
@@ -1599,11 +1811,11 @@ if (IS_BROWSER) {
     clearOverlays();
     const generation = scanGeneration;
     const collected = collectBrowserFindings();
-    const allFindings = renderBrowserFindings(collected);
+    const allFindings = renderBrowserFindings(collected, options);
     if (shouldRunVisualContrast(options)) {
       addVisualContrastFindings(collected.groupMap, options, { decorate: true, generation })
         .then(() => {
-          if (generation === scanGeneration) postSerializedFindings(collected.groupMap);
+          if (generation === scanGeneration) postSerializedFindings(collected.groupMap, options);
         })
         .catch(err => {
           reportVisualContrastError(err);
@@ -1618,10 +1830,10 @@ if (IS_BROWSER) {
     if (shouldRunVisualContrast(options)) {
       const collected = await collectBrowserFindingsAsync(options, { generation, scheduleLazy: true });
       if (generation !== scanGeneration) return [];
-      return renderBrowserFindings(collected);
+      return renderBrowserFindings(collected, options);
     }
     lastVisualContrastAnalyses = [];
-    return renderBrowserFindings(collectBrowserFindings());
+    return renderBrowserFindings(collectBrowserFindings(), options);
   };
 
   const detect = function(options = {}) {