sync: auto-sync from DESKTOP-0O8A1RL at 2026-05-22 11:07:55

Author: Mike Swanson
Machine: DESKTOP-0O8A1RL
Timestamp: 2026-05-22 11:07:55

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

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

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

@@ -0,0 +1,94 @@
+{
+  "craft": {
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
+    "argumentHint": "[feature description]"
+  },
+  "teach": {
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
+    "argumentHint": ""
+  },
+  "extract": {
+    "description": "Pull reusable patterns, components, and design tokens into the design system. Identifies repeated patterns and consolidates them. Use when you have drift across the codebase and want to bring things back to a consistent system.",
+    "argumentHint": "[target]"
+  },
+  "live": {
+    "description": "Interactive live variant mode. Select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via HMR. Requires a running dev server. Use when you want to visually experiment with design alternatives in real time.",
+    "argumentHint": ""
+  },
+  "adapt": {
+    "description": "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility.",
+    "argumentHint": "[target] [context (mobile, tablet, print...)]"
+  },
+  "animate": {
+    "description": "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive.",
+    "argumentHint": "[target]"
+  },
+  "audit": {
+    "description": "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "bolder": {
+    "description": "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character.",
+    "argumentHint": "[target]"
+  },
+  "clarify": {
+    "description": "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.",
+    "argumentHint": "[target]"
+  },
+  "colorize": {
+    "description": "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.",
+    "argumentHint": "[target]"
+  },
+  "critique": {
+    "description": "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "delight": {
+    "description": "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.",
+    "argumentHint": "[target]"
+  },
+  "distill": {
+    "description": "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused.",
+    "argumentHint": "[target]"
+  },
+  "harden": {
+    "description": "Make interfaces production-ready: error handling, i18n, text overflow, edge case management, and resilience under real-world data. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues.",
+    "argumentHint": "[target]"
+  },
+  "onboard": {
+    "description": "Design onboarding flows, first-run experiences, and empty states that guide new users to value. Covers welcome screens, account setup, progressive disclosure, contextual tooltips, feature announcements, and activation moments. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment.",
+    "argumentHint": "[target]"
+  },
+  "layout": {
+    "description": "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.",
+    "argumentHint": "[target]"
+  },
+  "optimize": {
+    "description": "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience.",
+    "argumentHint": "[target]"
+  },
+  "overdrive": {
+    "description": "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.",
+    "argumentHint": "[target]"
+  },
+  "polish": {
+    "description": "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.",
+    "argumentHint": "[target]"
+  },
+  "quieter": {
+    "description": "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.",
+    "argumentHint": "[target]"
+  },
+  "shape": {
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
+    "argumentHint": "[feature to shape]"
+  },
+  "typeset": {
+    "description": "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.",
+    "argumentHint": "[target]"
+  }
+}

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

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

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

@@ -0,0 +1,820 @@
+// Parse a DESIGN.md (Stitch-spec format) into a structured JSON model that
+// the live-mode design-system panel can render. Deterministic, dependency-free.
+//
+// Two-layer: YAML frontmatter (machine-readable tokens) + markdown body
+// (prose with six canonical H2 sections). When frontmatter is present, it's
+// exposed on `model.frontmatter` alongside the prose-scraped sections;
+// consumers can prefer frontmatter values and fall back to prose.
+
+const CANONICAL_SECTIONS = [
+  'Overview',
+  'Colors',
+  'Typography',
+  'Elevation',
+  'Components',
+  "Do's and Don'ts",
+];
+
+// ---------- Frontmatter (Stitch YAML subset) ----------
+
+function parseFrontmatter(md) {
+  const lines = md.split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') return { frontmatter: null, body: md };
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) return { frontmatter: null, body: md };
+
+  const yaml = lines.slice(1, end).join('\n');
+  const body = lines.slice(end + 1).join('\n');
+  try {
+    return { frontmatter: parseYamlSubset(yaml), body };
+  } catch {
+    return { frontmatter: null, body: md };
+  }
+}
+
+// Minimal YAML reader for the Stitch frontmatter subset: scalar maps with
+// one level of nested objects (typography roles, components). Indent-based,
+// 2-space convention. No arrays, no anchors, no multi-line scalars — Stitch's
+// schema doesn't need them and accepting them would require a real YAML
+// dependency we don't want to vendor.
+function parseYamlSubset(yaml) {
+  const lines = yaml.split(/\r?\n/);
+  const root = {};
+  const stack = [{ indent: -1, obj: root }];
+
+  for (const raw of lines) {
+    // Skip blanks and line-only comments. Don't strip inline comments:
+    // unquoted hex values start with `#` and can't be safely distinguished
+    // from a comment after whitespace.
+    if (!raw.trim() || /^\s*#/.test(raw)) continue;
+
+    const indent = raw.match(/^\s*/)[0].length;
+    const content = raw.slice(indent);
+
+    const colonIdx = findTopLevelColon(content);
+    if (colonIdx === -1) continue;
+
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+
+    const key = content.slice(0, colonIdx).trim();
+    const rest = content.slice(colonIdx + 1).trim();
+    const parent = stack[stack.length - 1].obj;
+
+    if (rest === '') {
+      const obj = {};
+      parent[key] = obj;
+      stack.push({ indent, obj });
+    } else {
+      parent[key] = parseScalar(rest);
+    }
+  }
+
+  return root;
+}
+
+function findTopLevelColon(s) {
+  let inQuote = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inQuote) {
+      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ':') {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === 'null' || s === '~') return null;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (/^-?\d*\.\d+$/.test(s)) return Number(s);
+  return s;
+}
+
+const HEX_RE = /#[0-9a-fA-F]{3,8}\b/g;
+const OKLCH_RE = /oklch\([^)]+\)/gi;
+const RGBA_RE = /rgba?\([^)]+\)/gi;
+const BOX_SHADOW_RE = /(?:box-shadow:\s*)?((?:-?\d[\w\d\s\-.,/()#%]*)+)/;
+const NAMED_RULE_RE = /\*\*(The [^*]+?Rule)\.\*\*\s*(.+)/;
+
+// ---------- Section splitting ----------
+
+function splitSections(md) {
+  const lines = md.split(/\r?\n/);
+  let title = null;
+  const sections = {};
+  let current = null;
+
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+
+    if (!title && line.startsWith('# ') && !line.startsWith('## ')) {
+      title = line.replace(/^#\s+/, '').trim();
+      continue;
+    }
+
+    const h2 = line.match(/^##\s+(?:\d+\.\s*)?([^:\n]+?)(?::\s*(.+))?$/);
+    if (h2) {
+      const rawName = normalizeApostrophes(h2[1].trim());
+      const subtitle = h2[2] ? h2[2].trim() : null;
+      const canonical = matchCanonicalSection(rawName);
+      if (canonical) {
+        current = { name: canonical, subtitle, lines: [] };
+        sections[canonical] = current;
+        continue;
+      }
+      // non-canonical H2 — ignore but stop feeding into current
+      current = null;
+      continue;
+    }
+
+    if (current) current.lines.push(raw);
+  }
+
+  return { title, sections };
+}
+
+function normalizeApostrophes(s) {
+  return s.replace(/[\u2018\u2019]/g, "'");
+}
+
+function matchCanonicalSection(name) {
+  const normalized = normalizeApostrophes(name).toLowerCase();
+  // Exact match first
+  for (const c of CANONICAL_SECTIONS) {
+    if (normalizeApostrophes(c).toLowerCase() === normalized) return c;
+  }
+  // Keyword-contained match: "Overview & Creative North Star" -> "Overview",
+  // "Elevation & Depth" -> "Elevation", etc.
+  for (const c of CANONICAL_SECTIONS) {
+    const key = normalizeApostrophes(c).toLowerCase();
+    const pattern = new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+    if (pattern.test(normalized)) return c;
+  }
+  return null;
+}
+
+// ---------- Subsection splitting (inside a canonical section) ----------
+
+function splitSubsections(lines) {
+  const subs = [];
+  let current = { name: null, lines: [] };
+  subs.push(current);
+
+  for (const raw of lines) {
+    const h3 = raw.match(/^###\s+(.+?)\s*$/);
+    if (h3) {
+      current = { name: h3[1].trim(), lines: [] };
+      subs.push(current);
+      continue;
+    }
+    current.lines.push(raw);
+  }
+
+  return subs;
+}
+
+// ---------- Generic helpers ----------
+
+function collectParagraphs(lines) {
+  const paragraphs = [];
+  let buf = [];
+  const flush = () => {
+    if (buf.length) {
+      paragraphs.push(buf.join(' ').trim());
+      buf = [];
+    }
+  };
+  for (const raw of lines) {
+    const trimmed = raw.trim();
+    if (trimmed === '') { flush(); continue; }
+    // Horizontal rules (---, ***) and headings/bullets end a paragraph.
+    if (/^(?:-{3,}|\*{3,}|_{3,})$/.test(trimmed)) { flush(); continue; }
+    if (raw.startsWith('#') || raw.match(/^[-*]\s/)) { flush(); continue; }
+    buf.push(trimmed);
+  }
+  flush();
+  return paragraphs.filter(Boolean);
+}
+
+function collectBullets(lines) {
+  const bullets = [];
+  let current = null;
+  for (const raw of lines) {
+    const m = raw.match(/^\s*[-*]\s+(.+)$/);
+    if (m) {
+      if (current) bullets.push(current);
+      current = m[1];
+      continue;
+    }
+    // continuation of a bullet (indented line)
+    if (current && raw.match(/^\s{2,}\S/)) {
+      current += ' ' + raw.trim();
+      continue;
+    }
+    // blank line ends a bullet
+    if (raw.trim() === '' && current) {
+      bullets.push(current);
+      current = null;
+    }
+  }
+  if (current) bullets.push(current);
+  return bullets;
+}
+
+function stripBold(s) {
+  return s.replace(/\*\*(.+?)\*\*/g, '$1');
+}
+
+function extractNamedRules(lines) {
+  const rules = [];
+  const seen = new Set();
+
+  // Style A (Impeccable): "**The X Rule.** body body body" — can span lines.
+  const joined = lines.join('\n');
+  const inlineStart = /\*\*(The [^*]+?Rule)\.\*\*/g;
+  const inlineMatches = [];
+  let m;
+  while ((m = inlineStart.exec(joined)) !== null) {
+    inlineMatches.push({ name: m[1], start: m.index, end: inlineStart.lastIndex });
+  }
+  for (let i = 0; i < inlineMatches.length; i++) {
+    const mm = inlineMatches[i];
+    const bodyEnd = i + 1 < inlineMatches.length ? inlineMatches[i + 1].start : joined.length;
+    const body = joined
+      .slice(mm.end, bodyEnd)
+      .replace(/\n##[^\n]*$/s, '')
+      .replace(/\n###[^\n]*$/s, '')
+      .trim();
+    const name = stripBold(mm.name).trim();
+    seen.add(name.toLowerCase());
+    rules.push({ name, body: stripBold(body) });
+  }
+
+  // Style B (Stitch): `### The "X" Rule` or `### The X Fallback`, body is the
+  // bullets/paragraphs until the next heading. Accept Rule / Fallback / Principle.
+  for (let i = 0; i < lines.length; i++) {
+    const h3 = lines[i].match(/^###\s+(.+?)\s*$/);
+    if (!h3) continue;
+    const headerName = stripBold(h3[1]).replace(/["“”]/g, '').trim();
+    if (!/^The\b.*\b(Rule|Fallback|Principle)\b/i.test(headerName)) continue;
+    if (seen.has(headerName.toLowerCase())) continue;
+
+    const bodyLines = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^##\s|^###\s/.test(lines[j])) break;
+      bodyLines.push(lines[j]);
+    }
+    const body = stripBold(bodyLines.join('\n').replace(/\n+/g, ' ')).trim();
+    if (body) {
+      seen.add(headerName.toLowerCase());
+      rules.push({ name: headerName, body });
+    }
+  }
+
+  // Style C (Stitch bullet form): "*   **The Layering Principle:** body"
+  // Colon/period lives inside the bold, so match "**...**" then inspect.
+  for (const b of collectBullets(lines)) {
+    const mm = b.match(/^\*\*([^*]+?)\*\*\s*(.+)$/);
+    if (!mm) continue;
+    const nameRaw = mm[1].replace(/[.:]\s*$/, '').replace(/["“”]/g, '').trim();
+    if (!/^The\b.+\b(Rule|Fallback|Principle)$/i.test(nameRaw)) continue;
+    if (seen.has(nameRaw.toLowerCase())) continue;
+    seen.add(nameRaw.toLowerCase());
+    rules.push({ name: nameRaw, body: stripBold(mm[2]).trim() });
+  }
+
+  return rules;
+}
+
+// ---------- Per-section extractors ----------
+
+function extractOverview(section) {
+  if (!section) return null;
+  const text = section.lines.join('\n');
+  const northStar = text.match(/\*\*Creative North Star:\s*"([^"]+)"\*\*/);
+  const keyChars = [];
+  const keyCharMatch = text.match(/\*\*Key Characteristics:\*\*\s*\n([\s\S]+?)(?:\n##|\n###|$)/);
+  if (keyCharMatch) {
+    for (const line of keyCharMatch[1].split('\n')) {
+      const m = line.match(/^\s*[-*]\s+(.+)$/);
+      if (m) keyChars.push(stripBold(m[1].trim()));
+    }
+  }
+
+  // Philosophy paragraphs: everything that isn't a rule header or key-char block
+  const paragraphs = collectParagraphs(section.lines).filter(
+    (p) =>
+      !p.startsWith('**Creative North Star') &&
+      !p.startsWith('**Key Characteristics')
+  );
+
+  return {
+    subtitle: section.subtitle,
+    creativeNorthStar: northStar ? northStar[1] : null,
+    philosophy: paragraphs,
+    keyCharacteristics: keyChars,
+  };
+}
+
+function extractColors(section) {
+  if (!section) return null;
+  const subs = splitSubsections(section.lines);
+
+  const description = collectParagraphs(subs[0].lines).join(' ');
+  const groups = [];
+  const ROLE_KEYWORDS = /^(primary|secondary|tertiary|neutral|accent)\b/i;
+
+  for (const sub of subs.slice(1)) {
+    if (!sub.name || /Named Rules?/i.test(sub.name) || /^The\s/i.test(sub.name)) continue;
+
+    const bullets = collectBullets(sub.lines);
+    const parsed = bullets.map((b) => parseColorBullet(b)).filter(Boolean);
+    if (parsed.length === 0) continue;
+
+    // If every bullet starts with a role keyword (Primary/Secondary/...), promote
+    // each bullet to its own group. Otherwise keep the subsection as the group.
+    const allRoleBullets =
+      parsed.length > 0 && parsed.every((p) => p.name && ROLE_KEYWORDS.test(p.name));
+
+    if (allRoleBullets) {
+      for (const p of parsed) {
+        groups.push({ role: p.name, colors: [p] });
+      }
+    } else {
+      groups.push({ role: sub.name, colors: parsed });
+    }
+  }
+
+  // If the Colors section has no subsections at all (unlikely), fall back to
+  // scanning the whole section as a flat bullet list.
+  if (groups.length === 0) {
+    const flat = collectBullets(section.lines)
+      .map((b) => parseColorBullet(b))
+      .filter(Boolean);
+    if (flat.length) {
+      for (const p of flat) {
+        if (p.name && ROLE_KEYWORDS.test(p.name)) {
+          groups.push({ role: p.name, colors: [p] });
+        } else {
+          const fallback = groups.find((g) => g.role === 'Palette');
+          if (fallback) fallback.colors.push(p);
+          else groups.push({ role: 'Palette', colors: [p] });
+        }
+      }
+    }
+  }
+
+  return {
+    subtitle: section.subtitle,
+    description: description || null,
+    groups,
+    rules: extractNamedRules(section.lines),
+  };
+}
+
+function parseColorBullet(bullet) {
+  const text = bullet.trim();
+
+  // Case 1 (Impeccable): **Name** (value-with-maybe-nested-parens): description
+  const bold = text.match(/^\*\*(.+?)\*\*\s*(.*)$/);
+  if (bold && bold[2].startsWith('(')) {
+    const value = extractParenGroup(bold[2]);
+    if (value !== null) {
+      const after = bold[2].slice(value.length + 2).trimStart();
+      if (after.startsWith(':')) {
+        return buildColor(bold[1], value, after.slice(1).trim());
+      }
+    }
+  }
+
+  // Case 2 (Stitch): **Name (values):** description   — value embedded in bold.
+  const stitch = text.match(/^\*\*([^*]+?)\s*\(([^)]+)\):\*\*\s*(.*)$/);
+  if (stitch) {
+    return buildColor(stitch[1].trim(), stitch[2], stitch[3]);
+  }
+
+  // Case 3: bullet without bold, just hex/oklch inside.
+  const values = collectColorValues(text);
+  if (values.length) {
+    return buildColor(null, values.join(' to '), text);
+  }
+  return null;
+}
+
+function extractParenGroup(s) {
+  if (s[0] !== '(') return null;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0) return s.slice(1, i);
+    }
+  }
+  return null;
+}
+
+function buildColor(name, rawValue, description) {
+  const values = collectColorValues(rawValue);
+  const primary = values[0] ?? rawValue.trim();
+  return {
+    name: name ? stripBold(name).trim() : null,
+    value: primary,
+    valueRange: values.length > 1 ? values : null,
+    format: detectFormat(primary),
+    description: stripBold(description || '').trim() || null,
+  };
+}
+
+function collectColorValues(s) {
+  const out = [];
+  s.replace(HEX_RE, (v) => {
+    out.push(v);
+    return v;
+  });
+  s.replace(OKLCH_RE, (v) => {
+    out.push(v);
+    return v;
+  });
+  return out;
+}
+
+function detectFormat(v) {
+  if (!v) return 'unknown';
+  if (v.startsWith('#')) return 'hex';
+  if (/^oklch/i.test(v)) return 'oklch';
+  if (/^rgb/i.test(v)) return 'rgb';
+  return 'unknown';
+}
+
+function scanInlineColors(lines) {
+  const out = [];
+  for (const line of lines) {
+    if (!/^\s*[-*]\s/.test(line)) continue;
+    const trimmed = line.replace(/^\s*[-*]\s+/, '');
+    const color = parseColorBullet(trimmed);
+    if (color) out.push(color);
+  }
+  return out;
+}
+
+function parseStitchInlineGroups(lines) {
+  // Stitch writes: `*   **Primary (`#00478d` to `#005eb8`):** Use for "..."`
+  // Each bullet IS its own role. Group them under the spoken role name.
+  const out = [];
+  for (const line of lines) {
+    if (!/^\s*[-*]\s/.test(line)) continue;
+    const trimmed = line.replace(/^\s*[-*]\s+/, '').trim();
+    const m = trimmed.match(
+      /^\*\*([A-Z][a-zA-Z]+)\s*\(([^)]+)\):\*\*\s*(.*)$/
+    );
+    if (m) {
+      const role = m[1];
+      const color = buildColor(role, m[2], m[3]);
+      out.push({ role, colors: [color] });
+    }
+  }
+  return out;
+}
+
+function extractTypography(section) {
+  if (!section) return null;
+  const text = section.lines.join('\n');
+
+  const fonts = {};
+  // Pattern A: **Display Font:** Family (with fallback)
+  const fontLineRe = /\*\*([\w\s/]+?)Font:\*\*\s*([^\n(]+?)(?:\s*\(with\s+([^)]+)\))?\s*$/gm;
+  let fm;
+  while ((fm = fontLineRe.exec(text)) !== null) {
+    const rawRole = fm[1].trim().toLowerCase().replace(/\s+/g, '-');
+    const role = normalizeFontRole(rawRole) || 'display';
+    fonts[role] = {
+      family: fm[2].trim(),
+      fallback: fm[3] ? fm[3].trim() : null,
+    };
+  }
+
+  // Pattern B (Stitch): *   **Display & Headlines (Noto Serif):** description
+  if (Object.keys(fonts).length === 0) {
+    const stitchRe = /\*\*([\w\s&/]+?)\s*\(([^)]+)\):\*\*\s*(.+)/g;
+    let sm;
+    while ((sm = stitchRe.exec(text)) !== null) {
+      const rawRole = sm[1]
+        .trim()
+        .toLowerCase()
+        .replace(/\s*&\s*/g, '-')
+        .replace(/\s+/g, '-');
+      const role = normalizeFontRole(rawRole) || rawRole;
+      fonts[role] = { family: sm[2].trim(), fallback: null, purpose: sm[3].trim() };
+    }
+  }
+
+  // Character paragraph — either a **Character:** label, or fall back to the
+  // first free paragraph under the section header (Stitch style).
+  const characterMatch = text.match(/\*\*Character:\*\*\s*([^\n]+(?:\n[^\n]+)*?)(?=\n\n|\n###|\n##|$)/);
+  let character = characterMatch ? characterMatch[1].replace(/\n/g, ' ').trim() : null;
+  if (!character) {
+    const paragraphs = collectParagraphs(section.lines).filter(
+      (p) => !/^\*\*[\w\s/&]+Font/i.test(p) && !/^\*\*[\w\s/&]+\([^)]+\)/.test(p)
+    );
+    if (paragraphs.length) character = paragraphs[0];
+  }
+
+  // Hierarchy bullets under ### Hierarchy
+  const subs = splitSubsections(section.lines);
+  let hierarchy = [];
+  const hierSub = subs.find((s) => s.name && /hierarch/i.test(s.name));
+  if (hierSub) {
+    const bullets = collectBullets(hierSub.lines);
+    hierarchy = bullets.map(parseTypeBullet).filter(Boolean);
+  }
+
+  return {
+    subtitle: section.subtitle,
+    fonts,
+    character,
+    hierarchy,
+    rules: extractNamedRules(section.lines),
+  };
+}
+
+function normalizeFontRole(raw) {
+  // Canonical roles the panel cares about: display, body, label, mono.
+  // Stitch often writes compound roles like "display-&-headlines" or "ui-&-body"
+  // — collapse them to the first canonical role present.
+  const tokens = raw.split(/[-/&\s]+/).filter(Boolean);
+  const priority = ['display', 'headline', 'body', 'ui', 'label', 'mono'];
+  const canonical = { headline: 'display', ui: 'body' };
+  for (const p of priority) {
+    if (tokens.includes(p)) return canonical[p] || p;
+  }
+  return null;
+}
+
+function parseTypeBullet(bullet) {
+  // - **Display** (family, weight 300, italic, clamp(...), line-height 1): purpose
+  const m = bullet.match(/^\*\*(.+?)\*\*\s*\(([^)]+)\):\s*(.*)$/);
+  if (!m) return null;
+  const name = m[1].trim();
+  const specs = m[2].split(',').map((s) => s.trim());
+  return {
+    name,
+    specs,
+    purpose: stripBold(m[3] || '').trim() || null,
+  };
+}
+
+function extractElevation(section) {
+  if (!section) return null;
+  const subs = splitSubsections(section.lines);
+
+  const description = collectParagraphs(subs[0].lines).join(' ') || null;
+
+  const shadows = [];
+  const seen = new Set();
+  const dedupe = (entry) => {
+    const key = (entry.name || '') + '::' + entry.value;
+    if (seen.has(key)) return;
+    seen.add(key);
+    shadows.push(entry);
+  };
+
+  for (const b of collectBullets(section.lines)) {
+    const parsed = parseShadowBullet(b);
+    if (parsed) dedupe(parsed);
+  }
+
+  // Fallback: extract shadows written inline in prose. Stitch style is
+  //   "...use an extra-diffused shadow: `box-shadow: 0 12px 40px rgba(...)`."
+  for (const p of collectParagraphs(section.lines)) {
+    for (const inline of extractInlineShadows(p)) dedupe(inline);
+  }
+  for (const b of collectBullets(section.lines)) {
+    for (const inline of extractInlineShadows(b)) dedupe(inline);
+  }
+
+  return {
+    subtitle: section.subtitle,
+    description,
+    shadows,
+    rules: extractNamedRules(section.lines),
+  };
+}
+
+function extractInlineShadows(text) {
+  // Find `box-shadow: ...` anywhere in prose and capture the value. Work on the
+  // raw string so it handles both backtick-fenced and unfenced variants.
+  const out = [];
+  const re = /box-shadow\s*:\s*([^`;\n]+)/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const value = m[1].replace(/[`.)]+$/, '').trim();
+    if (!value) continue;
+    // Name heuristic: the noun immediately before the shadow phrase.
+    // e.g. "an extra-diffused shadow: ..." -> "extra-diffused shadow"
+    const before = text.slice(0, m.index);
+    const nameMatch = before.match(/\b([A-Za-z][A-Za-z\- ]{2,40})\s+shadow\b[^A-Za-z0-9]*$/i);
+    let name = null;
+    if (nameMatch) {
+      const stripped = nameMatch[1]
+        .replace(/^(?:use|using|apply|applying|is|are|looks? like)\s+/i, '')
+        .replace(/^(?:a|an|the)\s+/i, '')
+        .trim();
+      if (stripped) {
+        name =
+          stripped.charAt(0).toUpperCase() + stripped.slice(1) + ' shadow';
+      }
+    }
+    out.push({
+      name,
+      value,
+      purpose: null,
+    });
+  }
+  return out;
+}
+
+function parseShadowBullet(bullet) {
+  // - **Name** (`box-shadow: value`): purpose
+  // - **Name** (`value`): purpose
+  // Only accept if the paren content looks like a shadow value (contains px,
+  // rem, rgba, or box-shadow). This filters out `**Rule Name:**` bullets.
+  const m = bullet.match(/^\*\*(.+?)\*\*\s*\(`?([^`]+?)`?\):\s*(.*)$/);
+  if (!m) return null;
+  const rawValue = m[2].replace(/^box-shadow:\s*/i, '').trim();
+  const looksLikeShadow =
+    /box-shadow|rgba?\(|\bpx\b|\brem\b|^-?\d+\s/i.test(rawValue) &&
+    /\d/.test(rawValue);
+  if (!looksLikeShadow) return null;
+  const name = stripBold(m[1]).trim();
+  return {
+    name,
+    value: rawValue,
+    purpose: stripBold(m[3] || '').trim() || null,
+  };
+}
+
+function extractComponents(section) {
+  if (!section) return null;
+  const subs = splitSubsections(section.lines);
+  const components = [];
+
+  for (const sub of subs.slice(1)) {
+    if (!sub.name) continue;
+
+    const bullets = collectBullets(sub.lines);
+    const paragraphs = collectParagraphs(sub.lines);
+
+    const variants = [];
+    const properties = {};
+
+    for (const b of bullets) {
+      // - **Key:** value
+      const m = b.match(/^\*\*(.+?):?\*\*:?\s*(.+)$/);
+      if (m) {
+        const key = stripBold(m[1]).trim();
+        const value = stripBold(m[2]).trim();
+        // Heuristic: "Primary", "Secondary", "Hover", "Focus" etc are variants;
+        // "Shape", "Background", "Padding" are properties.
+        if (/^(primary|secondary|tertiary|ghost|hover|focus|active|disabled|default|error|selected|unselected|state)$/i.test(key.split(/[\s/]/)[0])) {
+          variants.push({ name: key, description: value });
+        } else {
+          properties[key.toLowerCase()] = value;
+        }
+      }
+    }
+
+    components.push({
+      name: sub.name,
+      description: paragraphs.join(' ') || null,
+      properties,
+      variants,
+    });
+  }
+
+  return {
+    subtitle: section.subtitle,
+    components,
+  };
+}
+
+function extractDosDonts(section) {
+  if (!section) return null;
+  const subs = splitSubsections(section.lines);
+  const dos = [];
+  const donts = [];
+
+  for (const sub of subs.slice(1)) {
+    if (!sub.name) continue;
+    const subName = normalizeApostrophes(sub.name);
+    const bullets = collectBullets(sub.lines).map((b) => stripBold(b).trim());
+    if (/^do'?t?:?$/i.test(subName) || /^do:?$/i.test(subName)) {
+      dos.push(...bullets);
+    } else if (/^don'?t:?$/i.test(subName)) {
+      donts.push(...bullets);
+    }
+  }
+
+  // Classify by bullet prefix as a backup (catches loose bullets outside H3 wrappers)
+  for (const b of collectBullets(section.lines)) {
+    const stripped = normalizeApostrophes(stripBold(b).trim());
+    if (/^don'?t\b/i.test(stripped)) {
+      if (!donts.some((d) => normalizeApostrophes(d) === stripped)) donts.push(stripped);
+    } else if (/^do\b/i.test(stripped)) {
+      if (!dos.some((d) => normalizeApostrophes(d) === stripped)) dos.push(stripped);
+    }
+  }
+
+  return { dos, donts };
+}
+
+// ---------- Coverage assessment ----------
+
+function assessCoverage(model) {
+  const report = {};
+
+  report.overview = model.overview
+    ? {
+        northStar: Boolean(model.overview.creativeNorthStar),
+        philosophy: model.overview.philosophy.length > 0,
+        keyCharacteristics: model.overview.keyCharacteristics.length,
+      }
+    : 'missing';
+
+  report.colors = model.colors
+    ? {
+        groups: model.colors.groups.length,
+        totalColors: model.colors.groups.reduce((n, g) => n + g.colors.length, 0),
+        rules: model.colors.rules.length,
+      }
+    : 'missing';
+
+  report.typography = model.typography
+    ? {
+        fonts: Object.keys(model.typography.fonts).length,
+        hierarchyEntries: model.typography.hierarchy.length,
+        character: Boolean(model.typography.character),
+        rules: model.typography.rules.length,
+      }
+    : 'missing';
+
+  report.elevation = model.elevation
+    ? {
+        shadows: model.elevation.shadows.length,
+        rules: model.elevation.rules.length,
+        description: Boolean(model.elevation.description),
+      }
+    : 'missing';
+
+  report.components = model.components
+    ? {
+        count: model.components.components.length,
+        variantTotal: model.components.components.reduce((n, c) => n + c.variants.length, 0),
+      }
+    : 'missing';
+
+  report.dosDonts = model.dosDonts
+    ? {
+        dos: model.dosDonts.dos.length,
+        donts: model.dosDonts.donts.length,
+      }
+    : 'missing';
+
+  return report;
+}
+
+// ---------- Main ----------
+
+export function parseDesignMd(md) {
+  const { frontmatter, body } = parseFrontmatter(md);
+  const { title, sections } = splitSections(body);
+  return {
+    schemaVersion: 2,
+    title,
+    frontmatter,
+    overview: extractOverview(sections['Overview']),
+    colors: extractColors(sections['Colors']),
+    typography: extractTypography(sections['Typography']),
+    elevation: extractElevation(sections['Elevation']),
+    components: extractComponents(sections['Components']),
+    dosDonts: extractDosDonts(sections["Do's and Don'ts"]),
+  };
+}
+
+export { assessCoverage };

.agents/skills/impeccable/scripts/detect-csp.mjs

@@ -0,0 +1,198 @@
+/**
+ * Scan a project tree for Content-Security-Policy signals and classify the
+ * shape so the agent knows which patch template to propose.
+ *
+ * Used at first-time `live.mjs` setup. Mechanical (grep-based) — no network,
+ * no dev server, no JS evaluation. The classification drives a user-facing
+ * consent prompt; the agent does the actual patch writing.
+ *
+ * Shapes are named by patch mechanism, not framework origin:
+ *   - "append-arrays":  CSP defined as structured directive arrays. Patch
+ *                       appends a dev-only localhost entry. Covers:
+ *                         - Monorepo helpers with additional*Src options
+ *                           (e.g. createBaseNextConfig for Next)
+ *                         - SvelteKit kit.csp.directives
+ *                         - nuxt-security module's contentSecurityPolicy
+ *   - "append-string":  CSP built as a literal value string. Patch splices
+ *                       a dev-only token into script-src and connect-src.
+ *                       Covers:
+ *                         - Inline Next.js headers() with CSP string
+ *                         - Nuxt routeRules / nitro.routeRules CSP headers
+ *   - "middleware":     CSP set dynamically in middleware.{ts,js}.
+ *                       Detected but not auto-patched in v1.
+ *   - "meta-tag":       <meta http-equiv="Content-Security-Policy"> in
+ *                       layout files. Detected but not auto-patched in v1.
+ *   - null:             no CSP signals found; no patch needed.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.turbo',
+  '.svelte-kit',
+  '.nuxt',
+  '.astro',
+  'dist',
+  'build',
+  'out',
+  '.vercel',
+]);
+
+const SCAN_EXTS = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.tsx', '.jsx']);
+const LAYOUT_EXTS = new Set(['.tsx', '.jsx', '.astro', '.vue', '.svelte', '.html']);
+const MAX_DEPTH = 6;
+const MAX_READ_BYTES = 64 * 1024;
+
+// append-arrays signals: CSP expressed as structured directive arrays
+const MONOREPO_HELPER_SIGNALS = [
+  /\bbuildCSPConfig\b/,
+  /\bbuildSecurityHeaders\b/,
+  /\badditionalScriptSrc\b/,
+  /\badditionalConnectSrc\b/,
+  /\bcreateBaseNextConfig\b/,
+];
+const SVELTEKIT_CSP_SIGNALS = [
+  /\bkit\s*:/,
+  /\bcsp\s*:/,
+  /\bdirectives\s*:/,
+];
+const NUXT_SECURITY_SIGNALS = [
+  /['"]nuxt-security['"]/,
+  /\bcontentSecurityPolicy\b/,
+];
+
+// append-string signals: CSP written as a literal value string
+const INLINE_HEADER_SIGNALS = [
+  /["']Content-Security-Policy["']/i,
+  /\bscript-src\b/,
+  /\bconnect-src\b/,
+];
+const NUXT_ROUTE_RULES_SIGNALS = [
+  /\brouteRules\b/,
+  /Content-Security-Policy/i,
+  /\bscript-src\b/,
+];
+
+const MIDDLEWARE_HINT = /headers\.set\(\s*["']Content-Security-Policy["']/i;
+const META_TAG_HINT = /http-equiv\s*=\s*["']Content-Security-Policy["']/i;
+
+/**
+ * @param {string} cwd Project root.
+ * @returns {{ shape: string|null, signals: string[] }}
+ */
+export function detectCsp(cwd = process.cwd()) {
+  const hits = { appendArrays: [], appendString: [], middleware: [], metaTag: [] };
+
+  walk(cwd, cwd, 0, (absPath, relPath, body) => {
+    const ext = path.extname(absPath);
+    const base = path.basename(absPath).toLowerCase();
+    const isConfig = (name) =>
+      new RegExp('(^|/)' + name + '\\.config\\.').test(relPath);
+
+    // === append-arrays candidates ===
+
+    // Monorepo CSP helper: packages/*/src/.../(config|security)/*
+    if (SCAN_EXTS.has(ext) &&
+        /packages\/[^/]+\/src\/.*(config|next-config|security)/.test(relPath) &&
+        MONOREPO_HELPER_SIGNALS.some((re) => re.test(body))) {
+      hits.appendArrays.push(relPath);
+      return;
+    }
+
+    // SvelteKit kit.csp.directives
+    if (SCAN_EXTS.has(ext) && isConfig('svelte') &&
+        SVELTEKIT_CSP_SIGNALS.every((re) => re.test(body))) {
+      hits.appendArrays.push(relPath);
+      return;
+    }
+
+    // Nuxt nuxt-security module
+    if (SCAN_EXTS.has(ext) && isConfig('nuxt') &&
+        NUXT_SECURITY_SIGNALS.every((re) => re.test(body))) {
+      hits.appendArrays.push(relPath);
+      return;
+    }
+
+    // === append-string candidates ===
+
+    // Inline headers in Next/Nuxt/SvelteKit/Astro/Vite config
+    if (SCAN_EXTS.has(ext) &&
+        /(^|\/)(next|nuxt|vite|astro|svelte)\.config\./.test(relPath) &&
+        INLINE_HEADER_SIGNALS.every((re) => re.test(body))) {
+      // Nuxt routeRules is a sub-shape of append-string; we already covered
+      // nuxt-security above via return, so any remaining Nuxt CSP match here
+      // is a route-rules / inline-headers case. Either way, same patch
+      // mechanism.
+      hits.appendString.push(relPath);
+      return;
+    }
+
+    // === detect-only shapes ===
+
+    if ((base === 'middleware.ts' || base === 'middleware.js' || base === 'middleware.mjs') &&
+        MIDDLEWARE_HINT.test(body)) {
+      hits.middleware.push(relPath);
+    }
+
+    if (LAYOUT_EXTS.has(ext) && META_TAG_HINT.test(body)) {
+      hits.metaTag.push(relPath);
+    }
+  });
+
+  // Priority: append-arrays > append-string > middleware > meta-tag.
+  // Structured patches are safer than string splices; runtime and HTML
+  // injection patches are less reliable and v1 doesn't auto-apply them.
+  if (hits.appendArrays.length > 0) {
+    return { shape: 'append-arrays', signals: hits.appendArrays };
+  }
+  if (hits.appendString.length > 0) {
+    return { shape: 'append-string', signals: hits.appendString };
+  }
+  if (hits.middleware.length > 0) {
+    return { shape: 'middleware', signals: hits.middleware };
+  }
+  if (hits.metaTag.length > 0) {
+    return { shape: 'meta-tag', signals: hits.metaTag };
+  }
+  return { shape: null, signals: [] };
+}
+
+function walk(root, dir, depth, visit) {
+  if (depth > MAX_DEPTH) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walk(root, abs, depth + 1, visit);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name);
+    if (!SCAN_EXTS.has(ext) && !LAYOUT_EXTS.has(ext)) continue;
+    let body;
+    try {
+      const fd = fs.openSync(abs, 'r');
+      try {
+        const buf = Buffer.alloc(MAX_READ_BYTES);
+        const n = fs.readSync(fd, buf, 0, MAX_READ_BYTES, 0);
+        body = buf.slice(0, n).toString('utf-8');
+      } finally { fs.closeSync(fd); }
+    } catch { continue; }
+    visit(abs, path.relative(root, abs), body);
+  }
+}
+
+// CLI mode
+const _running = process.argv[1];
+if (_running?.endsWith('detect-csp.mjs') || _running?.endsWith('detect-csp.mjs/')) {
+  const result = detectCsp(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}

.agents/skills/impeccable/scripts/detect.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const candidates = [
+  path.join(__dirname, 'detector', 'detect-antipatterns.mjs'),
+  path.join(__dirname, '..', '..', 'cli', 'engine', 'detect-antipatterns.mjs'),
+];
+const detectorPath = candidates.find(p => fs.existsSync(p));
+
+if (!detectorPath) {
+  process.stderr.write('Error: bundled detector not found.\n');
+  process.exit(1);
+}
+
+const { detectCli } = await import(pathToFileURL(detectorPath));
+
+await detectCli();

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

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

.agents/skills/impeccable/scripts/is-generated.mjs

@@ -0,0 +1,69 @@
+/**
+ * Decide whether a given file is "generated" (regenerated by a build step,
+ * unsafe to write variants into) or "source" (safe to edit, changes persist).
+ *
+ * Why this matters: when the user picks an element on a page whose underlying
+ * file is regenerated by a build step (e.g. `scripts/build-sub-pages.js`
+ * rewriting `public/docs/*.html`), writing variants or accepted changes into
+ * that file is silent data loss — the next build wipes them.
+ *
+ * Signals, in order of reliability:
+ *   1. Git check-ignore: gitignored files are assumed generated.
+ *   2. File-header markers ("GENERATED", "DO NOT EDIT", "AUTO-GENERATED")
+ *      within the first ~300 characters — catches non-git projects.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HEADER_SCAN_BYTES = 300;
+const HEADER_MARKERS = [
+  /@generated\b/i,
+  /\bGENERATED\s+FILE\b/,
+  /\bAUTO-?GENERATED\b/i,
+  /\bDO\s+NOT\s+EDIT\b/i,
+];
+
+/**
+ * @param {string} filePath - absolute or cwd-relative path
+ * @param {object} [options]
+ * @param {string} [options.cwd] - project root (defaults to process.cwd())
+ */
+export function isGeneratedFile(filePath, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+
+  if (isGitIgnored(absPath, cwd)) return true;
+  if (hasGeneratedHeader(absPath)) return true;
+  return false;
+}
+
+function isGitIgnored(absPath, cwd) {
+  try {
+    execSync(`git check-ignore --quiet ${JSON.stringify(absPath)}`, {
+      cwd,
+      stdio: 'ignore',
+    });
+    return true; // exit 0 = ignored
+  } catch (err) {
+    // Exit code 1 = not ignored. Exit code 128 = not a git repo or other error.
+    // In both cases, treat as "not known to be ignored."
+    return false;
+  }
+}
+
+function hasGeneratedHeader(absPath) {
+  let fd;
+  try {
+    fd = fs.openSync(absPath, 'r');
+    const buf = Buffer.alloc(HEADER_SCAN_BYTES);
+    const bytesRead = fs.readSync(fd, buf, 0, HEADER_SCAN_BYTES, 0);
+    const head = buf.slice(0, bytesRead).toString('utf-8');
+    return HEADER_MARKERS.some((re) => re.test(head));
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch {} }
+  }
+}

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

@@ -0,0 +1,595 @@
+/**
+ * CLI helper: deterministic accept/discard of variant sessions.
+ *
+ * Usage:
+ *   node live-accept.mjs --id SESSION_ID --discard
+ *   node live-accept.mjs --id SESSION_ID --variant N
+ *
+ * For discard: removes the entire variant wrapper and restores the original.
+ * For accept: replaces the wrapper with the chosen variant's content. If the
+ * session had a colocated <style> block, it's preserved with carbonize markers
+ * for a background agent to integrate into the project's CSS.
+ *
+ * Output: JSON to stdout.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+
+const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+export async function acceptCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: node live-accept.mjs [options]
+
+Deterministic accept/discard for live variant sessions.
+
+Modes:
+  --discard          Remove variants, restore original
+  --variant N        Accept variant N, discard the rest
+
+Required:
+  --id SESSION_ID    Session ID of the variant wrapper
+
+Output (JSON):
+  { handled, file, carbonize }`);
+    process.exit(0);
+  }
+
+  const id = argVal(args, '--id');
+  const variantNum = argVal(args, '--variant');
+  const paramValuesRaw = argVal(args, '--param-values');
+  const isDiscard = args.includes('--discard');
+
+  if (!id) { console.error('Missing --id'); process.exit(1); }
+  if (!isDiscard && !variantNum) { console.error('Need --discard or --variant N'); process.exit(1); }
+
+  let paramValues = null;
+  if (paramValuesRaw) {
+    try { paramValues = JSON.parse(paramValuesRaw); }
+    catch { paramValues = null; } // malformed blob: skip the comment rather than failing the accept
+  }
+
+  // Find the file containing this session's markers
+  const found = findSessionFile(id, process.cwd());
+  if (!found) {
+    console.log(JSON.stringify({ handled: false, error: 'Session markers not found for id: ' + id }));
+    process.exit(0);
+  }
+
+  const { file: targetFile, content, lines } = found;
+  const relFile = path.relative(process.cwd(), targetFile);
+
+  // Bail if the session lives in a generated file. The agent manually wrote
+  // the wrapper there for preview, and is responsible for writing the
+  // accepted variant to true source (or cleaning up on discard). See
+  // "Handle fallback" in live.md.
+  if (isGeneratedFile(targetFile, { cwd: process.cwd() })) {
+    console.log(JSON.stringify({
+      handled: false,
+      mode: 'fallback',
+      file: relFile,
+      hint: 'Session is in a generated file. Persist the accepted variant in source; do not rely on this script.',
+    }));
+    process.exit(0);
+  }
+
+  if (isDiscard) {
+    const result = handleDiscard(id, lines, targetFile);
+    console.log(JSON.stringify({ handled: true, file: relFile, carbonize: false, ...result }));
+  } else {
+    const result = handleAccept(id, variantNum, lines, targetFile, paramValues);
+    // Single-line attention-grabber when cleanup is required. The full
+    // five-step checklist lives in reference/live.md (loaded once per
+    // session); repeating it per-event would waste tokens.
+    if (result.carbonize) {
+      result.todo = 'REQUIRED before next poll: carbonize cleanup in ' + relFile + '. See reference/live.md "Required after accept".';
+    }
+    console.log(JSON.stringify({ handled: true, file: relFile, ...result }));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discard
+// ---------------------------------------------------------------------------
+
+function handleDiscard(id, lines, targetFile) {
+  const block = findMarkerBlock(id, lines);
+  if (!block) return { handled: false, error: 'Markers not found' };
+
+  const original = extractOriginal(lines, block);
+  const isJsx = detectCommentSyntax(targetFile).open === '{/*';
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
+
+  // Restore at the line we're actually replacing FROM, not the marker line.
+  // For JSX wrappers the marker comments live INSIDE the outer `<div>`, so
+  // `block.start` sits 2 spaces deeper than the original element. Using that
+  // as the deindent base would push the restored content 2 spaces too far
+  // right on every JSX/TSX session. `replaceRange.start` is the outer wrapper
+  // line, which is at the original element's indent for both HTML and JSX.
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
+  const restored = deindentContent(original, indent);
+
+  const newLines = [
+    ...lines.slice(0, replaceRange.start),
+    ...restored,
+    ...lines.slice(replaceRange.end + 1),
+  ];
+  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Accept
+// ---------------------------------------------------------------------------
+
+function handleAccept(id, variantNum, lines, targetFile, paramValues) {
+  const block = findMarkerBlock(id, lines);
+  if (!block) return { handled: false, error: 'Markers not found' };
+
+  const commentSyntax = detectCommentSyntax(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  // Anchor indent on the line we're replacing FROM (the outer wrapper),
+  // not on `block.start` — for JSX that's the marker comment 2 spaces
+  // deeper than the original element. See handleDiscard for the full
+  // rationale.
+  const replaceRange = expandReplaceRange(block, lines, isJsx);
+  const indent = lines[replaceRange.start].match(/^(\s*)/)[1];
+
+  // Extract the chosen variant's inner content
+  const variantContent = extractVariant(lines, block, variantNum);
+  if (!variantContent) return { handled: false, error: 'Variant ' + variantNum + ' not found' };
+
+  // Extract CSS block if present
+  const cssContent = extractCss(lines, block, id);
+
+  // Check if carbonizing is needed:
+  // - CSS block exists, OR
+  // - variant HTML contains helper classes/attributes that need cleanup
+  const variantText = variantContent.join('\n');
+  const hasHelperAttrs = variantText.includes('data-impeccable-variant');
+  const needsCarbonize = !!(cssContent || hasHelperAttrs);
+
+  // Build the replacement
+  const restored = deindentContent(variantContent, indent);
+  const replacement = [];
+
+  if (cssContent) {
+    replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-start ' + id + ' ' + commentSyntax.close);
+    // JSX targets need the CSS body wrapped in a template literal so that the
+    // `{` and `}` in CSS rules don't get parsed as JSX expressions.
+    replacement.push(indent + '<style data-impeccable-css="' + id + '">' + (isJsx ? '{`' : ''));
+    // Re-indent CSS content to match
+    for (const cssLine of cssContent) {
+      replacement.push(indent + cssLine.trimStart());
+    }
+    replacement.push(indent + (isJsx ? '`}</style>' : '</style>'));
+    if (paramValues && Object.keys(paramValues).length > 0) {
+      // Preserve the user's knob positions for the carbonize-cleanup agent
+      // to bake into the final CSS when it collapses scoped rules.
+      replacement.push(indent + commentSyntax.open + ' impeccable-param-values ' + id + ': ' + JSON.stringify(paramValues) + ' ' + commentSyntax.close);
+    }
+    replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-end ' + id + ' ' + commentSyntax.close);
+  }
+
+  // Keep the `@scope ([data-impeccable-variant="N"])` selectors in the
+  // carbonize CSS block working visually by re-wrapping the accepted content
+  // in a data-impeccable-variant="N" div with `display: contents` (so layout
+  // isn't affected). The carbonize agent strips this attribute + wrapper when
+  // it moves the CSS to a proper stylesheet.
+  //
+  // Style attribute syntax has to follow the host file's flavor — JSX files
+  // need the object form, otherwise React 19 throws "Failed to set indexed
+  // property [0] on CSSStyleDeclaration" while parsing the string char-by-char.
+  if (cssContent) {
+    const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+    replacement.push(indent + '<div data-impeccable-variant="' + variantNum + '" ' + styleAttr + '>');
+    replacement.push(...restored);
+    replacement.push(indent + '</div>');
+  } else {
+    replacement.push(...restored);
+  }
+
+  const newLines = [
+    ...lines.slice(0, replaceRange.start),
+    ...replacement,
+    ...lines.slice(replaceRange.end + 1),
+  ];
+  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+  return { carbonize: needsCarbonize };
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the start/end marker lines for a session.
+ * Returns { start, end } (0-indexed line numbers) or null.
+ */
+function findMarkerBlock(id, lines) {
+  let start = -1;
+  let end = -1;
+  const startPattern = 'impeccable-variants-start ' + id;
+  const endPattern = 'impeccable-variants-end ' + id;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (start === -1 && lines[i].includes(startPattern)) start = i;
+    if (lines[i].includes(endPattern)) { end = i; break; }
+  }
+
+  return (start !== -1 && end !== -1) ? { start, end } : null;
+}
+
+/**
+ * Compute the line range to REPLACE (vs. just the marker range to extract
+ * from). For JSX/TSX wrappers, live-wrap places the marker comments INSIDE
+ * the `<div data-impeccable-variants="ID">` outer wrapper so the picked
+ * element's JSX slot keeps a single child — a Fragment `<></>` would have
+ * solved the multi-sibling case but failed inside `asChild` / cloneElement
+ * parents with "Invalid prop supplied to React.Fragment".
+ *
+ * That means the marker block is enclosed by the wrapper `<div>` opener
+ * (with `data-impeccable-variants="ID"`) and its matching `</div>`. We
+ * walk back to the opener and forward to the closer so accept/discard
+ * remove the entire scaffold, not just the inner markers.
+ *
+ * Marker lines themselves stay where they were so extractOriginal /
+ * extractVariant / extractCss continue to walk the same range.
+ */
+function expandReplaceRange(block, lines, isJsx) {
+  if (!isJsx) return { start: block.start, end: block.end };
+
+  let { start, end } = block;
+
+  // Walk back for the wrapper `<div data-impeccable-variants="..."` opener.
+  // The attr may sit on a continuation line of a multi-line opening tag, so
+  // also walk to the line that actually contains `<div`.
+  for (let i = start - 1; i >= Math.max(0, start - 12); i--) {
+    if (/data-impeccable-variants=/.test(lines[i])) {
+      let opener = i;
+      while (opener > 0 && !/<div\b/.test(lines[opener])) opener--;
+      start = opener;
+      break;
+    }
+  }
+
+  // Walk forward to the matching `</div>` by div-depth tracking from the
+  // wrapper opener. Operate on JOINED text instead of per-line: a
+  // multi-line self-closing JSX `<div\n  className="spacer"\n/>` would
+  // fool per-line regex tracking (the `<div` line matches openRe but the
+  // `/>` line never matches selfCloseRe since it needs `<div` on the same
+  // line). That left depth permanently over-counted and the wrapper's
+  // outer `</div>` orphaned after accept/discard. Single regex with
+  // `[^>]*?` (which spans newlines in JS) handles either form correctly.
+  const joined = lines.slice(start).join('\n');
+  // Match either `<div … />` (self-close, group 1 is `/`), `<div … >`
+  // (open, group 1 is empty), or `</div>`.
+  const tagRe = /<div\b[^>]*?(\/?)>|<\/div\s*>/g;
+  let depth = 0;
+  let m;
+  while ((m = tagRe.exec(joined)) !== null) {
+    const isClose = m[0].startsWith('</');
+    const isSelfClose = !isClose && m[1] === '/';
+    if (isClose) depth--;
+    else if (!isSelfClose) depth++;
+    if (depth <= 0) {
+      // m.index is offset within `joined`; convert back to a file line.
+      const linesBefore = joined.slice(0, m.index + m[0].length).split('\n').length - 1;
+      const candidateEnd = start + linesBefore;
+      if (candidateEnd >= end) {
+        end = candidateEnd;
+        break;
+      }
+    }
+  }
+
+  return { start, end };
+}
+
+/**
+ * Join wrapper lines into a single string with `<style>` elements removed so
+ * marker matching and div-depth tracking aren't confused by:
+ *   - CSS `@scope ([data-impeccable-variant="N"])` strings that look like the
+ *     HTML marker we're searching for
+ *   - JSX self-closing `<style ... />` (no separate `</style>` to close on)
+ *   - Same-line `<style>…</style>` blocks
+ *   - Multi-line `<style>\n…\n</style>` blocks
+ */
+function stripStyleAndJoin(lines, block) {
+  const out = [];
+  let inStyle = false;
+  for (let i = block.start; i <= block.end; i++) {
+    let line = lines[i];
+
+    if (!inStyle) {
+      // Strip any complete <style> elements on this line (self-closed or
+      // same-line-closed), including their body content.
+      line = line
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/g, '')
+        .replace(/<style\b[^>]*\/\s*>/g, '');
+
+      // If a <style> opener remains (multi-line body starts here), strip from
+      // the opener to end-of-line and flip into skip mode.
+      const openerIdx = line.search(/<style\b/);
+      if (openerIdx !== -1) {
+        line = line.slice(0, openerIdx);
+        inStyle = true;
+      }
+      out.push(line);
+    } else {
+      // In multi-line style body; drop everything until we see </style>.
+      const closeIdx = line.search(/<\/style\s*>/);
+      if (closeIdx !== -1) {
+        inStyle = false;
+        out.push(line.slice(closeIdx).replace(/<\/style\s*>/, ''));
+      }
+      // else: skip line entirely
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * Find the inner content of `<TAG ...attrMatch...>…</TAG>` inside `text`,
+ * handling nested same-tag elements via depth counting. `attrMatch` is a
+ * regex source fragment that must appear inside the opener tag.
+ * Returns the inner string (may be empty), or null if not found.
+ */
+function extractInnerByAttr(text, attrMatch) {
+  const openerRe = new RegExp('<([A-Za-z][A-Za-z0-9]*)\\b[^>]*' + attrMatch + '[^>]*>');
+  const openMatch = text.match(openerRe);
+  if (!openMatch) return null;
+
+  const tagName = openMatch[1];
+  const innerStart = openMatch.index + openMatch[0].length;
+
+  // Match any opener or closer of this tag name after innerStart.
+  // (Does not match self-closing <TAG … />, which doesn't contribute to depth.)
+  const tagRe = new RegExp('<(?:/)?' + tagName + '\\b[^>]*>', 'g');
+  tagRe.lastIndex = innerStart;
+
+  let depth = 1;
+  let m;
+  while ((m = tagRe.exec(text))) {
+    const isClose = m[0].startsWith('</');
+    const isSelfClose = !isClose && /\/\s*>$/.test(m[0]);
+    if (isClose) {
+      depth--;
+      if (depth === 0) return text.slice(innerStart, m.index);
+    } else if (!isSelfClose) {
+      depth++;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the original element content from within the variant wrapper.
+ * Returns an array of lines.
+ */
+function extractOriginal(lines, block) {
+  const text = stripStyleAndJoin(lines, block);
+  const inner = extractInnerByAttr(text, 'data-impeccable-variant="original"');
+  if (inner === null) return [];
+  return inner.split('\n');
+}
+
+/**
+ * Extract a specific variant's inner content (stripping the wrapper div).
+ * Returns an array of lines, or null if not found.
+ */
+function extractVariant(lines, block, variantNum) {
+  const text = stripStyleAndJoin(lines, block);
+  const inner = extractInnerByAttr(text, 'data-impeccable-variant="' + variantNum + '"');
+  if (inner === null) return null;
+  const result = inner.split('\n');
+  // Collapse a lone empty leading/trailing line (common after string splice).
+  while (result.length > 1 && result[0].trim() === '') result.shift();
+  while (result.length > 1 && result[result.length - 1].trim() === '') result.pop();
+  return result.length > 0 ? result : null;
+}
+
+/**
+ * Extract the colocated <style> block content (between the style tags).
+ * Returns an array of CSS lines, or null if no style block found.
+ *
+ * Handles three shapes of `<style data-impeccable-css="ID" ...>`:
+ *   1. Self-closing: `<style ... />` — no body; return null (nothing to carbonize).
+ *   2. Same-line open+close: `<style>...</style>` — return the inner content.
+ *   3. Multi-line: `<style>` on one line, `</style>` on a later line — return
+ *      the lines between them.
+ */
+function extractCss(lines, block, id) {
+  const styleAttr = 'data-impeccable-css="' + id + '"';
+  let inStyle = false;
+  const content = [];
+
+  for (let i = block.start; i <= block.end; i++) {
+    const line = lines[i];
+
+    if (!inStyle && line.includes(styleAttr)) {
+      // Self-closing: nothing to carbonize.
+      if (/<style\b[^>]*\/\s*>/.test(line)) return null;
+      // Same-line open + close: extract inner text.
+      const sameLine = line.match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/);
+      if (sameLine) {
+        const inner = stripJsxTemplateWrap(sameLine[1]);
+        return inner.length > 0 ? inner.split('\n') : null;
+      }
+      inStyle = true;
+      continue; // skip the <style> opening tag
+    }
+
+    if (inStyle) {
+      // Detect </style> anywhere on the line — JSX template-literal closes
+      // (`}</style>`) put the close mid-line, and we don't want to absorb the
+      // template-literal punctuation as CSS content.
+      const closeIdx = line.indexOf('</style>');
+      if (closeIdx !== -1) break;
+      content.push(line);
+    }
+  }
+
+  if (content.length === 0) return null;
+  return stripJsxTemplateLines(content);
+}
+
+/**
+ * Strip a JSX template-literal wrap (`{` … `}`) from CSS extracted out of a
+ * `<style>` element in a JSX/TSX file. The agent may write the wrap with
+ * `{` and `}` directly attached to the `<style>` tags, on their own lines,
+ * or attached to the first/last CSS lines — all three are JSX-legal.
+ *
+ * Stripping is required because handleAccept re-wraps the CSS itself when
+ * carbonizing. Without this, two consecutive accepts (or a previously-
+ * accepted variants block being carbonized) would produce nested
+ * `{` `{` … `}` `}`, which oxc rejects with "Expected `}` but found `@`".
+ */
+function stripJsxTemplateLines(content) {
+  const out = content.slice();
+
+  // Drop any leading blank lines so we don't miss a `{` line buried below
+  // them; same for trailing.
+  while (out.length > 0 && out[0].trim() === '') out.shift();
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+  if (out.length === 0) return null;
+
+  // Leading `{`: own line, or attached to the first CSS line.
+  const firstTrim = out[0].trimStart();
+  if (firstTrim === '{`') {
+    out.shift();
+  } else if (firstTrim.startsWith('{`')) {
+    const idx = out[0].indexOf('{`');
+    out[0] = out[0].slice(0, idx) + out[0].slice(idx + 2);
+    if (out[0].trim() === '') out.shift();
+  }
+  if (out.length === 0) return null;
+
+  // Trailing `` ` `` `}`: own line, or attached to the last CSS line.
+  const lastIdx = out.length - 1;
+  const lastTrim = out[lastIdx].trimEnd();
+  if (lastTrim === '`}') {
+    out.pop();
+  } else if (lastTrim.endsWith('`}')) {
+    const text = out[lastIdx];
+    const idx = text.lastIndexOf('`}');
+    out[lastIdx] = text.slice(0, idx) + text.slice(idx + 2);
+    if (out[lastIdx].trim() === '') out.pop();
+  }
+
+  return out.length > 0 ? out : null;
+}
+
+function stripJsxTemplateWrap(text) {
+  const lines = text.split('\n');
+  const stripped = stripJsxTemplateLines(lines);
+  return stripped ? stripped.join('\n') : '';
+}
+
+/**
+ * De-indent content that was indented by live-wrap.mjs.
+ * The wrap script adds `indent + '    '` (4 extra spaces) to each line.
+ * We restore to just `indent` level.
+ */
+function deindentContent(contentLines, baseIndent) {
+  // Find the minimum indentation in the content to determine how much was added
+  let minIndent = Infinity;
+  for (const line of contentLines) {
+    if (line.trim() === '') continue;
+    const leadingSpaces = line.match(/^(\s*)/)[1].length;
+    minIndent = Math.min(minIndent, leadingSpaces);
+  }
+  if (minIndent === Infinity) minIndent = 0;
+
+  // Strip the extra indentation and re-add base indent
+  return contentLines.map(line => {
+    if (line.trim() === '') return '';
+    return baseIndent + line.slice(minIndent);
+  });
+}
+
+function detectCommentSyntax(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jsx' || ext === '.tsx') {
+    return { open: '{/*', close: '*/}' };
+  }
+  return { open: '<!--', close: '-->' };
+}
+
+// ---------------------------------------------------------------------------
+// File search (find the file containing session markers)
+// ---------------------------------------------------------------------------
+
+function findSessionFile(id, cwd) {
+  const marker = 'impeccable-variants-start ' + id;
+  const searchDirs = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', '.'];
+  const seen = new Set();
+
+  for (const dir of searchDirs) {
+    const absDir = path.join(cwd, dir);
+    if (!fs.existsSync(absDir)) continue;
+    const result = searchDir(absDir, marker, seen, 0);
+    if (result) {
+      const content = fs.readFileSync(result, 'utf-8');
+      return { file: result, content, lines: content.split('\n') };
+    }
+  }
+  return null;
+}
+
+function searchDir(dir, query, seen, depth) {
+  if (depth > 5) return null;
+  let realDir;
+  try { realDir = fs.realpathSync(dir); } catch { return null; }
+  if (seen.has(realDir)) return null;
+  seen.add(realDir);
+
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return null; }
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!EXTENSIONS.includes(path.extname(entry.name).toLowerCase())) continue;
+    const filePath = path.join(dir, entry.name);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      if (content.includes(query)) return filePath;
+    } catch { /* skip */ }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (['node_modules', '.git', 'dist', 'build'].includes(entry.name)) continue;
+    const result = searchDir(path.join(dir, entry.name), query, seen, depth + 1);
+    if (result) return result;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function argVal(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+// Auto-execute when run directly
+const _running = process.argv[1];
+if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
+  acceptCli();
+}
+
+export { findMarkerBlock, extractOriginal, extractVariant, extractCss, deindentContent, detectCommentSyntax };

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

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

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

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

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

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

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

@@ -0,0 +1,446 @@
+/**
+ * CLI helper: insert/remove the live variant mode script tag in the project's
+ * main HTML entry point.
+ *
+ * On first live run, the agent generates `.impeccable/live/config.json`
+ * with the project's insertion target (framework-specific). On
+ * every subsequent run, this script handles insert/remove deterministically
+ * with zero LLM involvement.
+ *
+ * Usage:
+ *   node live-inject.mjs --port PORT   # Insert the live script tag
+ *   node live-inject.mjs --remove      # Remove the live script tag
+ *   node live-inject.mjs --check       # Check whether live config exists
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveLiveConfigPath } from './impeccable-paths.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
+const MARKER_OPEN_TEXT = 'impeccable-live-start';
+const MARKER_CLOSE_TEXT = 'impeccable-live-end';
+
+/**
+ * Hard-excluded directory patterns. These are NEVER user-facing pages and
+ * matching them would silently inject tracking scripts into third-party
+ * code. The user cannot turn these off via config — they are the floor.
+ */
+const HARD_EXCLUDES = [
+  '**/node_modules/**',
+  '**/.git/**',
+];
+
+export async function injectCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: node live-inject.mjs [options]
+
+Insert or remove the live mode script tag in the project's HTML entry point.
+Reads configuration from .impeccable/live/config.json.
+
+Modes:
+  --port PORT   Insert script tag pointing at http://localhost:PORT/live.js
+  --remove      Remove the script tag (if present)
+  --check       Print whether .impeccable/live/config.json exists and its content
+
+Output (JSON):
+  { ok, file, inserted|removed, config? }`);
+    process.exit(0);
+  }
+
+  if (args.includes('--check')) {
+    if (!fs.existsSync(CONFIG_PATH)) {
+      console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+      process.exit(0);
+    }
+    let cfg;
+    try {
+      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+    } catch (err) {
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      return;
+    }
+    try {
+      validateConfig(cfg);
+    } catch (err) {
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      return;
+    }
+    console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
+    return;
+  }
+
+  // Load config
+  if (!fs.existsSync(CONFIG_PATH)) {
+    console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+    process.exit(1);
+  }
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  validateConfig(config);
+
+  const resolvedFiles = resolveFiles(process.cwd(), config);
+
+  if (args.includes('--remove')) {
+    const results = resolvedFiles.map((relFile) => {
+      const absFile = path.resolve(process.cwd(), relFile);
+      if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
+      const content = fs.readFileSync(absFile, 'utf-8');
+      const detagged = removeTag(content, config.commentSyntax);
+      const updated = revertCspMeta(detagged);
+      if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
+      fs.writeFileSync(absFile, updated, 'utf-8');
+      return {
+        file: relFile,
+        removed: detagged !== content,
+        cspReverted: updated !== detagged,
+      };
+    });
+    console.log(JSON.stringify({ ok: true, results }));
+    return;
+  }
+
+  // Insert mode — need --port
+  const portIdx = args.indexOf('--port');
+  const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : NaN;
+  if (!Number.isFinite(port)) {
+    console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
+    process.exit(1);
+  }
+
+  const results = resolvedFiles.map((relFile) => {
+    const absFile = path.resolve(process.cwd(), relFile);
+    if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
+    const content = fs.readFileSync(absFile, 'utf-8');
+    const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
+    const withTag = insertTag(withoutOld, config, port);
+    if (withTag === withoutOld) {
+      return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
+    }
+    const updated = patchCspMeta(withTag, port);
+    fs.writeFileSync(absFile, updated, 'utf-8');
+    return {
+      file: relFile,
+      inserted: true,
+      cspPatched: updated !== withTag,
+    };
+  });
+  const anyInserted = results.some((r) => r.inserted);
+  console.log(JSON.stringify({ ok: anyInserted, port, results }));
+  if (!anyInserted) process.exit(1);
+}
+
+/**
+ * Expand config.files (which may contain glob patterns) into a literal list
+ * of existing file paths relative to rootDir. Literal entries pass through;
+ * glob patterns are expanded via fs.globSync. HARD_EXCLUDES and config.exclude
+ * are applied as filters. Duplicates are removed. Order is preserved by
+ * first appearance.
+ */
+export function resolveFiles(rootDir, config) {
+  const patterns = config.files;
+  const userExcludes = Array.isArray(config.exclude) ? config.exclude : [];
+  const allExcludes = [...HARD_EXCLUDES, ...userExcludes];
+  const excludeRegexes = allExcludes.map(globToRegex);
+
+  const isExcluded = (relPath) => excludeRegexes.some((re) => re.test(relPath));
+  const isGlob = (s) => /[*?[]/.test(s);
+
+  const seen = new Set();
+  const out = [];
+  for (const pat of patterns) {
+    if (!isGlob(pat)) {
+      // Literal path — include even if it doesn't exist yet; the caller
+      // reports file_not_found per-entry. Exclude list doesn't apply to
+      // explicit literal entries (user named it on purpose).
+      if (!seen.has(pat)) {
+        seen.add(pat);
+        out.push(pat);
+      }
+      continue;
+    }
+    let matches;
+    try {
+      matches = fs.globSync(pat, { cwd: rootDir, withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of matches) {
+      if (!ent.isFile || !ent.isFile()) continue;
+      const abs = path.join(ent.parentPath || ent.path || rootDir, ent.name);
+      const rel = path.relative(rootDir, abs).split(path.sep).join('/');
+      if (isExcluded(rel)) continue;
+      if (seen.has(rel)) continue;
+      seen.add(rel);
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Convert a glob pattern to a RegExp. Supports:
+ *   **  → any number of path segments (including zero)
+ *   *   → any chars except `/`
+ *   ?   → any single char except `/`
+ * Paths are normalized to forward slashes before matching.
+ */
+function globToRegex(pattern) {
+  let re = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // ** — any number of segments, including zero. Handle the common
+        // **/ and /** forms so `a/**/b` matches `a/b` as well as `a/x/y/b`.
+        if (pattern[i + 2] === '/') {
+          re += '(?:.*/)?';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+      re += '\\' + c;
+      i += 1;
+    } else {
+      re += c;
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// ---------------------------------------------------------------------------
+// Core operations
+// ---------------------------------------------------------------------------
+
+function validateConfig(cfg) {
+  if (!cfg || typeof cfg !== 'object') throw new Error('config.json must be an object');
+  if (!Array.isArray(cfg.files) || cfg.files.length === 0) {
+    throw new Error('config.files (non-empty string array) required');
+  }
+  if (!cfg.files.every((f) => typeof f === 'string' && f.length > 0)) {
+    throw new Error('config.files must contain only non-empty strings');
+  }
+  if (cfg.exclude !== undefined) {
+    if (!Array.isArray(cfg.exclude)) {
+      throw new Error('config.exclude, if present, must be a string array');
+    }
+    if (!cfg.exclude.every((f) => typeof f === 'string' && f.length > 0)) {
+      throw new Error('config.exclude must contain only non-empty strings');
+    }
+  }
+  if (typeof cfg.insertBefore !== 'string' && typeof cfg.insertAfter !== 'string') {
+    throw new Error('config.insertBefore or config.insertAfter (string) required');
+  }
+  if (cfg.commentSyntax !== 'html' && cfg.commentSyntax !== 'jsx') {
+    throw new Error("config.commentSyntax must be 'html' or 'jsx'");
+  }
+  if (cfg.cspChecked !== undefined && typeof cfg.cspChecked !== 'boolean') {
+    throw new Error("config.cspChecked, if present, must be a boolean");
+  }
+}
+
+function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
+function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
+
+function buildTagBlock(syntax, port) {
+  const open = commentOpen(syntax);
+  const close = commentClose(syntax);
+  return (
+    open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
+    '<script src="http://localhost:' + port + '/live.js"></script>\n' +
+    open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
+  );
+}
+
+function insertTag(content, config, port) {
+  const block = buildTagBlock(config.commentSyntax, port);
+  // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
+  // belong at the end, and the same literal can appear earlier in code blocks
+  // within rendered documentation pages.
+  if (config.insertBefore) {
+    const idx = content.lastIndexOf(config.insertBefore);
+    if (idx === -1) return content;
+    return content.slice(0, idx) + block + content.slice(idx);
+  }
+  // insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
+  // `<body>` open near the top of the document.
+  const idx = content.indexOf(config.insertAfter);
+  if (idx === -1) return content;
+  const after = idx + config.insertAfter.length;
+  // Preserve a single trailing newline if the anchor didn't end with one
+  const prefix = content[after] === '\n' ? content.slice(0, after + 1) : content.slice(0, after) + '\n';
+  return prefix + block + content.slice(prefix.length);
+}
+
+/**
+ * Remove the live script block. Matches either HTML or JSX comment markers
+ * regardless of config (so stale tags from a wrong config can still be cleaned).
+ *
+ * Indent-preserving: captures any whitespace immediately preceding the opener
+ * marker and re-emits it in place of the removed block. `insertTag` inserted
+ * the block *after* the original line's indent and *before* the anchor (e.g.
+ * `</body>`), which moved the indent onto the opener line and left the anchor
+ * unindented. Replacing the whole block (plus its trailing newline) with just
+ * the captured indent hands the indent back to the anchor that follows.
+ */
+function removeTag(content, _syntax) {
+  const patterns = [
+    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->[ \t]*\n/,
+    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}[ \t]*\n/,
+  ];
+  for (const pat of patterns) {
+    const next = content.replace(pat, '$1');
+    if (next !== content) return next;
+  }
+  return content;
+}
+
+// ---------------------------------------------------------------------------
+// Content-Security-Policy meta-tag patcher
+//
+// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
+// the cross-origin load of /live.js (and the SSE/POST connection back to
+// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
+//
+// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
+// and stash the original `content` value in a `data-impeccable-csp-original`
+// attribute (base64) so revert is exact.
+//
+// On remove: detect the marker attribute, decode it, restore the original
+// content value verbatim, drop the marker.
+//
+// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
+// shared helpers) is NOT patched here — those need framework-specific config
+// edits and are handled via the existing detect-csp.mjs reference output.
+// Only the in-source meta-tag form gets the auto-patch.
+// ---------------------------------------------------------------------------
+
+const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
+
+function findCspMetaTags(content) {
+  const out = [];
+  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
+  let m;
+  while ((m = tagRe.exec(content)) !== null) {
+    const attrs = m[1];
+    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
+    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
+  }
+  return out;
+}
+
+function getAttr(attrs, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
+  const m = attrs.match(re);
+  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
+}
+
+function appendOriginToDirective(csp, directive, origin) {
+  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
+  const m = csp.match(re);
+  if (m) {
+    const tokens = m[4].trim().split(/\s+/);
+    if (tokens.includes(origin)) return csp;
+    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
+  }
+  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
+  // narrow the policy compared to the default-src fallback (most users with
+  // an explicit CSP have 'self' there).
+  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
+}
+
+export function patchCspMeta(content, port) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+  const origin = `http://localhost:${port}`;
+
+  // Walk last-to-first so prior splices don't invalidate later indices.
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const attrs = tag.attrs;
+    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
+    const contentAttr = getAttr(attrs, 'content');
+    if (!contentAttr) continue;
+
+    const original = contentAttr.value;
+    let patched = original;
+    patched = appendOriginToDirective(patched, 'script-src', origin);
+    patched = appendOriginToDirective(patched, 'connect-src', origin);
+    // The shader overlay during 'generating' creates a screenshot via
+    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
+    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
+    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
+    if (patched === original) continue;
+
+    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
+    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
+    // The tagRe captures any whitespace between the last attribute and the
+    // closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
+    // a replace would land it BEFORE that trailing space, leaving a double
+    // space inside attrs and clobbering the space before `/>`. Split off
+    // the trailing whitespace, splice the marker into the attribute body,
+    // and re-append the original trailing whitespace so a self-closing
+    // `<meta … />` round-trips byte-for-byte.
+    const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
+    const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
+    const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
+    const newTag = tag.full.replace(attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
+export function revertCspMeta(content) {
+  const tags = findCspMetaTags(content);
+  if (tags.length === 0) return content;
+
+  let result = content;
+  for (let i = tags.length - 1; i >= 0; i--) {
+    const tag = tags[i];
+    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
+    if (!origAttr) continue;
+    const contentAttr = getAttr(tag.attrs, 'content');
+    if (!contentAttr) continue;
+
+    let originalValue;
+    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
+    catch { continue; }
+
+    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
+    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
+    // Drop the marker attribute and any single space immediately preceding it.
+    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
+    const newTag = tag.full.replace(tag.attrs, newAttrs);
+
+    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-execute
+// ---------------------------------------------------------------------------
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
+  injectCli();
+}
+
+export { insertTag, removeTag, validateConfig, buildTagBlock };
+// patchCspMeta + revertCspMeta are exported above where they're defined.

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

@@ -0,0 +1,200 @@
+/**
+ * CLI client for the live variant mode poll/reply protocol.
+ *
+ * Usage:
+ *   npx impeccable poll                         # Block until browser event, print JSON
+ *   npx impeccable poll --timeout=600000        # Custom timeout (ms); default is long-poll friendly
+ *   npx impeccable poll --reply <id> done       # Reply "done" to event <id>
+ *   npx impeccable poll --reply <id> error "msg" # Reply with error
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live-completion.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
+
+// Node's built-in fetch (undici under the hood) enforces a 300s headers
+// timeout that can't be lowered per-request. We cap each request below
+// that ceiling and loop in `pollOnce` to synthesize a long poll without
+// depending on the standalone undici package.
+const PER_REQUEST_TIMEOUT_MS = 270_000;
+
+function readServerInfo() {
+  const record = readLiveServerInfo(process.cwd());
+  if (!record) {
+    console.error('No running live server found. Start one with: npx impeccable live');
+    process.exit(1);
+  }
+  return record.info;
+}
+
+export function buildPollReplyPayload(token, { id, type, message, file, data }) {
+  return { token, id, type, message, file, data };
+}
+
+async function postReply(base, token, reply) {
+  const res = await fetch(`${base}/poll`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(buildPollReplyPayload(token, reply)),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || res.statusText);
+  }
+}
+
+export async function pollCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: impeccable poll [options]
+
+Wait for a browser event from the live variant server, or reply to one.
+
+Modes:
+  poll                             Block until a browser event arrives, print JSON
+  poll --reply <id> done           Reply "done" to event <id>
+  poll --reply <id> error "msg"    Reply with an error message
+
+Options:
+  --timeout=MS   Long-poll timeout in ms (default: 600000). Use the default unless the user asked to pause live; never use a short timeout to end the chat turn
+  --help         Show this help message`);
+    process.exit(0);
+  }
+
+  const info = readServerInfo();
+  const base = `http://localhost:${info.port}`;
+
+  // Reply mode: npx impeccable poll --reply <id> <status> [--file path] [message]
+  const replyIdx = args.indexOf('--reply');
+  if (replyIdx !== -1) {
+    const id = args[replyIdx + 1];
+    const status = args[replyIdx + 2] || 'done';
+    const fileIdx = args.indexOf('--file');
+    const filePath = fileIdx !== -1 && fileIdx + 1 < args.length ? args[fileIdx + 1] : undefined;
+    // Message is any remaining positional arg that isn't a flag
+    const message = args.find((a, i) => i > replyIdx + 2 && !a.startsWith('--') && i !== fileIdx + 1) || undefined;
+
+    if (!id) {
+      console.error('Usage: npx impeccable poll --reply <id> <status> [--file path] [message]');
+      process.exit(1);
+    }
+
+    try {
+      await postReply(base, info.token, { id, type: status, message, file: filePath });
+
+      // Success — silent exit (agent doesn't need output for replies)
+    } catch (err) {
+      if (err.cause?.code === 'ECONNREFUSED') {
+        console.error('Live server not running. Start one with: npx impeccable live');
+      } else {
+        console.error('Reply failed:', err.message);
+      }
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Poll mode: block until browser event. Default 10 min. Node's built-in
+  // fetch enforces a 300s headers timeout, so we loop in slices under that
+  // ceiling and keep re-polling until we get a real event or the user's
+  // total timeout runs out.
+  const timeoutArg = args.find(a => a.startsWith('--timeout='));
+  const totalTimeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 600000;
+
+  const deadline = Date.now() + totalTimeout;
+  let event;
+  try {
+    while (true) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        event = { type: 'timeout' };
+        break;
+      }
+      const slice = Math.min(remaining, PER_REQUEST_TIMEOUT_MS);
+      const res = await fetch(`${base}/poll?token=${info.token}&timeout=${slice}`);
+
+      if (res.status === 401) {
+        console.error('Authentication failed. The server token may have changed.');
+        console.error('Try restarting: npx impeccable live stop && npx impeccable live');
+        process.exit(1);
+      }
+
+      if (!res.ok) {
+        console.error(`Poll failed: ${res.status} ${res.statusText}`);
+        process.exit(1);
+      }
+
+      const next = await res.json();
+      // Server-side timeout means no browser event arrived in this slice.
+      // Loop and re-poll until we get a real event or we hit the user's
+      // total deadline.
+      if (next?.type === 'timeout' && Date.now() < deadline) continue;
+      event = next;
+      break;
+    }
+
+    // Auto-handle accept/discard via deterministic script
+    if (event.type === 'accept' || event.type === 'discard') {
+      const __dirname = path.dirname(fileURLToPath(import.meta.url));
+      const acceptScript = path.join(__dirname, 'live-accept.mjs');
+      const scriptArgs = event.type === 'discard'
+        ? ['--id', event.id, '--discard']
+        : ['--id', event.id, '--variant', event.variantId];
+      if (event.type === 'accept' && event.paramValues && Object.keys(event.paramValues).length > 0) {
+        scriptArgs.push('--param-values', JSON.stringify(event.paramValues));
+      }
+      try {
+        const out = execFileSync(
+          'node',
+          [acceptScript, ...scriptArgs],
+          { encoding: 'utf-8', cwd: process.cwd(), timeout: 30_000 }
+        );
+        event._acceptResult = JSON.parse(out.trim());
+      } catch (err) {
+        event._acceptResult = { handled: false, mode: 'error', error: err.message };
+      }
+
+      const completionType = completionTypeForAcceptResult(event.type, event._acceptResult);
+      try {
+        await postReply(base, info.token, {
+          id: event.id,
+          type: completionType,
+          message: event._acceptResult?.error,
+          file: event._acceptResult?.file,
+          data: event._acceptResult?.carbonize === true ? { carbonize: true } : undefined,
+        });
+      } catch (err) {
+        event._completionAck = { ok: false, error: err.message };
+      }
+      if (!event._completionAck) {
+        event._completionAck = completionAckForAcceptResult(event.id, completionType, event._acceptResult);
+      }
+    }
+
+    // Second signal path: stderr banner in case the agent parses stdout
+    // JSON but skips nested fields. One line is enough — the full checklist
+    // is in reference/live.md.
+    if (event._acceptResult?.carbonize === true) {
+      process.stderr.write('\n⚠ Carbonize cleanup REQUIRED before next poll. After cleanup, run live-complete.mjs --id ' + event.id + '. See reference/live.md "Required after accept".\n\n');
+    }
+
+    // Print the event as JSON — the agent reads this from stdout
+    console.log(JSON.stringify(event));
+  } catch (err) {
+    if (err.cause?.code === 'ECONNREFUSED') {
+      console.error('Live server not running. Start one with: npx impeccable live');
+    } else {
+      console.error('Poll failed:', err.message);
+    }
+    process.exit(1);
+  }
+}
+
+// Auto-execute when run directly
+const _running = process.argv[1];
+if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
+  pollCli();
+}

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

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

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

@@ -0,0 +1,838 @@
+#!/usr/bin/env node
+/**
+ * Live variant mode server (self-contained, zero dependencies).
+ *
+ * Serves the browser script (/live.js), the detection overlay (/detect.js),
+ * uses Server-Sent Events (SSE) for server→browser push, and HTTP POST for
+ * browser→server events. Agent communicates via HTTP long-poll (/poll).
+ *
+ * Usage:
+ *   node <scripts_path>/live-server.mjs              # start
+ *   node <scripts_path>/live-server.mjs stop         # stop + remove injected live.js tag
+ *   node <scripts_path>/live-server.mjs stop --keep-inject   # stop only
+ *   node <scripts_path>/live-server.mjs --help
+ */
+
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { parseDesignMd } from './design-parser.mjs';
+import { resolveContextDir } from './load-context.mjs';
+import { createLiveSessionStore } from './live-session-store.mjs';
+import {
+  getDesignSidecarPath,
+  getLiveAnnotationsDir,
+  readLiveServerInfo,
+  removeLiveServerInfo,
+  resolveDesignSidecarPath,
+  writeLiveServerInfo,
+} from './impeccable-paths.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// PRODUCT.md / DESIGN.md live wherever load-context.mjs resolves. The generated
+// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
+// DESIGN.json fallback for existing projects.
+const CONTEXT_DIR = resolveContextDir(process.cwd());
+const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
+const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
+
+// ---------------------------------------------------------------------------
+// Port detection
+// ---------------------------------------------------------------------------
+
+async function findOpenPort(start = 8400) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.listen(start, '127.0.0.1', () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+    srv.on('error', () => resolve(findOpenPort(start + 1)));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Session state
+// ---------------------------------------------------------------------------
+
+const state = {
+  token: null,
+  port: null,
+  sseClients: new Set(),   // SSE response objects (server→browser push)
+  pendingEvents: [],        // browser events waiting for agent ack ({ event, leaseUntil })
+  pendingPolls: [],         // agent poll callbacks waiting for browser events
+  exitTimer: null,
+  sessionDir: null,         // per-session tmp dir for annotation screenshots
+  sessionStore: null,
+  leaseTimer: null,
+};
+
+// Cap per-annotation upload size. A full 1920×1080 PNG is typically <1 MB;
+// cap at 10 MB to guard against runaway writes from a misbehaving client.
+const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
+
+function enqueueEvent(event) {
+  if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
+  state.pendingEvents.push({ event, leaseUntil: 0 });
+  flushPendingPolls();
+}
+
+function restorePendingEventsFromStore() {
+  if (!state.sessionStore) return;
+  for (const snapshot of state.sessionStore.listActiveSessions()) {
+    if (snapshot.pendingEvent) enqueueEvent(snapshot.pendingEvent);
+  }
+}
+
+function findAvailablePendingEvent(now = Date.now()) {
+  return state.pendingEvents.find((entry) => !entry.leaseUntil || entry.leaseUntil <= now);
+}
+
+function leaseEvent(entry, leaseMs) {
+  if (!entry.event?.id) {
+    const idx = state.pendingEvents.indexOf(entry);
+    if (idx !== -1) state.pendingEvents.splice(idx, 1);
+    return entry.event;
+  }
+  entry.leaseUntil = Date.now() + leaseMs;
+  return entry.event;
+}
+
+function acknowledgePendingEvent(id) {
+  if (!id) return false;
+  const idx = state.pendingEvents.findIndex((entry) => entry.event?.id === id);
+  if (idx === -1) return false;
+  state.pendingEvents.splice(idx, 1);
+  scheduleLeaseFlush();
+  return true;
+}
+
+function scheduleLeaseFlush() {
+  if (state.leaseTimer) {
+    clearTimeout(state.leaseTimer);
+    state.leaseTimer = null;
+  }
+  if (state.pendingPolls.length === 0) return;
+  const now = Date.now();
+  const nextLeaseUntil = state.pendingEvents
+    .map((entry) => entry.leaseUntil || 0)
+    .filter((leaseUntil) => leaseUntil > now)
+    .sort((a, b) => a - b)[0];
+  if (!nextLeaseUntil) return;
+  state.leaseTimer = setTimeout(() => {
+    state.leaseTimer = null;
+    flushPendingPolls();
+  }, Math.max(0, nextLeaseUntil - now));
+}
+
+function flushPendingPolls() {
+  while (state.pendingPolls.length > 0) {
+    const entry = findAvailablePendingEvent();
+    if (!entry) {
+      scheduleLeaseFlush();
+      return;
+    }
+    const poll = state.pendingPolls.shift();
+    poll.resolve(leaseEvent(entry, poll.leaseMs));
+  }
+  scheduleLeaseFlush();
+}
+
+/** Push a message to all connected SSE clients. */
+function broadcast(msg) {
+  const data = 'data: ' + JSON.stringify(msg) + '\n\n';
+  for (const res of state.sseClients) {
+    try { res.write(data); } catch { /* client gone */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Load scripts
+// ---------------------------------------------------------------------------
+
+function loadBrowserScripts() {
+  // Detection script: prefer the skill-bundled detector, then fall back to
+  // source/npm package locations for local development and older installs.
+  // This one IS cached — detect.js rarely changes during a session.
+  const detectPaths = [
+    path.join(__dirname, 'detector', 'detect-antipatterns-browser.js'),
+    path.join(__dirname, '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
+    path.join(__dirname, '..', '..', '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
+    path.join(process.cwd(), 'node_modules', 'impeccable', 'cli', 'engine', 'detect-antipatterns-browser.js'),
+  ];
+  let detectScript = '';
+  for (const p of detectPaths) {
+    try { detectScript = fs.readFileSync(p, 'utf-8'); break; } catch { /* try next */ }
+  }
+
+  // live-browser.js: DO NOT cache. Return the path so the /live.js handler
+  // can re-read on every request. Editing the browser script during iteration
+  // should land on the next tab reload, not require a server restart.
+  const sessionPath = path.join(__dirname, 'live-browser-session.js');
+  const livePath = path.join(__dirname, 'live-browser.js');
+  for (const p of [sessionPath, livePath]) {
+    if (!fs.existsSync(p)) {
+      process.stderr.write('Error: live browser script not found at ' + p + '\n');
+      process.exit(1);
+    }
+  }
+
+  return { detectScript, sessionPath, livePath };
+}
+
+function hasProjectContext() {
+  // PRODUCT.md carries brand voice / anti-references — that's what determines
+  // whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
+  // concern, surfaced by the design panel's own empty state. Legacy
+  // .impeccable.md is auto-migrated to PRODUCT.md by load-context.mjs.
+  try {
+    fs.accessSync(path.join(CONTEXT_DIR, 'PRODUCT.md'), fs.constants.R_OK);
+    return true;
+  } catch { return false; }
+}
+
+function statOrNull(filePath) {
+  try { return fs.statSync(filePath); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// Validation (inline — no external import needed for self-contained script)
+// ---------------------------------------------------------------------------
+
+const VISUAL_ACTIONS = [
+  'impeccable', 'bolder', 'quieter', 'distill', 'polish', 'typeset',
+  'colorize', 'layout', 'adapt', 'animate', 'delight', 'overdrive',
+];
+
+// Browser generates ids via crypto.randomUUID().slice(0, 8) (8 hex chars)
+// and variantIds via String(small integer). Restrict to those shapes so
+// any value that reaches a downstream child_process or DOM selector is
+// inert by construction.
+const ID_PATTERN = /^[0-9a-f]{8}$/;
+const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
+
+function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
+function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
+
+function validateEvent(msg) {
+  if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
+  switch (msg.type) {
+    case 'generate':
+      if (!isValidId(msg.id)) return 'generate: missing or malformed id';
+      if (!msg.action || !VISUAL_ACTIONS.includes(msg.action)) return 'generate: invalid action';
+      if (!Number.isInteger(msg.count) || msg.count < 1 || msg.count > 8) return 'generate: count must be 1-8';
+      if (!msg.element || !msg.element.outerHTML) return 'generate: missing element context';
+      // Optional annotation fields (all-or-nothing: if any present, all must be well-formed).
+      if (msg.screenshotPath !== undefined && typeof msg.screenshotPath !== 'string') return 'generate: screenshotPath must be string';
+      if (msg.comments !== undefined && !Array.isArray(msg.comments)) return 'generate: comments must be array';
+      if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) return 'generate: strokes must be array';
+      return null;
+    case 'accept':
+      if (!isValidId(msg.id)) return 'accept: missing or malformed id';
+      if (!isValidVariantId(msg.variantId)) return 'accept: missing or malformed variantId';
+      if (msg.paramValues !== undefined) {
+        if (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues)) {
+          return 'accept: paramValues must be an object';
+        }
+      }
+      return null;
+    case 'discard':
+      return isValidId(msg.id) ? null : 'discard: missing or malformed id';
+    case 'checkpoint':
+      if (!isValidId(msg.id)) return 'checkpoint: missing or malformed id';
+      if (!Number.isInteger(msg.revision) || msg.revision < 0) return 'checkpoint: revision must be a non-negative integer';
+      if (msg.paramValues !== undefined && (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues))) {
+        return 'checkpoint: paramValues must be an object';
+      }
+      return null;
+    case 'exit':
+      return null;
+    case 'prefetch':
+      if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return 'prefetch: missing pageUrl';
+      return null;
+    default:
+      return 'Unknown event type: ' + msg.type;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP request handler
+// ---------------------------------------------------------------------------
+
+function createRequestHandler({ detectScript, sessionPath, livePath }) {
+  return (req, res) => {
+    const url = new URL(req.url, `http://localhost:${state.port}`);
+    res.setHeader('Access-Control-Allow-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; }
+
+    const p = url.pathname;
+
+    // --- Scripts ---
+    if (p === '/live.js') {
+      // 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
+      // every subsequent session.
+      let sessionScript;
+      let liveScript;
+      try {
+        sessionScript = fs.readFileSync(sessionPath, 'utf-8');
+        liveScript = fs.readFileSync(livePath, 'utf-8');
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Error reading live browser scripts: ' + err.message);
+        return;
+      }
+      const body =
+        `window.__IMPECCABLE_TOKEN__ = '${state.token}';\n` +
+        `window.__IMPECCABLE_PORT__ = ${state.port};\n` +
+        sessionScript + '\n' +
+        liveScript;
+      res.writeHead(200, {
+        'Content-Type': 'application/javascript',
+        'Cache-Control': 'no-store, no-cache, must-revalidate, max-age=0',
+        'Pragma': 'no-cache',
+      });
+      res.end(body);
+      return;
+    }
+    if (p === '/detect.js' || p === '/') {
+      if (!detectScript) { res.writeHead(404); res.end('Not available'); return; }
+      res.writeHead(200, { 'Content-Type': 'application/javascript' });
+      res.end(detectScript);
+      return;
+    }
+
+    // --- Vendored modern-screenshot (UMD build) ---
+    // Lazy-loaded by live.js when the user clicks Go; exposes
+    // window.modernScreenshot.domToBlob(...) for capture.
+    if (p === '/modern-screenshot.js') {
+      const vendorPath = path.join(__dirname, 'modern-screenshot.umd.js');
+      try {
+        res.writeHead(200, {
+          'Content-Type': 'application/javascript',
+          'Cache-Control': 'public, max-age=31536000, immutable',
+        });
+        res.end(fs.readFileSync(vendorPath));
+      } catch {
+        res.writeHead(404); res.end('Vendor script not found');
+      }
+      return;
+    }
+
+    // --- Annotation upload (browser → server, raw PNG body) ---
+    // Client generates the eventId, POSTs the PNG, then POSTs the generate
+    // event with screenshotPath already set. Keeps bytes out of the SSE/poll
+    // bridge and preserves the "one shot from the user's POV" UX.
+    if (p === '/annotation' && req.method === 'POST') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+      const eventId = url.searchParams.get('eventId');
+      if (!eventId || !/^[A-Za-z0-9_-]{1,64}$/.test(eventId)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid eventId' }));
+        return;
+      }
+      if ((req.headers['content-type'] || '').toLowerCase() !== 'image/png') {
+        res.writeHead(415, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Content-Type must be image/png' }));
+        return;
+      }
+      if (!state.sessionDir) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Session dir unavailable' }));
+        return;
+      }
+      const chunks = [];
+      let total = 0;
+      let aborted = false;
+      req.on('data', (c) => {
+        if (aborted) return;
+        total += c.length;
+        if (total > MAX_ANNOTATION_BYTES) {
+          aborted = true;
+          res.writeHead(413, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Payload too large' }));
+          req.destroy();
+          return;
+        }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        if (aborted) return;
+        const absPath = path.join(state.sessionDir, eventId + '.png');
+        try {
+          fs.writeFileSync(absPath, Buffer.concat(chunks));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Write failed: ' + err.message }));
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, path: absPath }));
+      });
+      req.on('error', () => {
+        if (!aborted) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Upload failed' }));
+        }
+      });
+      return;
+    }
+
+    // --- Health ---
+    if (p === '/status') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
+      const sessions = state.sessionStore ? state.sessionStore.listActiveSessions() : [];
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        status: 'ok',
+        port: state.port,
+        connectedClients: state.sseClients.size,
+        pendingEvents: state.pendingEvents.map((entry) => ({
+          id: entry.event?.id,
+          type: entry.event?.type,
+          leased: !!(entry.leaseUntil && entry.leaseUntil > Date.now()),
+          leaseUntil: entry.leaseUntil || null,
+        })),
+        activeSessions: sessions,
+      }));
+      return;
+    }
+
+    if (p === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        status: 'ok', port: state.port, mode: 'variant',
+        hasProjectContext: hasProjectContext(),
+        connectedClients: state.sseClients.size,
+      }));
+      return;
+    }
+
+    // --- Design system (unified v2 response) + raw ---
+    //   /design-system.json    returns both parsed DESIGN.md and .impeccable/design.json
+    //                          sidecar when present. Panel merges them:
+    //                            { present, parsed, sidecar, hasMd, hasSidecar,
+    //                              mdNewerThanJson, parseError?, sidecarError? }
+    //                          - parsed: output of parseDesignMd (frontmatter
+    //                            + six canonical sections) when DESIGN.md exists.
+    //                          - sidecar: .impeccable/design.json contents when present.
+    //                            Expected shape: schemaVersion 2, carrying
+    //                            extensions + components + narrative.
+    //   /design-system/raw     returns DESIGN.md markdown verbatim
+    if (p === '/design-system.json' || p === '/design-system/raw') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+
+      const mdPath = path.join(CONTEXT_DIR, 'DESIGN.md');
+      const jsonPath = resolveDesignSidecarPath(process.cwd(), CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
+      const mdStat = statOrNull(mdPath);
+      const jsonStat = statOrNull(jsonPath);
+
+      if (p === '/design-system/raw') {
+        if (!mdStat) { res.writeHead(404); res.end('Not found'); return; }
+        res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
+        res.end(fs.readFileSync(mdPath, 'utf-8'));
+        return;
+      }
+
+      if (!mdStat && !jsonStat) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ present: false }));
+        return;
+      }
+
+      const response = {
+        present: true,
+        hasMd: !!mdStat,
+        hasSidecar: !!jsonStat,
+        mdNewerThanJson: !!(mdStat && jsonStat && mdStat.mtimeMs > jsonStat.mtimeMs + 1000),
+      };
+
+      if (mdStat) {
+        try {
+          response.parsed = parseDesignMd(fs.readFileSync(mdPath, 'utf-8'));
+        } catch (err) {
+          response.parseError = err.message;
+        }
+      }
+
+      if (jsonStat) {
+        try {
+          response.sidecar = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+        } catch (err) {
+          response.sidecarError = 'Failed to parse .impeccable/design.json: ' + err.message;
+        }
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(response));
+      return;
+    }
+
+    // --- Source file (no-HMR fallback) ---
+    if (p === '/source') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+      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; }
+      let content;
+      try { content = fs.readFileSync(absPath, 'utf-8'); }
+      catch { res.writeHead(404); res.end('File not found'); return; }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(content);
+      return;
+    }
+
+    // --- SSE: server→browser push (replaces WebSocket) ---
+    if (p === '/events' && req.method === 'GET') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      });
+      res.write('data: ' + JSON.stringify({
+        type: 'connected',
+        hasProjectContext: hasProjectContext(),
+      }) + '\n\n');
+
+      state.sseClients.add(res);
+      clearTimeout(state.exitTimer);
+
+      // Keepalive: SSE comment every 30s prevents silent connection drops.
+      const heartbeat = setInterval(() => {
+        try { res.write(': keepalive\n\n'); } catch { clearInterval(heartbeat); }
+      }, SSE_HEARTBEAT_INTERVAL);
+
+      req.on('close', () => {
+        clearInterval(heartbeat);
+        state.sseClients.delete(res);
+        if (state.sseClients.size === 0) {
+          clearTimeout(state.exitTimer);
+          state.exitTimer = setTimeout(() => {
+            if (state.sseClients.size === 0) enqueueEvent({ type: 'exit' });
+          }, 8000);
+        }
+      });
+      return;
+    }
+
+    // --- Browser→server events (replaces WebSocket messages) ---
+    if (p === '/events' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        let msg;
+        try { msg = JSON.parse(body); } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+        if (msg.token !== state.token) {
+          res.writeHead(401, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Unauthorized' }));
+          return;
+        }
+        const error = validateEvent(msg);
+        if (error) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error }));
+          return;
+        }
+        if (state.sessionStore && msg.id) {
+          try {
+            state.sessionStore.appendEvent(msg);
+          } catch (err) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'session_store_append_failed', message: err.message }));
+            return;
+          }
+        }
+        if (msg.type !== 'checkpoint') enqueueEvent(msg);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+      });
+      return;
+    }
+
+    // --- Stop ---
+    if (p === '/stop') {
+      const token = url.searchParams.get('token');
+      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('stopping');
+      shutdown();
+      return;
+    }
+
+    // --- Agent poll ---
+    if (p === '/poll' && req.method === 'GET') {
+      handlePollGet(req, res, url);
+      return;
+    }
+    if (p === '/poll' && req.method === 'POST') {
+      handlePollPost(req, res);
+      return;
+    }
+
+    res.writeHead(404); res.end('Not found');
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Agent poll endpoints (unchanged from WS version)
+// ---------------------------------------------------------------------------
+
+function handlePollGet(req, res, url) {
+  const token = url.searchParams.get('token');
+  if (token !== state.token) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Unauthorized' }));
+    return;
+  }
+  const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
+  const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
+  const available = findAvailablePendingEvent();
+  if (available) {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(leaseEvent(available, leaseMs)));
+    return;
+  }
+  const poll = { resolve, leaseMs };
+  const timer = setTimeout(() => {
+    const idx = state.pendingPolls.indexOf(poll);
+    if (idx !== -1) state.pendingPolls.splice(idx, 1);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ type: 'timeout' }));
+  }, timeout);
+  function resolve(event) {
+    clearTimeout(timer);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(event));
+  }
+  state.pendingPolls.push(poll);
+  scheduleLeaseFlush();
+  req.on('close', () => {
+    clearTimeout(timer);
+    const idx = state.pendingPolls.indexOf(poll);
+    if (idx !== -1) state.pendingPolls.splice(idx, 1);
+  });
+}
+
+function handlePollPost(req, res) {
+  let body = '';
+  req.on('data', (c) => { body += c; });
+  req.on('end', () => {
+    let msg;
+    try { msg = JSON.parse(body); } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Invalid JSON' }));
+      return;
+    }
+    if (msg.token !== state.token) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Unauthorized' }));
+      return;
+    }
+    acknowledgePendingEvent(msg.id);
+    if (state.sessionStore && msg.id) {
+      try {
+        const eventType = msg.type === 'discard' || msg.type === 'discarded'
+          ? 'discarded'
+          : msg.type === 'complete'
+            ? 'complete'
+            : msg.type === 'error'
+              ? 'agent_error'
+              : 'agent_done';
+        state.sessionStore.appendEvent({
+          type: eventType,
+          id: msg.id,
+          file: msg.file,
+          message: msg.message,
+          carbonize: msg.data?.carbonize === true,
+        });
+      } catch { /* keep reply path best-effort; browser still needs SSE */ }
+    }
+    flushPendingPolls();
+    // Forward the reply to the browser via SSE
+    broadcast({ type: msg.type || 'done', id: msg.id, message: msg.message, file: msg.file, data: msg.data });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+let httpServer = null;
+
+function shutdown() {
+  removeLiveServerInfo(process.cwd());
+  if (state.leaseTimer) clearTimeout(state.leaseTimer);
+  state.leaseTimer = null;
+  if (state.sessionDir) {
+    try { fs.rmSync(state.sessionDir, { recursive: true, force: true }); } catch {}
+  }
+  for (const res of state.sseClients) { try { res.end(); } catch {} }
+  state.sseClients.clear();
+  for (const poll of state.pendingPolls) poll.resolve({ type: 'exit' });
+  state.pendingPolls.length = 0;
+  if (httpServer) httpServer.close();
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: node live-server.mjs [options]
+
+Start the live variant mode server (zero dependencies).
+
+Commands:
+  (default)     Start the server (foreground)
+  stop          Stop the server and remove the injected live.js script tag
+  stop --keep-inject   Stop the server only (leave the script tag in the HTML entry)
+
+Options:
+  --background  Start detached, print connection JSON to stdout, then exit
+  --port=PORT   Use a specific port (default: auto-detect starting at 8400)
+  --keep-inject Only with stop: skip live-inject.mjs --remove
+  --help        Show this help
+
+Endpoints:
+  /live.js             Browser script (element picker + variant cycling)
+  /detect.js           Detection overlay (backwards compatible)
+  /modern-screenshot.js Vendored modern-screenshot UMD build (lazy-loaded by live.js)
+  /annotation          POST raw image/png to stage a variant screenshot
+  /events              SSE stream (server→browser) + POST (browser→server)
+  /poll                Long-poll for agent CLI
+  /source              Raw source file reader (no-HMR fallback)
+  /status              Durable recovery status (token-protected)
+  /health              Health check`);
+  process.exit(0);
+}
+
+if (args.includes('stop')) {
+  const keepInject = args.includes('--keep-inject');
+  try {
+    const { info } = readLiveServerInfo(process.cwd()) || {};
+    const res = await fetch(`http://localhost:${info.port}/stop?token=${info.token}`);
+    if (res.ok) console.log(`Stopped live server on port ${info.port}.`);
+  } catch {
+    console.log('No running live server found.');
+  }
+  if (!keepInject) {
+    const injectPath = path.join(__dirname, 'live-inject.mjs');
+    try {
+      const out = execFileSync(process.execPath, [injectPath, '--remove'], {
+        encoding: 'utf-8',
+        cwd: process.cwd(),
+      });
+      const line = out.trim().split('\n').filter(Boolean).pop();
+      if (line) {
+        try {
+          const j = JSON.parse(line);
+          if (j.removed === true) {
+            console.log(`Removed live script tag from ${j.file}.`);
+          }
+        } catch {
+          /* ignore non-JSON lines */
+        }
+      }
+    } catch (err) {
+      const detail = err.stderr?.toString?.().trim?.()
+        || err.stdout?.toString?.().trim?.()
+        || err.message
+        || String(err);
+      console.warn(`Note: could not remove live script tag (${detail.split('\n')[0]})`);
+    }
+  }
+  process.exit(0);
+}
+
+// --background: spawn a detached child server, wait for it to be ready,
+// print the connection JSON, then exit.  This keeps the startup command
+// simple (no shell backgrounding or chained commands).
+if (args.includes('--background')) {
+  const childArgs = args.filter(a => a !== '--background');
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...childArgs], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: process.cwd(),
+  });
+  child.unref();
+
+  // Poll for the PID file (the child writes it once the HTTP server is listening).
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    try {
+      const { info } = readLiveServerInfo(process.cwd()) || {};
+      if (info.pid !== process.pid) {
+        // Output JSON so the agent can read port + token from stdout.
+        console.log(JSON.stringify(info));
+        process.exit(0);
+      }
+    } catch { /* not ready yet */ }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  console.error('Timed out waiting for live server to start.');
+  process.exit(1);
+}
+
+// Check for existing session
+const existingRecord = readLiveServerInfo(process.cwd());
+if (existingRecord?.info) {
+  const existing = existingRecord.info;
+  try {
+    process.kill(existing.pid, 0);
+    console.error(`Live server already running on port ${existing.port} (pid ${existing.pid}).`);
+    console.error('Stop it first with: node ' + path.basename(fileURLToPath(import.meta.url)) + ' stop');
+    process.exit(1);
+  } catch {
+    try { fs.unlinkSync(existingRecord.path); } catch {}
+  }
+}
+
+state.token = randomUUID();
+state.sessionStore = createLiveSessionStore({ cwd: process.cwd() });
+restorePendingEventsFromStore();
+const portArg = args.find(a => a.startsWith('--port='));
+state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
+// Annotation screenshots live in the project root so the agent's Read tool
+// doesn't trip a per-file permission prompt. Sessioned by token so concurrent
+// projects (or quick restarts) don't collide.
+const annotRoot = getLiveAnnotationsDir(process.cwd());
+fs.mkdirSync(annotRoot, { recursive: true });
+state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
+
+const { detectScript, sessionPath, livePath } = loadBrowserScripts();
+httpServer = http.createServer(createRequestHandler({ detectScript, sessionPath, livePath }));
+
+httpServer.listen(state.port, '127.0.0.1', () => {
+  writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
+  const url = `http://localhost:${state.port}`;
+  console.log(`\nImpeccable live server running on ${url}`);
+  console.log(`Token: ${state.token}\n`);
+  console.log(`Inject: <script src="${url}/live.js"><\/script>`);
+  console.log(`Stop:   node ${path.basename(fileURLToPath(import.meta.url))} stop`);
+});
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

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

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

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

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

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

@@ -0,0 +1,632 @@
+/**
+ * CLI helper: find an element in source and wrap it in a variant container.
+ *
+ * Usage:
+ *   npx impeccable wrap --id SESSION_ID --count N --query "hero-combined-left" [--file path]
+ *
+ * Searches project files for the element matching the query (class name, ID, or
+ * text snippet), wraps it with the variant scaffolding, and prints the file path
+ * + line range where the agent should insert variant HTML.
+ *
+ * This replaces 3-4 agent tool calls (grep + read + edit) with a single CLI call.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+
+const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
+
+export async function wrapCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: impeccable wrap [options]
+
+Find an element in source and wrap it in a variant container.
+
+Required:
+  --id ID            Session ID for the variant wrapper
+  --count N          Number of expected variants (1-8)
+
+Element identification (at least one required):
+  --element-id ID    HTML id attribute of the element
+  --classes A,B,C    Comma-separated CSS class names
+  --tag TAG          Tag name (div, section, etc.)
+  --query TEXT       Fallback: raw text to search for
+
+Optional:
+  --file PATH        Source file to search in (skips auto-detection)
+  --text TEXT        Picked element's textContent. Used to disambiguate when
+                     classes/tag match multiple sibling elements (e.g. a list
+                     of <Card>s with the same className). Pass the first ~80
+                     chars of event.element.textContent.
+  --help             Show this help message
+
+Output (JSON):
+  { file, startLine, endLine, insertLine, commentSyntax }
+
+The agent should insert variant HTML at insertLine.`);
+    process.exit(0);
+  }
+
+  const id = argVal(args, '--id');
+  const count = parseInt(argVal(args, '--count') || '3');
+  const elementId = argVal(args, '--element-id');
+  const classes = argVal(args, '--classes');
+  const tag = argVal(args, '--tag');
+  const query = argVal(args, '--query');
+  const filePath = argVal(args, '--file');
+  const text = argVal(args, '--text');
+
+  if (!id) { console.error('Missing --id'); process.exit(1); }
+  if (!elementId && !classes && !query) {
+    console.error('Need at least one of: --element-id, --classes, --query');
+    process.exit(1);
+  }
+
+  // Build search queries in priority order (most specific first)
+  const queries = buildSearchQueries(elementId, classes, tag, query);
+
+  const genOpts = { cwd: process.cwd() };
+
+  // Find the source file. Generated files are excluded from auto-search so we
+  // don't silently write variants into a file the next build will wipe.
+  let targetFile = filePath;
+  let matchedQuery = null;
+  if (!targetFile) {
+    for (const q of queries) {
+      targetFile = findFileWithQuery(q, process.cwd(), genOpts);
+      if (targetFile) { matchedQuery = q; break; }
+    }
+    if (!targetFile) {
+      // Nothing in source. Did the element show up in a generated file? That
+      // tells the agent "fall back to the agent-driven flow" vs "element just
+      // doesn't exist in this project."
+      let generatedHit = null;
+      for (const q of queries) {
+        generatedHit = findFileWithQuery(q, process.cwd(), { ...genOpts, includeGenerated: true });
+        if (generatedHit) break;
+      }
+      if (generatedHit) {
+        console.error(JSON.stringify({
+          error: 'element_not_in_source',
+          fallback: 'agent-driven',
+          generatedMatch: path.relative(process.cwd(), generatedHit),
+          hint: 'Element found only in a generated file. See "Handle fallback" in live.md.',
+        }));
+      } else {
+        console.error(JSON.stringify({
+          error: 'element_not_found',
+          fallback: 'agent-driven',
+          hint: 'Element not found in any project file. It may be runtime-injected (JS component, etc.). See "Handle fallback" in live.md.',
+        }));
+      }
+      process.exit(1);
+    }
+  } else {
+    if (isGeneratedFile(targetFile, genOpts)) {
+      console.error(JSON.stringify({
+        error: 'file_is_generated',
+        fallback: 'agent-driven',
+        file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)),
+        hint: 'Explicit --file points at a generated file. Writing here gets wiped by the next build. See "Handle fallback" in live.md.',
+      }));
+      process.exit(1);
+    }
+    matchedQuery = queries[0];
+  }
+
+  const content = fs.readFileSync(targetFile, 'utf-8');
+  const lines = content.split('\n');
+
+  // Find the element, trying each query in priority order. When `--text` is
+  // supplied, collect every candidate the queries surface and disambiguate
+  // by the picked element's textContent. Without `--text`, fall back to the
+  // legacy first-match behavior so unmodified callers keep working.
+  let match = null;
+  if (text) {
+    const candidates = [];
+    for (const q of queries) {
+      const all = findAllElements(lines, q, tag);
+      for (const c of all) {
+        if (!candidates.some((x) => x.startLine === c.startLine)) {
+          candidates.push(c);
+        }
+      }
+      // Once a more-specific query (ID, full className combo) yielded a unique
+      // result, stop — falling through to the loose tag+single-class query
+      // would readmit the siblings we just disambiguated past.
+      if (candidates.length === 1) break;
+    }
+    if (candidates.length === 0) {
+      console.error(JSON.stringify({ error: 'Found file but could not locate element in ' + targetFile + '. Searched for: ' + queries.join(', ') }));
+      process.exit(1);
+    }
+    if (candidates.length === 1) {
+      match = candidates[0];
+    } else {
+      const filtered = filterByText(candidates, lines, text);
+      if (filtered.length === 1) {
+        match = filtered[0];
+      } else if (filtered.length === 0) {
+        // Source uses dynamic content (`<h1>{title}</h1>` etc.) so the
+        // browser-side textContent doesn't appear literally in source. Fall
+        // back to first-match rather than refusing — this is the same
+        // behavior unmodified callers see, just preserved.
+        match = candidates[0];
+      } else {
+        // Multiple candidates ALSO match the text. Truly ambiguous — refuse
+        // rather than pick wrong, and hand the agent the candidate locations
+        // so it can disambiguate by reading the file.
+        console.error(JSON.stringify({
+          error: 'element_ambiguous',
+          fallback: 'agent-driven',
+          file: path.relative(process.cwd(), targetFile),
+          candidates: filtered.map((c) => ({
+            startLine: c.startLine + 1,
+            endLine: c.endLine + 1,
+          })),
+          hint: 'Multiple source elements match both classes/tag and textContent. Pass --element-id, a more specific --text, or write the wrapper manually. See "Handle fallback" in live.md.',
+        }));
+        process.exit(1);
+      }
+    }
+  } else {
+    for (const q of queries) {
+      match = findElement(lines, q, tag);
+      if (match) break;
+    }
+    if (!match) {
+      console.error(JSON.stringify({ error: 'Found file but could not locate element in ' + targetFile + '. Searched for: ' + queries.join(', ') }));
+      process.exit(1);
+    }
+  }
+
+  const { startLine, endLine } = match;
+  const commentSyntax = detectCommentSyntax(targetFile);
+  const styleMode = detectStyleMode(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  const indent = lines[startLine].match(/^(\s*)/)[1];
+
+  // Extract the original element. Reindent under the wrapper while preserving
+  // the relative depth between lines — `l.trimStart()` would strip ALL leading
+  // whitespace and collapse e.g. `<aside>`/`  <h1>`/`</aside>` (6/8/6 spaces)
+  // to a single uniform indent, so on accept/discard the round-trip restores
+  // the inner element at its parent's depth instead of nested inside it.
+  // Strip only the COMMON minimum leading whitespace across the picked lines;
+  // `deindentContent` on the accept side already mirrors this convention.
+  const originalLines = lines.slice(startLine, endLine + 1);
+  const originalBaseIndent = minLeadingSpaces(originalLines);
+  const reindentOriginal = (extra) => originalLines
+    .map((l) => (l.trim() === '' ? '' : indent + extra + l.slice(originalBaseIndent)))
+    .join('\n');
+  const originalIndented = reindentOriginal('    ');
+
+  // Wrapper attributes differ by syntax. HTML allows plain string attrs;
+  // JSX requires object-literal style and parses string attrs as HTML (which
+  // either type-errors or renders a literal CSS string).
+  const styleContents = isJsx ? 'style={{ display: "contents" }}' : 'style="display: contents"';
+
+  // JSX/TSX guard: the picked element occupies a single JSX child slot
+  // (inside `return (...)`, an array `.map(...)`, an `asChild` branch, or
+  // any other expression position). Replacing it with `comment + <div> +
+  // comment` yields three adjacent siblings — invalid JSX. We can't use a
+  // Fragment `<></>` either: parents that clone children (Radix `asChild`,
+  // Headless UI, etc.) hit "Invalid prop supplied to React.Fragment" when
+  // they try to pass an `id` through.
+  //
+  // Solution: keep the wrapper `<div>` as the single JSX-slot child and
+  // tuck both marker comments INSIDE it. accept/discard then expands its
+  // replacement range to include the wrapper's `<div>` open / close lines
+  // so the entire scaffold gets removed cleanly.
+  const wrapperLines = isJsx ? [
+    indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
+    indent + '  ' + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+    indent + '  ' + commentSyntax.open + ' Original ' + commentSyntax.close,
+    indent + '  <div data-impeccable-variant="original">',
+    reindentOriginal('    '),
+    indent + '  </div>',
+    indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+    indent + '  ' + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+    indent + '</div>',
+  ] : [
+    indent + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+    indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
+    indent + '  ' + commentSyntax.open + ' Original ' + commentSyntax.close,
+    indent + '  <div data-impeccable-variant="original">',
+    originalIndented,
+    indent + '  </div>',
+    indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+    indent + '</div>',
+    indent + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+  ];
+
+  // Replace the original element with the wrapper
+  const newLines = [
+    ...lines.slice(0, startLine),
+    ...wrapperLines,
+    ...lines.slice(endLine + 1),
+  ];
+  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+  // Calculate insert line (the "insert below this line" comment).
+  // 0-indexed file position. Both HTML and JSX wrappers have 6 lines above
+  // the insert marker (HTML: start-comment + outer-div + Original-comment +
+  // original-div + content + close-original-div; JSX: outer-div +
+  // start-comment + Original-comment + original-div + content +
+  // close-original-div). Multi-line originals push the marker by their
+  // extra line count.
+  const insertLine = startLine + 6 + (originalLines.length - 1);
+
+  console.log(JSON.stringify({
+    file: path.relative(process.cwd(), targetFile),
+    startLine: startLine + 1,       // 1-indexed for the agent
+    // wrapperLines is an array but one element (the original-content slot)
+    // is a `\n`-joined multi-line string, so the actual file-row count is
+    // wrapperLines.length + (originalLines.length - 1). Without the offset,
+    // endLine pointed inside the wrapper for any picked element that
+    // spanned more than one source line.
+    endLine: startLine + wrapperLines.length + (originalLines.length - 1), // 1-indexed
+    insertLine: insertLine + 1,     // 1-indexed: where variants go
+    commentSyntax: commentSyntax,
+    styleMode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    cssSelectorPrefixExamples: buildCssSelectorPrefixExamples(styleMode.mode, count),
+    cssAuthoring: buildCssAuthoring(styleMode, count),
+    originalLineCount: originalLines.length,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function argVal(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+/**
+ * Build search query strings in priority order (most specific first).
+ * ID is most reliable, then specific class combos, then single classes, then raw query.
+ */
+function buildSearchQueries(elementId, classes, tag, query) {
+  const queries = [];
+
+  // 1. ID is the most specific
+  if (elementId) {
+    queries.push('id="' + elementId + '"');
+  }
+
+  // 2. Full class attribute match (for elements with distinctive multi-class combos).
+  // Emit both class="..." (HTML) and className="..." (React/JSX) so whichever
+  // convention the file uses will match.
+  if (classes) {
+    const classList = classes.split(',').map(c => c.trim()).filter(Boolean);
+    if (classList.length > 1) {
+      const joined = classList.join(' ');
+      const sorted = [...classList].sort((a, b) => b.length - a.length);
+      queries.push('class="' + joined + '"');
+      queries.push('className="' + joined + '"');
+      queries.push(sorted[0]); // most distinctive single class, fallback
+    } else if (classList.length === 1) {
+      queries.push(classList[0]);
+    }
+  }
+
+  // 3. Tag + class combo (e.g., <section class="hero">).
+  // Same dual-emit for JSX compatibility.
+  if (tag && classes) {
+    const firstClass = classes.split(',')[0].trim();
+    queries.push('<' + tag + ' class="' + firstClass);
+    queries.push('<' + tag + ' className="' + firstClass);
+  }
+
+  // 4. Raw fallback query
+  if (query) {
+    queries.push(query);
+  }
+
+  return queries;
+}
+
+function detectCommentSyntax(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jsx' || ext === '.tsx') {
+    return { open: '{/*', close: '*/}' };
+  }
+  // HTML, Vue, Svelte, Astro all use HTML comments
+  return { open: '<!--', close: '-->' };
+}
+
+function detectStyleMode(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.astro') {
+    return {
+      mode: 'astro-global-prefixed',
+      styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
+    };
+  }
+  return {
+    mode: 'scoped',
+    styleTag: '<style data-impeccable-css="SESSION_ID">',
+  };
+}
+
+function buildCssSelectorPrefixExamples(styleMode, count) {
+  if (styleMode !== 'astro-global-prefixed') return [];
+  return Array.from({ length: count }, (_, i) => `[data-impeccable-variant="${i + 1}"]`);
+}
+
+function buildCssAuthoring(styleMode, count) {
+  const variantNumbers = Array.from({ length: count }, (_, i) => i + 1);
+  if (styleMode.mode === 'astro-global-prefixed') {
+    return {
+      mode: styleMode.mode,
+      styleTag: styleMode.styleTag,
+      strategy: 'global-prefixed',
+      rulePattern: '[data-impeccable-variant="N"] > .variant-class { ... }',
+      selectorExamples: variantNumbers.map((n) => `[data-impeccable-variant="${n}"] > .variant-class`),
+      requirements: [
+        'Use the styleTag exactly; the is:inline attribute is required for this file.',
+        'Prefix every preview selector with the matching [data-impeccable-variant="N"] selector.',
+        'Keep selectors anchored to the generated variant wrapper; do not rely on component CSS scoping for preview rules.',
+      ],
+      forbidden: [
+        'Do not use @scope for this styleMode.',
+      ],
+    };
+  }
+  return {
+    mode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    strategy: 'scope-rule',
+    rulePattern: '@scope ([data-impeccable-variant="N"]) { :scope > .variant-class { ... } }',
+    selectorExamples: variantNumbers.map((n) => `@scope ([data-impeccable-variant="${n}"]) { :scope > .variant-class { ... } }`),
+    requirements: [
+      'Use @scope blocks keyed to each [data-impeccable-variant="N"] wrapper.',
+      'Inside each @scope block, make :scope rules step into the replacement element with a descendant combinator.',
+      'Use the styleTag exactly; do not add framework-specific style attributes unless this object says to.',
+    ],
+    forbidden: [
+      'Do not use global [data-impeccable-variant="N"] selector prefixes for this styleMode.',
+      'Do not add is:inline to the style tag for this styleMode.',
+    ],
+  };
+}
+
+/**
+ * Search project files for the query string (class name, ID, etc.)
+ * Returns the first matching file path, or null.
+ */
+function findFileWithQuery(query, cwd, genOpts = {}) {
+  const searchDirs = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', '.'];
+  const seen = new Set();
+
+  for (const dir of searchDirs) {
+    const absDir = path.join(cwd, dir);
+    if (!fs.existsSync(absDir)) continue;
+    const result = searchDir(absDir, query, seen, 0, genOpts);
+    if (result) return result;
+  }
+  return null;
+}
+
+function searchDir(dir, query, seen, depth, genOpts) {
+  if (depth > 5) return null; // don't go too deep
+  const realDir = fs.realpathSync(dir);
+  if (seen.has(realDir)) return null;
+  seen.add(realDir);
+
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return null; }
+
+  // Check files first
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!EXTENSIONS.includes(ext)) continue;
+
+    const filePath = path.join(dir, entry.name);
+    if (!genOpts.includeGenerated && isGeneratedFile(filePath, genOpts)) continue;
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      if (content.includes(query)) return filePath;
+    } catch { /* skip unreadable files */ }
+  }
+
+  // Then recurse into directories. Always skip node_modules and .git (never
+  // project content). dist/build/out are left to the isGeneratedFile guard so
+  // the includeGenerated second-pass can still find the element there and
+  // report `generatedMatch`.
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const result = searchDir(path.join(dir, entry.name), query, seen, depth + 1, genOpts);
+    if (result) return result;
+  }
+
+  return null;
+}
+
+/**
+ * Regex that matches a tag opener on a line. Allows the tag name to be
+ * followed by whitespace, `>`, `/`, or end-of-line so that multi-line JSX
+ * openers (e.g. `<section\n  className="..."\n>`) are recognised.
+ */
+const OPENER_RE = /<([A-Za-z][A-Za-z0-9]*)(?=[\s/>]|$)/;
+
+/**
+ * Find the element's start and end line in the file.
+ *
+ * `query` is a class name, attribute fragment (`class="..."`, `className="..."`,
+ * `id="..."`), or a raw text snippet. Because a query can appear on a
+ * continuation line of a multi-line tag (e.g. the `className="..."` row of a
+ * `<section\n  className="..."\n>` JSX tag), we walk backward from the match
+ * line to find the actual tag opener. When `tag` is provided, opener candidates
+ * must match that tag name.
+ */
+/**
+ * Return the smallest leading-whitespace count across a set of lines,
+ * ignoring blank lines (whose indent isn't load-bearing). Used to compute
+ * the common base indent of a multi-line picked element so reindenting
+ * under the wrapper preserves the relative depth between lines.
+ */
+function minLeadingSpaces(lines) {
+  let min = Infinity;
+  for (const l of lines) {
+    if (l.trim() === '') continue;
+    const m = l.match(/^(\s*)/);
+    if (m && m[1].length < min) min = m[1].length;
+  }
+  return min === Infinity ? 0 : min;
+}
+
+function findElement(lines, query, tag = null) {
+  // Iterate all matches — the first substring hit isn't always the right one.
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes(query)) continue;
+
+    const stripped = lines[i].trim();
+    if (stripped.startsWith('<!--') || stripped.startsWith('{/*') || stripped.startsWith('//')) continue;
+    // Skip lines already inside a variant wrapper
+    if (lines[i].includes('data-impeccable-variant')) continue;
+
+    const openerLine = findOpenerLine(lines, i, tag);
+    if (openerLine === -1) continue;
+
+    const endLine = findClosingLine(lines, openerLine);
+    return { startLine: openerLine, endLine };
+  }
+
+  return null;
+}
+
+/**
+ * Like findElement, but returns every match. Used for ambiguity detection
+ * when the agent passes --text: when the same className appears on multiple
+ * sibling elements (a list of cards, repeated section variants, etc.),
+ * first-match silently lands on the wrong branch. Returning all matches lets
+ * the caller narrow by textContent or fail with a structured ambiguity error.
+ */
+function findAllElements(lines, query, tag = null) {
+  const out = [];
+  const seen = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes(query)) continue;
+    const stripped = lines[i].trim();
+    if (stripped.startsWith('<!--') || stripped.startsWith('{/*') || stripped.startsWith('//')) continue;
+    if (lines[i].includes('data-impeccable-variant')) continue;
+    const openerLine = findOpenerLine(lines, i, tag);
+    if (openerLine === -1) continue;
+    if (seen.has(openerLine)) continue; // multiple matches inside the same element
+    seen.add(openerLine);
+    const endLine = findClosingLine(lines, openerLine);
+    out.push({ startLine: openerLine, endLine });
+  }
+  return out;
+}
+
+/**
+ * Narrow a candidate set to those whose source body matches a meaningful
+ * prefix of the picked element's textContent. The compare strips tags and
+ * JSX expressions, then checks two whitespace normalizations side-by-side:
+ *
+ *   - single-space ("hero two second card body")
+ *   - no-whitespace ("herotwosecondcardbody")
+ *
+ * Both are needed because `el.textContent` concatenates sibling text without
+ * inserting whitespace (e.g. `<h1>Hero Two</h1><p>Second…</p>` reads as
+ * `"Hero TwoSecond…"`), while the source has whitespace between tags. If
+ * EITHER normalization matches, the candidate keeps. A snippet shorter than
+ * 8 chars after stripping is too weak to disambiguate — the caller falls
+ * back to first-match.
+ */
+function filterByText(candidates, lines, text) {
+  const trimmed = text.replace(/\s+/g, ' ').trim().toLowerCase().slice(0, 80);
+  // Too short to disambiguate. Return [] so the caller's `filtered.length
+  // === 0` branch fires (fall back to first-match) — the previous
+  // `candidates.slice()` return forced `filtered.length > 1` and surfaced
+  // a spurious `element_ambiguous` error on every short-text picker event
+  // with multiple candidates.
+  if (trimmed.length < 8) return [];
+  const targetSpaced = trimmed;
+  const targetCompact = trimmed.replace(/\s+/g, '');
+
+  return candidates.filter((c) => {
+    const body = lines.slice(c.startLine, c.endLine + 1).join(' ');
+    const inner = body
+      .replace(/<[^>]*>/g, ' ')   // strip HTML/JSX tags
+      .replace(/\{[^}]*\}/g, ' ')  // strip JSX expressions
+      .toLowerCase();
+    const sourceSpaced = inner.replace(/\s+/g, ' ').trim();
+    const sourceCompact = inner.replace(/\s+/g, '');
+    return sourceSpaced.includes(targetSpaced) || sourceCompact.includes(targetCompact);
+  });
+}
+
+/**
+ * Resolve a match line to the real tag opener. If the match line itself opens
+ * a tag, return it. Otherwise walk up to 10 lines backward looking for the
+ * first tag opener. If `tag` is specified, the opener must match that tag
+ * name; an opener with a different tag name aborts the backward walk for this
+ * match (we don't jump across element boundaries).
+ *
+ * Returns the line index of the opener, or -1 if none can be resolved.
+ */
+function findOpenerLine(lines, matchLine, tag) {
+  const self = lines[matchLine].match(OPENER_RE);
+  if (self) {
+    if (!tag || self[1] === tag) return matchLine;
+    return -1;
+  }
+  const MAX_BACKWALK = 10;
+  for (let i = matchLine - 1; i >= Math.max(0, matchLine - MAX_BACKWALK); i--) {
+    const opener = lines[i].match(OPENER_RE);
+    if (!opener) continue;
+    if (!tag || opener[1] === tag) return i;
+    // Different tag name than requested — abort; we're inside a non-target opener.
+    return -1;
+  }
+  return -1;
+}
+
+/**
+ * Starting from a line with an opening tag, find the line with the matching
+ * closing tag by counting tag nesting depth.
+ */
+function findClosingLine(lines, start) {
+  const openMatch = lines[start].match(OPENER_RE);
+  if (!openMatch) return start; // caller passed a non-opener; nothing to span
+
+  const tagName = openMatch[1];
+  let depth = 0;
+  const openRe = new RegExp('<' + tagName + '(?=[\\s/>]|$)', 'g');
+  const selfCloseRe = new RegExp('<' + tagName + '[^>]*/>', 'g');
+  const closeRe = new RegExp('</' + tagName + '\\s*>', 'g');
+
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i];
+    const opens = (line.match(openRe) || []).length;
+    const selfCloses = (line.match(selfCloseRe) || []).length;
+    const closes = (line.match(closeRe) || []).length;
+
+    depth += opens - selfCloses - closes;
+
+    if (depth <= 0) return i;
+  }
+
+  // If we can't find the close, return a reasonable guess
+  return Math.min(start + 50, lines.length - 1);
+}
+
+// Auto-execute when run directly (node live-wrap.mjs ...)
+const _running = process.argv[1];
+if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
+  wrapCli();
+}
+
+// Test exports (used by tests/live-wrap.test.mjs)
+export { buildSearchQueries, findElement, findClosingLine, detectCommentSyntax };

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

@@ -0,0 +1,247 @@
+/**
+ * CLI entry point: prepare everything needed to enter the live variant poll loop.
+ *
+ * Does (all in one command):
+ *   1. Check .impeccable/live/config.json (returns config_missing if first-ever run)
+ *   2. Start the live server in the background (or reuse a running one)
+ *   3. Inject the browser script tag into the project's entry file
+ *   4. Read PRODUCT.md / DESIGN.md for project context
+ *   5. Print a single JSON blob with everything the agent needs
+ *
+ * After this, the agent's only remaining steps are:
+ *   - Open the project's live dev/preview URL in the browser (optional, if browser automation exists)—not `serverPort`; that port is the Impeccable helper for /live.js and /poll
+ *   - Enter the poll loop: `node live-poll.mjs`
+ *
+ * Usage:
+ *   node live.mjs                   # Prepare everything, print JSON, exit
+ *   node live.mjs --help
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
+import { resolveFiles } from './live-inject.mjs';
+import { readLiveServerInfo } from './impeccable-paths.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function liveCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: node live.mjs
+
+Prepare everything for live variant mode in a single command:
+  - Checks .impeccable/live/config.json (required, created once per project)
+  - Starts (or reuses) the live server in the background
+  - Injects the browser script tag
+  - Reads PRODUCT.md / DESIGN.md for project context
+
+On success, prints a JSON blob with:
+  { ok, serverPort, serverToken, pageFile, hasContext, context }
+
+On config_missing, prints:
+  { ok: false, error: "config_missing", configPath, hint }
+
+The agent should then:
+  1. If config_missing, create the config and re-run this script
+  2. Optionally open the project's dev/preview URL in the browser (see reference/live.md—not serverPort)
+  3. Enter the poll loop: node live-poll.mjs`);
+    process.exit(0);
+  }
+
+  // 1. Check config (fail fast if missing — no point starting anything else)
+  const checkOut = runScript('live-inject.mjs', ['--check']);
+  const checkResult = safeParse(checkOut);
+  if (!checkResult || !checkResult.ok) {
+    console.log(JSON.stringify(checkResult || { ok: false, error: 'check_failed', raw: checkOut }));
+    process.exit(0);
+  }
+
+  // 2. Start server (or reuse existing)
+  const serverInfo = ensureServerRunning();
+  if (!serverInfo) {
+    console.log(JSON.stringify({ ok: false, error: 'server_start_failed' }));
+    process.exit(1);
+  }
+
+  // 3. Inject the script tag at the current port
+  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)]);
+  const injectResult = safeParse(injectOut);
+  if (!injectResult || !injectResult.ok) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'inject_failed',
+      detail: injectResult || injectOut,
+      serverPort: serverInfo.port,
+    }));
+    process.exit(1);
+  }
+
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
+
+  // 5. Compute drift-heal: compare resolved inject targets against the
+  //    project's HTML files. Orphans are HTML files not covered by config.
+  //    Warning only — the agent decides whether to act.
+  const resolvedFiles = resolveFiles(process.cwd(), checkResult.config);
+  const drift = scanForDrift(process.cwd(), resolvedFiles, checkResult.config);
+
+  // 6. Emit everything the agent needs
+  console.log(JSON.stringify({
+    ok: true,
+    serverPort: serverInfo.port,
+    serverToken: serverInfo.token,
+    pageFiles: resolvedFiles,
+    configDrift: drift,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
+  }, null, 2));
+}
+
+/**
+ * Drift-heal scan. Walks the project for HTML files under common
+ * page-source directories (public/, src/, app/, pages/) and reports any
+ * that aren't covered by the resolved inject targets. This is purely
+ * advisory — the agent can ignore it, or suggest the user add the
+ * orphans to config.files.
+ *
+ * Skipped if config.files already contains at least one glob pattern
+ * covering everything in practice (signaled by the orphan count being 0).
+ */
+function scanForDrift(rootDir, resolvedFiles, config) {
+  const SCAN_ROOTS = ['public', 'src', 'app', 'pages'];
+  const IGNORE_DIRS = new Set([
+    'node_modules', '.git', '.next', '.nuxt', '.svelte-kit', '.astro',
+    '.turbo', '.vercel', '.cache', 'coverage', 'dist', 'build',
+  ]);
+
+  const resolvedSet = new Set(resolvedFiles.map((f) => f.split(path.sep).join('/')));
+
+  // Files matching the user's `exclude` globs are intentional omissions,
+  // not drift. Compile them to regexes so the orphan list stays signal.
+  const userExcludeRegexes = (Array.isArray(config.exclude) ? config.exclude : [])
+    .map((p) => globToRegex(p));
+  const isUserExcluded = (rel) => userExcludeRegexes.some((re) => re.test(rel));
+
+  const orphans = [];
+
+  const walk = (dir, relBase) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const rel = relBase ? `${relBase}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+        walk(path.join(dir, e.name), rel);
+      } else if (e.isFile() && e.name.endsWith('.html')) {
+        if (resolvedSet.has(rel)) continue;
+        if (isUserExcluded(rel)) continue;
+        orphans.push(rel);
+      }
+    }
+  };
+
+  for (const root of SCAN_ROOTS) {
+    const abs = path.join(rootDir, root);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      walk(abs, root);
+    }
+  }
+
+  if (orphans.length === 0) return null;
+  const capped = orphans.slice(0, 20);
+  return {
+    orphans: capped,
+    orphanCount: orphans.length,
+    hint: `${orphans.length} HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like "public/**/*.html".`,
+  };
+}
+
+/**
+ * Same glob-to-regex mapping used by live-inject.mjs. Kept inline here
+ * to avoid a circular import (live-inject.mjs already imports nothing
+ * from live.mjs). The two must stay in sync.
+ */
+function globToRegex(pattern) {
+  let re = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        if (pattern[i + 2] === '/') { re += '(?:.*/)?'; i += 3; }
+        else { re += '.*'; i += 2; }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+      re += '\\' + c;
+      i += 1;
+    } else {
+      re += c;
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function runScript(name, args) {
+  const scriptPath = path.join(__dirname, name);
+  const cmd = `node "${scriptPath}" ${args.map(a => `"${a}"`).join(' ')}`;
+  try {
+    return execSync(cmd, { encoding: 'utf-8', cwd: process.cwd(), timeout: 15_000 });
+  } catch (err) {
+    // execSync throws on non-zero exit; return stdout if any
+    return err.stdout || err.message || '';
+  }
+}
+
+function safeParse(out) {
+  try { return JSON.parse(String(out).trim()); } catch { return null; }
+}
+
+/**
+ * Return { pid, port, token } for the running live server, starting one if needed.
+ */
+function ensureServerRunning() {
+  // Try to reuse an existing server
+  try {
+    const existing = readLiveServerInfo(process.cwd())?.info;
+    if (existing && existing.pid) {
+      try {
+        process.kill(existing.pid, 0); // throws if dead
+        return existing;
+      } catch { /* stale PID file — the server script will clean it up */ }
+    }
+  } catch { /* no PID file */ }
+
+  // Start a new server
+  const out = runScript('live-server.mjs', ['--background']);
+  return safeParse(out);
+}
+
+// ---------------------------------------------------------------------------
+// Auto-execute
+// ---------------------------------------------------------------------------
+
+const _running = process.argv[1];
+if (_running?.endsWith('live.mjs') || _running?.endsWith('live.mjs/')) {
+  liveCli();
+}

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

@@ -0,0 +1,141 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *     contextDir: string,         // absolute path of the directory the files were found in
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ *
+ * Lookup directory resolution (first match wins):
+ *   1. process.env.IMPECCABLE_CONTEXT_DIR (absolute or relative to cwd)
+ *   2. cwd, if PRODUCT.md / DESIGN.md / .impeccable.md is there (back-compat)
+ *   3. Auto-fallback subdirectories of cwd: .agents/context/, then docs/
+ *   4. cwd as a default "no context found" location
+ *
+ * Legacy `.impeccable.md` -> PRODUCT.md migration only fires at cwd root;
+ * fallback directories are read-only as far as auto-rename is concerned.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+const FALLBACK_DIRS = ['.agents/context', 'docs'];
+
+/**
+ * Resolve the directory that holds PRODUCT.md / DESIGN.md for
+ * this project. Exported so other scripts (e.g. live-server.mjs) can read the
+ * design files from the same location the loader uses.
+ */
+export function resolveContextDir(cwd = process.cwd()) {
+  // 1. Explicit override
+  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
+  if (envDir && envDir.trim()) {
+    const trimmed = envDir.trim();
+    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+  }
+
+  // 2. cwd wins if any canonical or legacy file is there. We check legacy too
+  //    so the auto-migration path in loadContext stays predictable.
+  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES, ...LEGACY_NAMES])) {
+    return cwd;
+  }
+
+  // 3. Auto-fallback subdirs. Match if PRODUCT.md or DESIGN.md is present;
+  //    legacy `.impeccable.md` does not pull the lookup into a fallback dir.
+  for (const rel of FALLBACK_DIRS) {
+    const candidate = path.resolve(cwd, rel);
+    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
+      return candidate;
+    }
+  }
+
+  // 4. Nothing found — keep the historical "default to cwd" behaviour so the
+  //    caller's `hasProduct === false` branch still fires the same way.
+  return cwd;
+}
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+  const contextDir = resolveContextDir(cwd);
+
+  // 1. Look for PRODUCT.md (case-insensitive) in the resolved dir
+  let productPath = firstExisting(contextDir, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists at cwd root, rename
+  //    it in place. We only migrate at the root — fallback dirs are read-only
+  //    so we don't surprise users by mutating files under docs/ or .agents/.
+  if (!productPath && contextDir === cwd) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(contextDir, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+    contextDir,
+  };
+}
+
+function firstExisting(dir, names) {
+  for (const name of names) {
+    const abs = path.join(dir, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

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

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Pin/unpin sub-commands as standalone skill shortcuts.
+ *
+ * Usage:
+ *   node <scripts_path>/pin.mjs pin <command>
+ *   node <scripts_path>/pin.mjs unpin <command>
+ *
+ * `pin audit` creates a lightweight /audit skill that redirects to /impeccable audit.
+ * `unpin audit` removes that shortcut.
+ *
+ * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
+ * in the project root and creates/removes the pin in all of them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// All known harness directories
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+// Valid sub-command names
+const VALID_COMMANDS = [
+  'craft', 'teach', 'extract', 'document', 'shape',
+  'critique', 'audit',
+  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
+  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
+  'clarify', 'adapt', 'optimize',
+];
+
+// Marker to identify pinned skills (so unpin doesn't delete user skills)
+const PIN_MARKER = '<!-- impeccable-pinned-skill -->';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an impeccable skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const skillsDir = join(projectRoot, harness, 'skills');
+    // Only pin in harness dirs that already have impeccable installed
+    const impeccableDir = join(skillsDir, 'impeccable');
+    if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
+      dirs.push(skillsDir);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+  const metadataPath = join(__dirname, 'command-metadata.json');
+  if (existsSync(metadataPath)) {
+    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  }
+  return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function generatePinnedSkill(command, metadata) {
+  const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
+  const hint = metadata[command]?.argumentHint || '[target]';
+
+  return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
+
+Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+  const metadata = loadCommandMetadata();
+  const harnessDirs = findHarnessDirs(projectRoot);
+
+  if (harnessDirs.length === 0) {
+    console.log('No harness directories with impeccable installed found.');
+    return false;
+  }
+
+  const content = generatePinnedSkill(command, metadata);
+  let created = 0;
+
+  for (const skillsDir of harnessDirs) {
+    // Check if skill already exists (and isn't a pin)
+    const skillDir = join(skillsDir, command);
+    if (existsSync(skillDir)) {
+      const existingMd = join(skillDir, 'SKILL.md');
+      if (existsSync(existingMd)) {
+        const existing = readFileSync(existingMd, 'utf-8');
+        if (!existing.includes(PIN_MARKER)) {
+          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
+          continue;
+        }
+      }
+    }
+
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+    console.log(`  + ${skillDir}`);
+    created++;
+  }
+
+  if (created > 0) {
+    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+    console.log(`You can now use /${command} directly.`);
+  }
+
+  return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+  const harnessDirs = findHarnessDirs(projectRoot);
+  let removed = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const skillDir = join(skillsDir, command);
+    if (!existsSync(skillDir)) continue;
+
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    // Safety: only remove if it's a pinned skill
+    const content = readFileSync(skillMd, 'utf-8');
+    if (!content.includes(PIN_MARKER)) {
+      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
+      continue;
+    }
+
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  - ${skillDir}`);
+    removed++;
+  }
+
+  if (removed > 0) {
+    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+    console.log(`Use /impeccable ${command} to access it.`);
+  } else {
+    console.log(`No pinned '${command}' shortcut found.`);
+  }
+
+  return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+  console.log('Usage: node pin.mjs <pin|unpin> <command>');
+  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+  process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+  pin(command, root);
+} else {
+  unpin(command, root);
+}