Release prep: skill v4.0.2

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.agents/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 ---
 
 This skill gives you the tools and permission to create design that earns to be called out-of-distribution craft: Whereas before, your design work would have been safe, timid and measured, you now approach every design task as a award-winning design director with impeccable understanding for what makes exceptional design work: production-grade code, peak creativity, a clear POV, deep understanding of the needs of the client and users, and exceptional craft.

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

@@ -15,10 +15,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -114,7 +114,7 @@ node .agents/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -139,7 +139,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .agents/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -156,7 +158,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -595,11 +597,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .agents/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -78,7 +78,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -100,4 +100,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

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

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

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

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({

.agents/skills/impeccable/scripts/live/generation-preflight.mjs

@@ -5,7 +5,32 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 
-export function buildGenerationPreflight(event, scriptsDir) {
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
   if (!event || event.type !== 'generate' || !event.id) return null;
 
   const isInsert = event.mode === 'insert';
@@ -14,13 +39,24 @@ export function buildGenerationPreflight(event, scriptsDir) {
 
   const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
   const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
   if (isInsert) args.push('--position', target.position);
   if (target.elementId) args.push('--element-id', target.elementId);
   if (target.classes) args.push('--classes', target.classes);
   if (target.tag) args.push('--tag', target.tag);
   if (target.text) args.push('--text', target.text);
   if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
-  return { script, args, mode: isInsert ? 'insert' : 'replace' };
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
 }
 
 /**
@@ -38,8 +74,9 @@ export async function runGenerationPreflight(event, {
   scriptsDir,
   execFileImpl = execFileAsync,
   timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
 } = {}) {
-  const command = buildGenerationPreflight(event, scriptsDir);
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
   if (!command) {
     return { ok: false, skipped: true, reason: 'insufficient_locator' };
   }
@@ -53,13 +90,23 @@ export async function runGenerationPreflight(event, {
     });
     const line = String(stdout).trim().split('\n').filter(Boolean).pop();
     if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
     return {
       ok: true,
       mode: command.mode,
       durationMs: performance.now() - startedAt,
-      scaffold: JSON.parse(line),
+      scaffold,
     };
   } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
     return {
       ok: false,
       mode: command.mode,

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

@@ -36,14 +36,14 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, 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));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +136,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from '../live-inject.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+function isManagedComponent(content) {
+  return String(content || '').includes('impeccable-live-tanstack');
+}
+
+function findRootRouteFile(cwd) {
+  for (const rel of ROOT_ROUTE_CANDIDATES) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function packageHasTanStackStart(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 START_PACKAGES.some((name) => Boolean(deps[name]));
+  } catch {
+    return false;
+  }
+}
+
+function relativeImportSpecifier(fromFile, toFile) {
+  const rel = path.posix.relative(
+    path.posix.dirname(fromFile.split(path.sep).join('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+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/serve-question.mjs

@@ -105,7 +105,7 @@ function printAnswer(raw) {
   try {
     const a = JSON.parse(raw);
     if (a.hero || a.board) {
-      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code (download local copies first when your harness only reads files); they set the craft bar the build must reach.");
+      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.");
     }
     if (a.optionId === 'canon') {
       console.log('CANON CHOSEN: the user picked the category standard on purpose. Ask once for two or three products this should sit alongside; their craft level becomes the quality bar. Execute the canon at full commitment, conventions embraced without irony or smuggled quirk.');

.claude-plugin/marketplace.json

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

.claude-plugin/plugin.json

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

.claude/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 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

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

@@ -13,10 +13,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -112,7 +112,7 @@ node .claude/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -137,7 +137,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .claude/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -154,7 +156,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -593,11 +595,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .claude/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -80,7 +80,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -102,4 +102,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

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

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

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

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({

.claude/skills/impeccable/scripts/live/generation-preflight.mjs

@@ -5,7 +5,32 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 
-export function buildGenerationPreflight(event, scriptsDir) {
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
   if (!event || event.type !== 'generate' || !event.id) return null;
 
   const isInsert = event.mode === 'insert';
@@ -14,13 +39,24 @@ export function buildGenerationPreflight(event, scriptsDir) {
 
   const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
   const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
   if (isInsert) args.push('--position', target.position);
   if (target.elementId) args.push('--element-id', target.elementId);
   if (target.classes) args.push('--classes', target.classes);
   if (target.tag) args.push('--tag', target.tag);
   if (target.text) args.push('--text', target.text);
   if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
-  return { script, args, mode: isInsert ? 'insert' : 'replace' };
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
 }
 
 /**
@@ -38,8 +74,9 @@ export async function runGenerationPreflight(event, {
   scriptsDir,
   execFileImpl = execFileAsync,
   timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
 } = {}) {
-  const command = buildGenerationPreflight(event, scriptsDir);
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
   if (!command) {
     return { ok: false, skipped: true, reason: 'insufficient_locator' };
   }
@@ -53,13 +90,23 @@ export async function runGenerationPreflight(event, {
     });
     const line = String(stdout).trim().split('\n').filter(Boolean).pop();
     if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
     return {
       ok: true,
       mode: command.mode,
       durationMs: performance.now() - startedAt,
-      scaffold: JSON.parse(line),
+      scaffold,
     };
   } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
     return {
       ok: false,
       mode: command.mode,

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

@@ -36,14 +36,14 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, 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));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +136,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from '../live-inject.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+function isManagedComponent(content) {
+  return String(content || '').includes('impeccable-live-tanstack');
+}
+
+function findRootRouteFile(cwd) {
+  for (const rel of ROOT_ROUTE_CANDIDATES) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function packageHasTanStackStart(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 START_PACKAGES.some((name) => Boolean(deps[name]));
+  } catch {
+    return false;
+  }
+}
+
+function relativeImportSpecifier(fromFile, toFile) {
+  const rel = path.posix.relative(
+    path.posix.dirname(fromFile.split(path.sep).join('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+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, '\\$&');
+}

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

@@ -105,7 +105,7 @@ function printAnswer(raw) {
   try {
     const a = JSON.parse(raw);
     if (a.hero || a.board) {
-      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code (download local copies first when your harness only reads files); they set the craft bar the build must reach.");
+      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.");
     }
     if (a.optionId === 'canon') {
       console.log('CANON CHOSEN: the user picked the category standard on purpose. Ask once for two or three products this should sit alongside; their craft level becomes the quality bar. Execute the canon at full commitment, conventions embraced without irony or smuggled quirk.');

.cursor/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 license: Apache 2.0
 ---
 

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

@@ -13,10 +13,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -112,7 +112,7 @@ node .cursor/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -137,7 +137,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .cursor/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -154,7 +156,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -593,11 +595,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .cursor/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -78,7 +78,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -100,4 +100,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

.cursor/skills/impeccable/scripts/context.mjs

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

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

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({

.cursor/skills/impeccable/scripts/live/generation-preflight.mjs

@@ -5,7 +5,32 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 
-export function buildGenerationPreflight(event, scriptsDir) {
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
   if (!event || event.type !== 'generate' || !event.id) return null;
 
   const isInsert = event.mode === 'insert';
@@ -14,13 +39,24 @@ export function buildGenerationPreflight(event, scriptsDir) {
 
   const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
   const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
   if (isInsert) args.push('--position', target.position);
   if (target.elementId) args.push('--element-id', target.elementId);
   if (target.classes) args.push('--classes', target.classes);
   if (target.tag) args.push('--tag', target.tag);
   if (target.text) args.push('--text', target.text);
   if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
-  return { script, args, mode: isInsert ? 'insert' : 'replace' };
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
 }
 
 /**
@@ -38,8 +74,9 @@ export async function runGenerationPreflight(event, {
   scriptsDir,
   execFileImpl = execFileAsync,
   timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
 } = {}) {
-  const command = buildGenerationPreflight(event, scriptsDir);
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
   if (!command) {
     return { ok: false, skipped: true, reason: 'insufficient_locator' };
   }
@@ -53,13 +90,23 @@ export async function runGenerationPreflight(event, {
     });
     const line = String(stdout).trim().split('\n').filter(Boolean).pop();
     if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
     return {
       ok: true,
       mode: command.mode,
       durationMs: performance.now() - startedAt,
-      scaffold: JSON.parse(line),
+      scaffold,
     };
   } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
     return {
       ok: false,
       mode: command.mode,

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

@@ -36,14 +36,14 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, 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));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +136,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from '../live-inject.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+function isManagedComponent(content) {
+  return String(content || '').includes('impeccable-live-tanstack');
+}
+
+function findRootRouteFile(cwd) {
+  for (const rel of ROOT_ROUTE_CANDIDATES) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function packageHasTanStackStart(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 START_PACKAGES.some((name) => Boolean(deps[name]));
+  } catch {
+    return false;
+  }
+}
+
+function relativeImportSpecifier(fromFile, toFile) {
+  const rel = path.posix.relative(
+    path.posix.dirname(fromFile.split(path.sep).join('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+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, '\\$&');
+}

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

@@ -105,7 +105,7 @@ function printAnswer(raw) {
   try {
     const a = JSON.parse(raw);
     if (a.hero || a.board) {
-      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code (download local copies first when your harness only reads files); they set the craft bar the build must reach.");
+      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.");
     }
     if (a.optionId === 'canon') {
       console.log('CANON CHOSEN: the user picked the category standard on purpose. Ask once for two or three products this should sit alongside; their craft level becomes the quality bar. Execute the canon at full commitment, conventions embraced without irony or smuggled quirk.');

.gemini/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 ---
 
 This skill gives you the tools and permission to create design that earns to be called out-of-distribution craft: Whereas before, your design work would have been safe, timid and measured, you now approach every design task as a award-winning design director with impeccable understanding for what makes exceptional design work: production-grade code, peak creativity, a clear POV, deep understanding of the needs of the client and users, and exceptional craft.

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

@@ -13,10 +13,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -112,7 +112,7 @@ node .gemini/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -137,7 +137,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .gemini/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -154,7 +156,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -593,11 +595,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .gemini/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -78,7 +78,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -100,4 +100,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

.gemini/skills/impeccable/scripts/context.mjs

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

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

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({

.gemini/skills/impeccable/scripts/live/generation-preflight.mjs

@@ -5,7 +5,32 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 
-export function buildGenerationPreflight(event, scriptsDir) {
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
   if (!event || event.type !== 'generate' || !event.id) return null;
 
   const isInsert = event.mode === 'insert';
@@ -14,13 +39,24 @@ export function buildGenerationPreflight(event, scriptsDir) {
 
   const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
   const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
   if (isInsert) args.push('--position', target.position);
   if (target.elementId) args.push('--element-id', target.elementId);
   if (target.classes) args.push('--classes', target.classes);
   if (target.tag) args.push('--tag', target.tag);
   if (target.text) args.push('--text', target.text);
   if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
-  return { script, args, mode: isInsert ? 'insert' : 'replace' };
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
 }
 
 /**
@@ -38,8 +74,9 @@ export async function runGenerationPreflight(event, {
   scriptsDir,
   execFileImpl = execFileAsync,
   timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
 } = {}) {
-  const command = buildGenerationPreflight(event, scriptsDir);
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
   if (!command) {
     return { ok: false, skipped: true, reason: 'insufficient_locator' };
   }
@@ -53,13 +90,23 @@ export async function runGenerationPreflight(event, {
     });
     const line = String(stdout).trim().split('\n').filter(Boolean).pop();
     if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
     return {
       ok: true,
       mode: command.mode,
       durationMs: performance.now() - startedAt,
-      scaffold: JSON.parse(line),
+      scaffold,
     };
   } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
     return {
       ok: false,
       mode: command.mode,

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

@@ -36,14 +36,14 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, 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));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +136,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from '../live-inject.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+function isManagedComponent(content) {
+  return String(content || '').includes('impeccable-live-tanstack');
+}
+
+function findRootRouteFile(cwd) {
+  for (const rel of ROOT_ROUTE_CANDIDATES) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function packageHasTanStackStart(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 START_PACKAGES.some((name) => Boolean(deps[name]));
+  } catch {
+    return false;
+  }
+}
+
+function relativeImportSpecifier(fromFile, toFile) {
+  const rel = path.posix.relative(
+    path.posix.dirname(fromFile.split(path.sep).join('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+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, '\\$&');
+}

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

@@ -105,7 +105,7 @@ function printAnswer(raw) {
   try {
     const a = JSON.parse(raw);
     if (a.hero || a.board) {
-      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code (download local copies first when your harness only reads files); they set the craft bar the build must reach.");
+      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.");
     }
     if (a.optionId === 'canon') {
       console.log('CANON CHOSEN: the user picked the category standard on purpose. Ask once for two or three products this should sit alongside; their craft level becomes the quality bar. Execute the canon at full commitment, conventions embraced without irony or smuggled quirk.');

.github/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 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

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

@@ -13,10 +13,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -112,7 +112,7 @@ node .github/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -137,7 +137,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .github/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -154,7 +156,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -593,11 +595,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .github/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -78,7 +78,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -100,4 +100,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

.github/skills/impeccable/scripts/context.mjs

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

.github/skills/impeccable/scripts/live.mjs

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({

.github/skills/impeccable/scripts/live/generation-preflight.mjs

@@ -5,7 +5,32 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const PREFLIGHT_TIMEOUT_MS = 15_000;
 
-export function buildGenerationPreflight(event, scriptsDir) {
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
   if (!event || event.type !== 'generate' || !event.id) return null;
 
   const isInsert = event.mode === 'insert';
@@ -14,13 +39,24 @@ export function buildGenerationPreflight(event, scriptsDir) {
 
   const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
   const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
   if (isInsert) args.push('--position', target.position);
   if (target.elementId) args.push('--element-id', target.elementId);
   if (target.classes) args.push('--classes', target.classes);
   if (target.tag) args.push('--tag', target.tag);
   if (target.text) args.push('--text', target.text);
   if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
-  return { script, args, mode: isInsert ? 'insert' : 'replace' };
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
 }
 
 /**
@@ -38,8 +74,9 @@ export async function runGenerationPreflight(event, {
   scriptsDir,
   execFileImpl = execFileAsync,
   timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
 } = {}) {
-  const command = buildGenerationPreflight(event, scriptsDir);
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
   if (!command) {
     return { ok: false, skipped: true, reason: 'insufficient_locator' };
   }
@@ -53,13 +90,23 @@ export async function runGenerationPreflight(event, {
     });
     const line = String(stdout).trim().split('\n').filter(Boolean).pop();
     if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
     return {
       ok: true,
       mode: command.mode,
       durationMs: performance.now() - startedAt,
-      scaffold: JSON.parse(line),
+      scaffold,
     };
   } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
     return {
       ok: false,
       mode: command.mode,

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

@@ -36,14 +36,14 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, 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));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
@@ -136,18 +136,20 @@ export function unpatchSvelteLayout(content) {
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from '../live-inject.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+function isManagedComponent(content) {
+  return String(content || '').includes('impeccable-live-tanstack');
+}
+
+function findRootRouteFile(cwd) {
+  for (const rel of ROOT_ROUTE_CANDIDATES) {
+    if (fs.existsSync(path.join(cwd, rel))) return rel;
+  }
+  return null;
+}
+
+function packageHasTanStackStart(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 START_PACKAGES.some((name) => Boolean(deps[name]));
+  } catch {
+    return false;
+  }
+}
+
+function relativeImportSpecifier(fromFile, toFile) {
+  const rel = path.posix.relative(
+    path.posix.dirname(fromFile.split(path.sep).join('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+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, '\\$&');
+}

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

@@ -105,7 +105,7 @@ function printAnswer(raw) {
   try {
     const a = JSON.parse(raw);
     if (a.hero || a.board) {
-      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code (download local copies first when your harness only reads files); they set the craft bar the build must reach.");
+      console.log("CHOSEN CARD: open the chosen world's board and hero images now, before any code. When your harness only reads files, or runs sandboxed, download them INTO the workspace and open the relative path; a sandboxed viewer rejects absolute paths outside it. They set the craft bar the build must reach.");
     }
     if (a.optionId === 'canon') {
       console.log('CANON CHOSEN: the user picked the category standard on purpose. Ask once for two or three products this should sit alongside; their craft level becomes the quality bar. Execute the canon at full commitment, conventions embraced without irony or smuggled quirk.');

.grok/skills/impeccable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.0.1
+version: 4.0.2
 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

.grok/skills/impeccable/reference/live.md

@@ -13,10 +13,10 @@ Execute in order. No step skipped, no step reordered.
 3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
 
 The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
-4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead.
+4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
 5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
 6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
-7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart.
+7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
 8. On `exit`: run the cleanup at the bottom.
 
 Harness policy:
@@ -112,7 +112,7 @@ node .grok/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT
 - `--position` ← `event.insert.position` (`before` | `after`)
 - Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
 
-The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
+The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
 
 For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
 
@@ -137,7 +137,9 @@ Reading annotations precisely:
 
 ### 2. Wrap the element
 
-When `event.scaffold` is present, the local helper already found and wrapped the source before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
+
+**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
 
 ```bash
 node .grok/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
@@ -154,7 +156,7 @@ The helper searches ID first, then classes, then tag + class combo. If `event.pa
 
 If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
 
-Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`.
+Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
 
 For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
 
@@ -593,11 +595,15 @@ Schema:
 | Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
 | Nuxt | `["app.vue"]` | `</body>` | `html` |
 | Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
 | Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
 | Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
 
 Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
 
+**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
+
 For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
 
 For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.

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

@@ -48,7 +48,7 @@ The script assigns which structure gets built: your top-ranked structure is what
 
 The standing exit: every direction round offers one quiet, permanent alternative, the category standard, played straight. It is the user's door, never yours: never recommend it, never weigh it against the roll, never let it soften the dealt directions; the counterweights bind the unchosen default, not the chosen one. When the user takes it, in the canon action, a safer-steer, or plain words asking for the familiar or competitor-like path, convention becomes the commitment: ask once for two or three products this should sit alongside, make their craft level the bar, and execute the canon at full fidelity, without irony or smuggled quirk. A standing preference gets recorded as a brand commitment in PRODUCT.md. Re-roll eliminates every direction already shown, grounded and challenger alike; after two consecutive re-rolls, ask what quality is missing. You may re-roll on your own only on named factual grounds, when the assigned direction cannot carry the product's truth or task; taste is never grounds. The user may re-roll freely, and a user- or brief-pinned direction beats the roll, always. Present the decision visually: write an options payload with the assigned direction leading, the dealt challengers as alternates carrying their QUALITY BAR cards, and re-roll, steer, plus canon enabled; a degraded roll with no challengers still uses the page, as a single text-only card with re-roll. Run `node .grok/skills/impeccable/scripts/serve-question.mjs --start --payload <file>` (run it with `--schema` first for the exact payload shape). It daemonizes, prints the page URL and a key, and exits immediately; now open that URL for the user, in-app browser first, then the system opener, then showing the URL. Collect the choice with `--wait --key <key>`, repeating while it exits 3; the ANSWER prints as JSON. Exit 4 means the page was closed without an answer: re-present once through the structured question tool, and with no answer there either, proceed unattended with the assigned direction and state the assumptions. A harness that can leave a shell blocked in the background may instead run the script without `--start` and let it auto-open and block. Only a session where no browser can open at all, headless, CI, an eval worker, a remote shell with no display, puts the same decision through the structured question tool instead; the script self-detects these environments and exits 2 with that advice, so treat exit 2 as this fallback, never as an error to retry.
 
-Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (download to a temp file when the harness only reads local images). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
+Catalog worlds are working systems, not mood references. When one survives, carry its palette and material, type and composition, topology, controls and state, and responsive rules into the product. When the source is itself an interface language, commit to its native grammar across navigation, content, controls, and states. Open the QUALITY BAR board and hero for the world you build the moment the choice lands, even if you viewed another card earlier; the ANSWER line names the chosen card's images for exactly this reason (when the harness only reads files or runs sandboxed, download them into the workspace and open the relative path; sandboxed viewers reject absolute paths outside it). They set the craft level the build must reach, a rendered reference's finish, commitment, and art direction, never the composition; your surface serves this product.
 
 Every direction the roll can land on must already be viable: every relationship and claim it visualizes true, a real palette and component family, a distinctive composition with one product-specific experience, workable at full-surface scale within the available assets, tools, and performance budget. A candidate that fails on truth is replaced before the roll, never rescued by it. Truth binds claims, not demonstrations: in greenfield work, author whatever illustrative material the concept needs at full fidelity, label it synthetic wherever a visitor could mistake it for the real thing, and hand the user the list of what to replace with real material. What stays uninventable are commercial and factual claims: prices, customers, benchmarks, endpoints, capabilities the product does not have. Refusing a bold direction because its demonstration data does not exist yet is the timidity reflex wearing honesty's clothes.
 
@@ -78,7 +78,7 @@ If the work establishes durable strategy for a route or artifact, read its exist
 
 Keep the brief small: scope and visitor mode; audience, job, action/task, proof/content, and constraints; chosen direction and memorable moment; unresolved decisions. Do not copy global product truth or DESIGN.md tokens into it.
 
-Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work.
+Whenever any image generation is available, a harness-native tool or the API fallback context.mjs reports, the locked direction is visualized before it is built, never skipped: load [visualize.md](visualize.md) and follow it, three compositional options rendered and put before the user for approval. This step is proven to produce the most compositional and ambitious work. One exception: under a hard harness turn or budget cap the full flow cannot fit, the shipped page outranks optional imagery; cut to one comp or skip generation, say so, and make certain the build lands.
 
 For `shape`, return the selected direction to [shape.md](shape.md) and stop before persistence or implementation.
 
@@ -100,4 +100,4 @@ Preserve semantics, accessibility, performance, responsiveness, project conventi
 
 Inspect desktop and mobile, critique the render against the user's request, the direction contract, and DESIGN.md, fix material gaps, and re-inspect. On a Persuade surface, verify the mode did its job: a first-time visitor should know what this is, why it matters, and what to do within seconds, in the form's own vocabulary. After a first implementation of a new world, update DESIGN.md with the exact tokens and behaviors that survived the build.
 
-Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread; a harness with no subagents runs it as its own fresh pass, after stepping fully out of the build context. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.
+Spawn the shipped finish reviewer, `impeccable-finish-reviewer` (`impeccable_finish_reviewer` in codex), and give it the original request, confirmed answers, the artifact path, its direction contract, DESIGN.md, existing hook findings, and the QUALITY BAR card and approved comp paths. This review never runs inside the build thread. Only a harness whose tool surface has no subagent capability at all substitutes a fresh in-thread pass after stepping fully out of the build context, and a substituted review is disclosed in one line at finish, never silently. The reviewer's first check is persistence: on a new or replacement world, PRODUCT.md and DESIGN.md exist and DESIGN.md matches the built world; a missing file fails the review before any craft point is scored. Its second check is the ceiling: against the chosen world's QUALITY BAR card and the approved comp, name the native devices the build left unused, frame, depth, lettering, ornament density; floor rigor is very good at disguising an unreached card. Then ask for a short list of material fixes, promise by promise against the contract, apply them, and finish. Do not run a second detector.

.grok/skills/impeccable/scripts/context.mjs

@@ -1142,6 +1142,7 @@ async function cli() {
     appendDetectorFallback(parts, ctx);
     appendImageGenDirective(parts);
     appendAutonomyCounterDirective(parts);
+    appendSubagentAuthorizationDirective(parts);
     if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
       parts.push(buildMissingTargetDirective());
     }
@@ -1159,6 +1160,7 @@ async function cli() {
   appendDetectorFallback(parts, ctx);
   appendImageGenDirective(parts);
   appendAutonomyCounterDirective(parts);
+  appendSubagentAuthorizationDirective(parts);
   if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
     parts.push(buildMissingTargetDirective());
   }
@@ -1296,6 +1298,20 @@ function appendAutonomyCounterDirective(parts) {
   ].join(' '));
 }
 
+// Same class of harness default as the autonomy directive: some harnesses gate
+// agent-tool use on an explicit user request, which silently disables every
+// shipped subagent the skill's flows depend on (finish reviewer, asset
+// producer, manual-edit applier, critique panels). Observed live: the model
+// resolved the conflict against the skill without telling the user.
+function appendSubagentAuthorizationDirective(parts) {
+  parts.push([
+    'SUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request,',
+    "the user's invocation of this skill is that request for the skill's shipped subagents;",
+    'spawn them where a reference file directs, without re-asking.',
+    'Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.',
+  ].join(' '));
+}
+
 // reference/craft-floor.md carries the detector-blind reflexes on every build,
 // so the only gap left here is the mechanical pass. A hook covers it, per-edit
 // or Stop; a session without one has to run the detector by hand. The detector

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

@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
 const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
 const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
 
+// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
+// analyzer and the browser DOM check so both fire on the same saturation
+// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
+// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
+// text. A long article that uses a few em-dashes is left alone; a short,
+// dash-per-clause page is not.
+const EM_DASH_FLOOR = 8;
+const EM_DASH_CHARS_PER_DASH = 500;
+
 // Serif faces that show up in italic-display heroes. The rule also fires when
 // the primary face is unknown but the stack ends in the generic `serif` token,
 // which catches custom/private faces with a serif fallback.
@@ -315,9 +324,14 @@ const ANTIPATTERNS = [
   {
     id: 'em-dash-overuse',
     category: 'slop',
+    // Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
+    // rather than a failure. It fires only on the AI saturation pattern, not on
+    // ordinary prose. Advisory findings are surfaced separately, never counted
+    // as failures, and skipped by the design hook unless a project opts in.
+    advisory: true,
     name: 'Em-dash overuse',
     description:
-      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
+      'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
     skillSection: 'Copy',
     skillGuideline: 'no em dashes',
   },
@@ -507,6 +521,14 @@ const ANTIPATTERNS = [
     description:
       'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
   },
+  {
+    id: 'undersized-ui-text',
+    category: 'quality',
+    scopes: ['type'],
+    name: 'Undersized functional text',
+    description:
+      'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
+  },
   {
     id: 'all-caps-body',
     category: 'quality',
@@ -3367,6 +3389,33 @@ function checkNumberedSectionLabelsDOM() {
   return checkNumberedSectionLabels({ candidates });
 }
 
+// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
+// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
+// two gates (absolute floor + density) so a long article using a few dashes is
+// left alone while a short, dash-per-clause page is flagged. Operates on
+// already-rendered text, so no HTML-entity decoding is needed (the browser has
+// resolved `—` to the literal glyph). Exported for jsdom unit tests.
+function checkEmDashOveruse(text) {
+  const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
+  let count = 0;
+  const re = /[—]|--(?=\S)/g;
+  while (re.exec(body) !== null) count++;
+  if (count < EM_DASH_FLOOR) return [];
+  if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
+  return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
+}
+
+function checkEmDashOveruseDOM() {
+  const body = document.body;
+  if (!body) return [];
+  // innerText reflects rendered, visible text; fall back to textContent for
+  // engines (jsdom) that don't compute innerText.
+  const text = typeof body.innerText === 'string' && body.innerText
+    ? body.innerText
+    : (body.textContent || '');
+  return checkEmDashOveruse(text);
+}
+
 function checkElementMotionDOM(el) {
   const tag = el.tagName.toLowerCase();
   if (SAFE_TAGS.has(tag)) return [];
@@ -3594,6 +3643,27 @@ function textDescendantsFlushSides(el, rect) {
   return flush;
 }
 
+// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
+// floors: it is never rendered, so its size is irrelevant. Detect the two
+// standard idioms — a known sr-only class on the element or an ancestor, and
+// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
+// browser (computed styles).
+const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
+function isVisuallyHidden(el, style) {
+  if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
+  const pos = style.position || '';
+  if (pos === 'absolute' || pos === 'fixed') {
+    const clip = style.clip || '';
+    const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
+    if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
+    const w = parseFloat(style.width);
+    const h = parseFloat(style.height);
+    const overflow = style.overflow || '';
+    if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
+  }
+  return false;
+}
+
 // 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
@@ -3878,6 +3948,60 @@ function checkQuality(opts) {
     }
   }
 
+  // --- Undersized functional / UI text ---
+  // Complements `tiny-text` above, which owns long body copy and deliberately
+  // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
+  // uppercase micro-labels). This rule targets exactly that blind spot: the
+  // interactive and short content-bearing text — nav items, buttons, labels,
+  // table cells, meta rows, timecodes — shipped below an 11px floor.
+  //
+  // The live failure it closes: a build shipped its entire furniture layer at
+  // 8px, and the design hook waved it through because 8px had been added to
+  // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
+  // legibility one, so this rule ignores the design system entirely — a value
+  // on the ramp is still flagged.
+  //
+  // Floors: 11px for anything functional. The floor holds inside a footer;
+  // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
+  // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
+  // Uppercase letterspaced micro-labels are still functional — not exempt.
+  {
+    const directText = [...el.childNodes]
+      .filter(n => n.nodeType === 3)
+      .map(n => n.textContent || '')
+      .join('')
+      .replace(/\s+/g, ' ')
+      .trim();
+    const dtLen = directText.length;
+    const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
+    const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
+    // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
+    // text that computes at or above the floor never reaches here. The browser
+    // adapter additionally catches values only resolvable with real layout
+    // (e.g. viewport-relative units, cascade winners set in linked sheets).
+    if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
+      const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
+      const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
+      if (!isExemptContext && !isVisuallyHidden(el, style)) {
+        const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
+        const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
+        const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
+        const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
+        const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
+        const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
+        const floor = (!isInteractive && isSmallprint) ? 10 : 11;
+        // Fire on functional text only: interactive, structural furniture, or
+        // any short (<=20-char) run — the label / meta / timecode shape. Long
+        // non-furniture body copy stays with `tiny-text`, so the two rules
+        // never double-flag the same element.
+        if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
+          const excerpt = directText.slice(0, 40);
+          findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
+        }
+      }
+    }
+  }
+
   // --- All-caps body text ---
   if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
     if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -7066,6 +7190,10 @@ if (IS_BROWSER) {
           type: f.type || f.id,
           category: ap ? ap.category : 'quality',
           severity: f.severity || ap?.severity || 'warning',
+          // Advisory findings (em-dash overuse, etc.) are surfaced but never
+          // treated as failures; carry the flag so the overlay/extension can
+          // render them with the mildest affordance and consumers can filter.
+          advisory: (ap && ap.advisory === true) || f.advisory === true,
           detail: f.detail || f.snippet,
           ignoreValue: f.ignoreValue || f.value || '',
           name: ap ? ap.name : (f.type || f.id),
@@ -7384,6 +7512,17 @@ if (IS_BROWSER) {
       addBrowserFindings(groupMap, document.body, repeatedTextFindings);
     }
 
+    // Em-dash overuse (advisory): browser parity with the static/regex path.
+    // Reads rendered body text so it catches dashes written as HTML entities.
+    // serializeFindings stamps the advisory flag from the registry.
+    const emDashFindings = checkEmDashOveruseDOM()
+      .map(f => ({ type: f.id, detail: f.snippet }))
+      .filter(f => _ruleOk(f.type));
+    if (emDashFindings.length > 0) {
+      pageLevelFindings.push(...emDashFindings);
+      addBrowserFindings(groupMap, document.body, emDashFindings);
+    }
+
     const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
     for (const f of layoutFindings) {
       const el = f.el || document.body;

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

@@ -1960,6 +1960,20 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
       return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
     }
 
+    // Claude Code's Stop-hook contract: `stop_hook_active` is true when this
+    // hook is being re-invoked only because a prior invocation kept the turn
+    // alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
+    // re-blocking now would loop until Claude Code's consecutive-block cap
+    // force-ends the turn (issue #400). The prior fire already surfaced the
+    // findings; whether to act on them is the agent's call. Exit fast with no
+    // output before any scan. Only Claude Code sends this field; other
+    // harnesses omit it, so the strict `=== true` is a no-op for them. This
+    // guard makes the loop impossible regardless of the finding cache key's
+    // line-number sensitivity (out of scope here; see findingCacheKey).
+    if (event.stop_hook_active === true) {
+      return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
+    }
+
     const harness = resolveHarness(env, event);
     audit.harness = harness;
 

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

@@ -215,12 +215,57 @@ function collectHookCommands(value, out = []) {
   return out;
 }
 
-// Pull the script path out of a hook command line. Commands look like
-// `node .claude/skills/impeccable/scripts/hook.mjs` and may be quoted or carry
-// trailing arguments.
-function hookScriptPathFrom(command) {
-  const match = String(command).match(/(\S*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
-  return match ? match[1].replace(/^['"]|['"]$/g, '') : null;
+const HOOK_MARKER = /skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs/;
+
+// Pull the script-path token out of a hook command line, placeholders intact.
+// The forms our manifests ship:
+//   * bare:            node "${CLAUDE_PROJECT_DIR}/.../hook.mjs"
+//   * bundle-relative: node ".agents/.../hook.mjs"
+//   * legacy unquoted: node .claude/.../hook.mjs
+//   * guarded (#399):  [ ! -f "PATH" ] || node "PATH"   (PATH twice, identical)
+//   * absolute:        node "/Users/.../hook.mjs"        (user-level installs)
+//   * github portable: node "$(git rev-parse --show-toplevel)/.../hook.mjs"
+// A quoted path wins; the guard's two occurrences are identical, so the first
+// quoted match is the path. Otherwise fall back to the whitespace/metachar-
+// delimited token that ends at the marker, so we don't absorb `node`, `[`, `!`
+// or `||`. Returns the token verbatim; resolution happens separately.
+function hookScriptTokenFrom(command) {
+  const str = String(command);
+  if (!HOOK_MARKER.test(str)) return null;
+  const quoted = str.match(/"([^"]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)"/);
+  if (quoted) return quoted[1];
+  const bare = str.match(/([^\s"'|&;()]*skills\/impeccable\/scripts\/hook(?:-before-edit)?\.mjs)/);
+  return bare ? bare[1] : null;
+}
+
+// Resolve a script token to an absolute path the doctor can existsSync, or null
+// when the doctor cannot know where it points — in which case the caller must
+// NOT report it missing (a doctor never asserts a negative it cannot verify).
+//
+// Per-placeholder policy, mirroring what each runtime actually expands:
+//   ${CLAUDE_PROJECT_DIR}  → the project root being scanned. This is exactly the
+//                            runtime mapping (Claude Code sets it to the project
+//                            dir at hook time), so we EXPAND it against `root`.
+//                            Not doing so was the #402 bug: the literal
+//                            `${CLAUDE_PROJECT_DIR}/...` string never exists.
+//   ${CLAUDE_PLUGIN_ROOT}  → plugin-package install dir, set by the harness to
+//   ${PLUGIN_ROOT}           wherever the plugin/codex/grok bundle was unpacked
+//   ${GROK_PLUGIN_ROOT}      (grok aliases CLAUDE_PLUGIN_ROOT). The doctor has no
+//                            way to know that location → SKIP (return null).
+//   $(...) / backticks     → command substitution, e.g. GitHub's
+//                            `$(git rev-parse --show-toplevel)`. Not statically
+//                            resolvable → SKIP.
+//   any other ${VAR}/$VAR  → unknown to the doctor → SKIP.
+// A token with no placeholder is a literal path: absolute as-is, else relative
+// to `root`.
+function resolveHookScriptPath(token, root) {
+  if (!token) return null;
+  // Command substitution or backtick expansion we can't evaluate.
+  if (token.includes('$(') || token.includes('`')) return null;
+  const expanded = token.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, root);
+  // Any placeholder or shell variable still present is one we can't map.
+  if (/\$\{[^}]*\}|\$[A-Za-z_]/.test(expanded)) return null;
+  return path.isAbsolute(expanded) ? expanded : path.join(root, expanded);
 }
 
 /**
@@ -246,9 +291,11 @@ export function checkHookInstallation({ projectRoot, repoRoot, providerId }) {
       installedAt = toRelative(manifestPath, projectRoot || root);
 
       const broken = commands.filter((command) => {
-        const scriptPath = hookScriptPathFrom(command);
-        if (!scriptPath) return false;
-        const abs = path.isAbsolute(scriptPath) ? scriptPath : path.join(root, scriptPath);
+        const token = hookScriptTokenFrom(command);
+        if (!token) return false;
+        const abs = resolveHookScriptPath(token, root);
+        // Unresolvable placeholder or command substitution: never assert missing.
+        if (!abs) return false;
         return !fs.existsSync(abs);
       });
       if (broken.length) {

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

@@ -127,6 +127,41 @@
   let arrivedVariants = 0;
   let visibleVariant = 0;
   let generationPhase = null;
+  // Ascending order of the agent-generation lifecycle. The visible progress bar
+  // must never regress: a `browser_resumed`/behind checkpoint re-broadcasts an
+  // earlier phase (the server regresses the snapshot phase to `generating` on a
+  // behind checkpoint), and without this the bar jumps backward mid-generation.
+  // Unranked phases (params sidecar flow, unknown values) always pass so we
+  // never block a phase we do not model.
+  const PHASE_RANK = {
+    queued: 0,
+    picked_up: 1,
+    scaffolding: 2,
+    scaffold_fallback: 3,
+    source_ready: 4,
+    generation_ready: 5,
+    generating: 5,
+    variants_progress: 5,
+    first_variant_generating: 6,
+    first_variant_validating: 7,
+    first_reviewable: 8,
+    remaining_variants_generating: 9,
+    remaining_variants_validating: 10,
+    second_reviewable: 11,
+    all_variants_ready: 12,
+    variants_ready: 12,
+    variant_parameters_generating: 13,
+    variant_parameters_validating: 14,
+    parameters_ready: 15,
+  };
+  function shouldAdvancePhase(current, next) {
+    if (!next || next === current) return false;
+    const nextRank = PHASE_RANK[next];
+    const currentRank = PHASE_RANK[current];
+    // Only block a known-lower phase from overwriting a known-higher one.
+    if (nextRank === undefined || currentRank === undefined) return true;
+    return nextRank >= currentRank;
+  }
   let parameterGenerationState = 'idle';
   let parameterReadyAnnouncedSession = null;
   let svelteComponentSession = null;
@@ -6347,7 +6382,10 @@
           break;
         case 'agent_phase':
           if (msg.id === currentSessionId && (state === 'GENERATING' || state === 'CYCLING')) {
-            generationPhase = msg.phase || generationPhase;
+            // Advance the visible phase monotonically. A behind/resumed
+            // checkpoint may carry an earlier phase for internal bookkeeping,
+            // but the bar must not move backward.
+            if (shouldAdvancePhase(generationPhase, msg.phase)) generationPhase = msg.phase;
             if (msg.phase === 'variant_parameters_generating' || msg.phase === 'variant_parameters_validating') {
               parameterGenerationState = 'loading';
             }
@@ -6363,22 +6401,19 @@
             if (msg.publicationKind === 'params') parameterGenerationState = 'loading';
             rememberSessionFileMeta(msg);
             if (isFrameworkComponentPreviewMode(msg.previewMode) && msg.previewFile) {
+              // Component-preview (Svelte/Vue) progressive delivery: the browser
+              // mounts compiled components, so there is no framework-owned DOM
+              // to race. Keep streaming each checkpoint into the preview.
               injectSvelteComponentsFromManifest(msg.previewFile, msg.id);
-            } else if ((msg.previewMode === 'source' || !msg.previewMode) && (msg.previewFile || msg.file)) {
-              // Give normal framework HMR the first chance to reconcile its
-              // own managed tree. Nuxt route-module HMR can skip intermediate
-              // revisions, so fall back to source injection only when the
-              // advertised progress still has not appeared after a short
-              // settle. Immediate injection races React/Vue ownership and can
-              // trigger removeChild errors on the next HMR commit.
-              const targetArrived = Number(msg.arrivedVariants) || 1;
-              setTimeout(() => {
-                if (msg.id !== currentSessionId) return;
-                if (state !== 'GENERATING' && state !== 'CYCLING') return;
-                if (msg.publicationKind !== 'params' && arrivedVariants >= targetArrived) return;
-                injectVariantsFromSource(msg.previewFile || msg.file, msg.id);
-              }, 150);
             }
+            // Source-preview targets: do NOT source-inject per checkpoint.
+            // Immediate injection races framework (React/Vue) ownership mid-
+            // generation and triggers removeChild errors on the next HMR
+            // commit. Let HMR own reconciliation while variants stream in;
+            // source injection runs only on the final `done` (which keeps its
+            // 750ms settle + retry ladder for non-HMR harnesses like Cursor).
+            // The visible progress count still advances from the variant
+            // MutationObserver as HMR lands each variant.
           }
           break;
         case 'steer_done':
@@ -6489,7 +6524,7 @@
   function handleServerLost() {
     const recoveryState = currentSessionId ? state : 'IDLE';
     if (state === 'GENERATING' || state === 'CYCLING' || state === 'SAVING') {
-      showToast('Live server disconnected. Session ended.', 5000);
+      showToast('Live server connection lost. Your session is saved; reopen this page or restart live-poll.mjs to continue.', 6000);
     }
     hideBar();
     hideHighlight();

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

@@ -8,9 +8,14 @@
  * with zero LLM involvement.
  *
  * Usage:
- *   node live-inject.mjs --port PORT   # Insert the live script tag
- *   node live-inject.mjs --remove      # Remove the live script tag
- *   node live-inject.mjs --check       # Check whether live config exists
+ *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
+ *   node live-inject.mjs --remove                     # Remove the live script tag
+ *   node live-inject.mjs --check                      # Check whether live config exists
+ *
+ * When --token is supplied, it is appended to the /live.js src as `?token=...`
+ * so the server's token-gated /live.js handler will serve the bundle. Omitting
+ * the token yields a bare `/live.js` src (legacy behavior; the server returns
+ * 401 for it under the current gate).
  */
 
 import fs from 'node:fs';
@@ -22,6 +27,11 @@ import {
   detectSvelteKitProject,
   removeSvelteKitLiveAdapter,
 } from './live/sveltekit-adapter.mjs';
+import {
+  applyTanStackLiveAdapter,
+  detectTanStackStartProject,
+  removeTanStackLiveAdapter,
+} from './live/tanstack-adapter.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
@@ -124,6 +134,7 @@ Output (JSON):
   const resolvedFiles = resolveFiles(process.cwd(), config);
   const svelteKit = detectSvelteKitProject(process.cwd(), config);
   const nuxt = detectNuxtProject(process.cwd());
+  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
 
   if (args.includes('--remove')) {
     if (svelteKit) {
@@ -131,6 +142,12 @@ Output (JSON):
       console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
       return;
     }
+    if (tanstack) {
+      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
+      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
+      if (adapterResult.error) process.exitCode = 1;
+      return;
+    }
     if (nuxt) {
       const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
       console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
@@ -162,18 +179,34 @@ Output (JSON):
     console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
     process.exit(1);
   }
+  // Optional server token: appended to the /live.js src so the token-gated
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  const tokenIdx = args.indexOf('--token');
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
   const gitIgnore = ensureLiveGitIgnores(
     process.cwd(),
-    nuxt ? [nuxt.pluginFile] : [],
+    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
   );
 
   if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
+    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
     console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
     return;
   }
+  if (tanstack) {
+    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
+    console.log(JSON.stringify({
+      ok: !adapterResult.error,
+      port,
+      adapter: 'tanstack-start',
+      gitIgnore,
+      results: [adapterResult],
+    }));
+    if (adapterResult.error) process.exitCode = 1;
+    return;
+  }
   if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
+    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
     console.log(JSON.stringify({
       ok: !adapterResult.error,
       port,
@@ -190,7 +223,7 @@ Output (JSON):
     if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile);
+    const withTag = insertTag(withoutOld, config, port, relFile, token);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
@@ -276,9 +309,9 @@ export function detectNuxtProject(cwd = process.cwd()) {
   return { configFile, appDir, pluginFile };
 }
 
-export function buildNuxtPlugin(port) {
+export function buildNuxtPlugin(port, token) {
   return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = 'http://localhost:${port}/live.js';
+const liveSrc = '${buildLiveScriptSrc(port, token)}';
 const liveSelector = 'script[data-impeccable-live-nuxt]';
 
 export default defineNuxtPlugin(() => {
@@ -303,7 +336,7 @@ export default defineNuxtPlugin(() => {
 `;
 }
 
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = detectNuxtProject(cwd) }) {
+export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
   if (!project) return { error: 'nuxt_not_detected' };
   const absFile = path.join(cwd, project.pluginFile);
   const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
@@ -315,7 +348,7 @@ export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, project = dete
     };
   }
 
-  const content = buildNuxtPlugin(port);
+  const content = buildNuxtPlugin(port, token);
   fs.mkdirSync(path.dirname(absFile), { recursive: true });
   if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
   return {
@@ -497,7 +530,18 @@ function validateConfig(cfg) {
 function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
 function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
 
-function buildTagBlock(syntax, port, filePath) {
+/**
+ * Build the /live.js src the browser loads. When a token is supplied it rides
+ * as a `?token=...` query param so the server's token-gated /live.js handler
+ * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
+ * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}
+
+function buildTagBlock(syntax, port, filePath, token) {
   const open = commentOpen(syntax);
   const close = commentClose(syntax);
   // Astro processes <script> tags by default and rewrites src to its own
@@ -506,7 +550,7 @@ function buildTagBlock(syntax, port, filePath) {
   const scriptAttrs = isAstro ? 'is:inline ' : '';
   return (
     open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="http://localhost:' + port + '/live.js"></script>\n' +
+    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
     open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
   );
 }
@@ -528,9 +572,9 @@ function readLineEndingAt(content, index) {
   return '';
 }
 
-function insertTag(content, config, port, filePath) {
+function insertTag(content, config, port, filePath, token) {
   const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath), lineEnding);
+  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
   // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
   // belong at the end, and the same literal can appear earlier in code blocks
   // within rendered documentation pages.

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

@@ -131,6 +131,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +247,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +271,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,

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

@@ -235,11 +235,12 @@ function recordAgentPhase(id, phase, details = {}) {
 /**
  * Detect a browser that missed the generation `done` broadcast.
  *
- * The preflight scaffold write triggers a framework full-reload (Astro reloads
- * the page for any .astro edit). If the agent's variant write + `done` land
- * while the browser is mid-reload, the new page misses both the second HMR
- * reload and the SSE `done` — it resumes from the scaffold-only source and
- * sits in GENERATING at 0/N forever. That resumed page always checkpoints
+ * The preflight no longer writes the scaffold into source for source-preview
+ * targets (the agent writes wrapper + variants in one atomic edit), so the old
+ * scaffold-write full-reload that opened the "stranded at 0/N" race is gone.
+ * This recovery stays as defense in depth: any framework reload that drops the
+ * agent's variant write + `done` while the browser is mid-reload leaves the new
+ * page in GENERATING at 0/N. That resumed page always checkpoints
  * (`browser_resumed`), so a checkpoint claiming "still generating, variants
  * missing" for a session whose generation already completed is direct
  * evidence of the miss. Rebuild the `done` payload from the snapshot so the
@@ -624,13 +625,37 @@ function statOrNull(filePath) {
   try { return fs.statSync(filePath); } catch { return null; }
 }
 
+// Strict loopback-origin test for CORS. Parses the Origin as a URL (never a
+// substring match, so `http://localhost.evil.com` and `http://127.0.0.1.evil.com`
+// fail) and accepts only http/https on localhost, 127.0.0.1, or the IPv6 loopback.
+function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.length === 0) return false;
+  let parsed;
+  try { parsed = new URL(origin); } catch { return false; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  const host = parsed.hostname.toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
 // HTTP request handler
 // ---------------------------------------------------------------------------
 
 function createRequestHandler({ detectScript, liveScriptParts }) {
   return (req, res) => {
     const url = new URL(req.url, `http://localhost:${state.port}`);
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // Loopback-restricted CORS. Reflect the caller's Origin only when it is a
+    // loopback origin, always paired with `Vary: Origin` so an intermediary
+    // cache never serves a response authorized for one origin to another. A
+    // remote page (e.g. https://evil.example probing the port from a tab open
+    // on the same machine) gets no Access-Control-Allow-Origin, so its
+    // JS-initiated fetch cannot read any response. Requests with no Origin
+    // header (script tags, curl, the agent's own fetches) are not subject to
+    // CORS and keep working; no ACAO header is needed for them.
+    const origin = req.headers.origin;
+    if (origin && isLoopbackOrigin(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
@@ -639,6 +664,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
 
     // --- Scripts ---
     if (p === '/live.js') {
+      // Token-gated: the script body embeds state.token, which unlocks every
+      // token-guarded route. Serving it unauthenticated let any local page read
+      // the token and drive the session. The injected <script src> carries
+      // `?token=...` (see live-inject.mjs). A missing/wrong token → 401.
+      if (url.searchParams.get('token') !== state.token) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+      }
       // Re-read from disk each request so edits to live-browser.js land on
       // the next tab reload. No-store headers prevent browser caching across
       // sessions — during iteration, a cached old script silently breaks
@@ -846,7 +880,13 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
       const filePath = url.searchParams.get('path');
       if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
       const absPath = path.resolve(process.cwd(), filePath);
-      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
+      // Confine to the project root. A bare `startsWith(cwd)` string check lets a
+      // sibling dir whose name extends the root name (projeto -> projeto-backup)
+      // slip through; compare on the relative path instead (same pattern as
+      // sessionFileMetadataFromPollReply below). An empty rel means the request
+      // resolved to the root directory itself, which this file route never serves.
+      const rel = path.relative(process.cwd(), absPath);
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { res.writeHead(403); res.end('Forbidden'); return; }
       let content;
       try { content = fs.readFileSync(absPath, 'utf-8'); }
       catch { res.writeHead(404); res.end('File not found'); return; }

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

@@ -68,6 +68,13 @@ The agent should insert variant HTML at insertLine.`);
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
   const pageUrl = argVal(args, '--page-url');
+  // Preflight passes this for source-preview targets. It computes the scaffold
+  // (element location + wrapper text) but does NOT write it into source. The
+  // agent then writes the wrapper + all variants in one atomic edit. The
+  // premature server-side write full-reloaded the framework mid-generate and
+  // stranded the browser at 0/N (live-server.mjs missed-completion note). It is
+  // a no-op on the svelte-component path, which never writes the route source.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!elementId && !classes && !query) {
@@ -334,6 +341,7 @@ The agent should insert variant HTML at insertLine.`);
   let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
   let insertLine;
   let svelteSession = null;
+  let deferredWrapper = null;
 
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
@@ -353,6 +361,20 @@ The agent should insert variant HTML at insertLine.`);
     outputStartLine = 1;
     outputEndLine = 1;
     insertLine = 1;
+  } else if (deferSourceWrite) {
+    // Deferred source write: compute the scaffold text but leave source
+    // untouched. The agent replaces the picked element's source range with
+    // `wrapperBlock` (variants spliced at the marker) in one edit. Writing the
+    // scaffold here first would reload the framework before the agent's write
+    // lands, and a browser caught mid-reload misses the `done` and sits at 0/N.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: startLine + 1, // 1-indexed picked-element range the
+      replaceEndLine: endLine + 1,     // agent's wrapper block replaces
+    };
+    // insertLine matches the final file position the wrapper occupies once the
+    // agent replaces the picked range, so downstream consumers stay consistent.
+    insertLine = startLine + 6 + (originalLines.length - 1) + 1;
   } else {
     // Replace the original element with the wrapper
     const newLines = [
@@ -383,6 +405,13 @@ The agent should insert variant HTML at insertLine.`);
     file: outputRelFile,
     sourceFile: useFrameworkComponent ? relTargetFile : undefined,
     previewMode,
+    // Deferred source write: the wrapper is NOT yet in source. The agent
+    // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
+    // spliced at the "insert below this line" marker) in one atomic edit.
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
     sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,

.grok/skills/impeccable/scripts/live.mjs

@@ -112,7 +112,11 @@ The agent should then:
   }
 
   // 3. Inject the script tag at the current port
-  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
+  const injectOut = runScript(
+    'live-inject.mjs',
+    ['--port', String(serverInfo.port), '--token', String(serverInfo.token)],
+    { cwd: activeCwd },
+  );
   const injectResult = safeParse(injectOut);
   if (!injectResult || !injectResult.ok) {
     console.log(JSON.stringify({