@hegemonart/get-design-done 1.45.0 → 1.47.0

package/scripts/lib/pin/cli.cjs

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * scripts/lib/pin/cli.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Thin CLI over scripts/lib/pin/store.cjs. projectRoot is always process.cwd().
+ *
+ * Usage:
+ *   node cli.cjs pin <skill> [--user]
+ *   node cli.cjs unpin <skill>
+ *   node cli.cjs list
+ *
+ * Exit codes:
+ *   0  action succeeded (at least one file written/removed, or a non-empty list)
+ *   1  nothing done (no harness dirs / nothing to remove / empty list)
+ *   2  error (bad usage, unknown skill, unexpected failure)
+ *
+ * Dependency-free CommonJS. Ships in the npm package; runtime-safe.
+ */
+
+const path = require('path');
+
+const { pinSkill, unpinSkill, listPins } = require('./store.cjs');
+
+function out(msg) {
+  process.stdout.write(msg + '\n');
+}
+function err(msg) {
+  process.stderr.write(msg + '\n');
+}
+
+function usage() {
+  return [
+    'gdd pin - manage pinned skill aliases across installed harness dirs',
+    '',
+    'Usage:',
+    '  node cli.cjs pin <skill> [--user]',
+    '  node cli.cjs unpin <skill>',
+    '  node cli.cjs list',
+    '',
+    'Exit codes: 0 ok / 1 nothing done / 2 error.',
+  ].join('\n');
+}
+
+function runPin(skillId, opts) {
+  const projectRoot = process.cwd();
+  let res;
+  try {
+    res = pinSkill({ projectRoot, skillId, user: Boolean(opts.user) });
+  } catch (e) {
+    err(`pin: ${e.message}`);
+    return 2;
+  }
+  if (res.written.length === 0) {
+    err(`pin: no harness skills dirs found under ${projectRoot}${opts.user ? '' : ' (try --user to create them)'}.`);
+    for (const s of res.skipped) err(`  skipped ${s.config_dir}: ${s.reason}`);
+    return 1;
+  }
+  out(`Pinned "${skillId}" into ${res.written.length} harness dir(s):`);
+  for (const w of res.written) out(`  ${w.config_dir} -> ${path.relative(projectRoot, w.path)}`);
+  for (const s of res.skipped) err(`  skipped ${s.config_dir}: ${s.reason}`);
+  return 0;
+}
+
+function runUnpin(skillId) {
+  const projectRoot = process.cwd();
+  let res;
+  try {
+    res = unpinSkill({ projectRoot, skillId });
+  } catch (e) {
+    err(`unpin: ${e.message}`);
+    return 2;
+  }
+  for (const r of res.refused) err(`  refused ${r.config_dir}: ${r.reason}`);
+  if (res.removed.length === 0) {
+    err(`unpin: no pinned "${skillId}" stubs removed.`);
+    return 1;
+  }
+  out(`Unpinned "${skillId}" from ${res.removed.length} harness dir(s):`);
+  for (const r of res.removed) out(`  ${r.config_dir} -> ${path.relative(projectRoot, r.path)}`);
+  return 0;
+}
+
+function runList() {
+  const projectRoot = process.cwd();
+  let pins;
+  try {
+    pins = listPins(projectRoot);
+  } catch (e) {
+    err(`list: ${e.message}`);
+    return 2;
+  }
+  if (pins.length === 0) {
+    out('No pinned skills found.');
+    return 1;
+  }
+  out(`Pinned skills (${pins.length}):`);
+  for (const p of pins) {
+    out(`  [${p.config_dir}] ${p.alias} -> source=${p.source} (pinned ${p.pinnedAt})`);
+  }
+  return 0;
+}
+
+/**
+ * Pure entry point. argv is the slice AFTER node + script (process.argv.slice(2)).
+ * Returns an exit code; never calls process.exit (so tests can call it directly).
+ */
+function main(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const cmd = args.shift();
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    out(usage());
+    return cmd ? 0 : 2;
+  }
+
+  if (cmd === 'list') {
+    if (args.length) { err(`list: unexpected argument "${args[0]}"`); return 2; }
+    return runList();
+  }
+
+  if (cmd === 'pin' || cmd === 'unpin') {
+    const opts = { user: false };
+    const positionals = [];
+    for (const a of args) {
+      if (a === '--user') opts.user = true;
+      else if (a.startsWith('--')) { err(`${cmd}: unknown flag ${a}`); return 2; }
+      else positionals.push(a);
+    }
+    const skillId = positionals[0];
+    if (!skillId) { err(`${cmd}: missing <skill> argument`); return 2; }
+    if (positionals.length > 1) { err(`${cmd}: unexpected argument "${positionals[1]}"`); return 2; }
+    if (cmd === 'unpin' && opts.user) { err('unpin: --user is not valid for unpin'); return 2; }
+    return cmd === 'pin' ? runPin(skillId, opts) : runUnpin(skillId);
+  }
+
+  err(`unknown command: ${cmd}`);
+  err(usage());
+  return 2;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { main };

package/scripts/lib/pin/harness-detect.cjs

@@ -0,0 +1,75 @@
+'use strict';
+/**
+ * scripts/lib/pin/harness-detect.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Locates the per-harness `skills/` directories under a project root so the pin
+ * store knows where to write / scan pinned skill stubs. Each harness record in
+ * scripts/lib/manifest/harnesses.cjs carries a `config_dir` (e.g. ".claude",
+ * ".cursor", ".codex"); the candidate skills dir for a harness is
+ * `<projectRoot>/<config_dir>/skills`.
+ *
+ * Two surfaces:
+ *   detectHarnessSkillDirs(projectRoot)   -> only the candidates that EXIST on disk
+ *   harnessSkillDirCandidates(projectRoot)-> ALL candidates (existing or not), for
+ *                                            the --user / create flows that may need
+ *                                            to materialize a missing dir.
+ *
+ * Dependency-free CommonJS. Cross-platform: all path joins go through `path`,
+ * never a hardcoded separator. Ships inside the npm package, so it must stay
+ * runtime-safe (no dev-only requires).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const harnesses = require('../manifest/harnesses.cjs');
+
+/**
+ * Build the full candidate list (one entry per harness record), regardless of
+ * whether the directory currently exists. The candidate skills dir for a harness
+ * is `<projectRoot>/<config_dir>/skills`.
+ *
+ * @param {string} projectRoot absolute or relative project root
+ * @returns {Array<{ id: string, config_dir: string, skillsDir: string }>}
+ */
+function harnessSkillDirCandidates(projectRoot) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new TypeError('harnessSkillDirCandidates: projectRoot must be a non-empty string');
+  }
+  const out = [];
+  const seen = new Set();
+  for (const h of harnesses) {
+    if (!h || !h.config_dir) continue;
+    // De-dupe on config_dir so two records pointing at the same dir don't double up.
+    if (seen.has(h.config_dir)) continue;
+    seen.add(h.config_dir);
+    out.push({
+      id: h.id,
+      config_dir: h.config_dir,
+      skillsDir: path.join(projectRoot, h.config_dir, 'skills'),
+    });
+  }
+  return out;
+}
+
+/**
+ * Filter the candidate list to the harness skills dirs that actually exist as
+ * directories under projectRoot.
+ *
+ * @param {string} projectRoot absolute or relative project root
+ * @returns {Array<{ id: string, config_dir: string, skillsDir: string }>}
+ */
+function detectHarnessSkillDirs(projectRoot) {
+  return harnessSkillDirCandidates(projectRoot).filter((c) => {
+    try {
+      return fs.statSync(c.skillsDir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+module.exports = {
+  detectHarnessSkillDirs,
+  harnessSkillDirCandidates,
+};

package/scripts/lib/pin/store.cjs

@@ -0,0 +1,288 @@
+'use strict';
+/**
+ * scripts/lib/pin/store.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Core for "pinning" a gdd skill: writing a small standalone shortcut alias
+ * (a SKILL.md stub) into every installed harness `skills/` dir so the skill is
+ * directly discoverable as its own command in each runtime, plus the inverse
+ * (unpin) and an inventory (listPins).
+ *
+ * The pin marker is exactly:
+ *   <!-- gdd-pinned-skill source=<skillId> -->
+ * and is the FIRST line of every pinned stub. unpin only ever deletes files
+ * carrying this marker, so a hand-written / unrelated SKILL.md is never removed.
+ *
+ * Metadata (name, description, argument-hint, tools) is pulled from the manifest
+ * SoT via readSkills() — NEVER scraped from live frontmatter — so a pinned stub
+ * always reflects the canonical record.
+ *
+ * Writes are atomic: contents go to `<dest>.tmp` then fs.renameSync to the final
+ * path (rename is atomic within a filesystem), so a crash mid-write never leaves
+ * a half-written SKILL.md.
+ *
+ * Dependency-free CommonJS. Cross-platform via `path`. Ships in the npm package,
+ * so it stays runtime-safe (no dev-only requires).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readSkills } = require('../manifest/index.cjs');
+const { detectHarnessSkillDirs, harnessSkillDirCandidates } = require('./harness-detect.cjs');
+
+const MARKER_PREFIX = '<!-- gdd-pinned-skill source=';
+const MARKER_SUFFIX = ' -->';
+
+/** Build the exact marker line for a skill id. */
+function markerFor(skillId) {
+  return `${MARKER_PREFIX}${skillId}${MARKER_SUFFIX}`;
+}
+
+/**
+ * Extract the `source=<id>` skill id from a marker line, or null if the line is
+ * not a gdd pin marker. Tolerates surrounding whitespace.
+ */
+function parseMarker(line) {
+  if (typeof line !== 'string') return null;
+  const trimmed = line.trim();
+  if (!trimmed.startsWith(MARKER_PREFIX) || !trimmed.endsWith(MARKER_SUFFIX)) return null;
+  const inner = trimmed.slice(MARKER_PREFIX.length, trimmed.length - MARKER_SUFFIX.length);
+  const id = inner.trim();
+  return id.length ? id : null;
+}
+
+/** First non-empty line of a text blob (trimmed), or '' if none. */
+function firstNonEmptyLine(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  for (const l of lines) {
+    if (l.trim().length) return l;
+  }
+  return '';
+}
+
+/** Look up a skill record from the manifest SoT by id, or null. */
+function lookupSkill(skillId) {
+  const { skills } = readSkills();
+  for (const r of skills || []) {
+    if (r && r.name === skillId) return r;
+  }
+  return null;
+}
+
+/** Double-quote a YAML scalar, escaping backslashes and quotes. */
+function quote(s) {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/**
+ * Render the pinned stub contents for a skill record. Layout:
+ *   <marker line>
+ *   ---
+ *   name: gdd-<id>
+ *   description: "<desc>"
+ *   argument-hint: "<hint>"   (only when the record has one)
+ *   tools: <tools>            (only when the record has tools)
+ *   ---
+ *   <one-line body pointing at the source skill>
+ *
+ * `name` mirrors the generator: `gdd-<id>` unless the record overrides via
+ * `frontmatter_name`.
+ */
+function renderStub(skillId, rec) {
+  const fmName = rec.frontmatter_name || `gdd-${skillId}`;
+  const lines = [];
+  lines.push(markerFor(skillId));
+  lines.push('---');
+  lines.push(`name: ${fmName}`);
+  lines.push(`description: ${quote(rec.description || '')}`);
+  if (rec.argument_hint != null && String(rec.argument_hint).length) {
+    lines.push(`argument-hint: ${quote(rec.argument_hint)}`);
+  }
+  if (rec.tools != null && String(rec.tools).length) {
+    lines.push(`tools: ${rec.tools}`);
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push(`Pinned alias for the gdd \`${skillId}\` skill. Run the canonical \`${fmName}\` skill; this stub only makes it directly discoverable in this harness.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Atomic write: write to `<dest>.tmp` then rename into place. */
+function atomicWrite(dest, contents) {
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${dest}.tmp`;
+  fs.writeFileSync(tmp, contents, 'utf8');
+  try {
+    fs.renameSync(tmp, dest);
+  } catch (e) {
+    // Clean up the temp file on failure so we never leave a stray .tmp behind.
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+/**
+ * Pin a skill across harness skills dirs.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.skillId
+ * @param {Array<string>} [args.harnesses] optional allow-list of config_dir or harness id; when omitted, all detected dirs
+ * @param {boolean} [args.user] when true, materialize ALL candidate dirs (not just existing ones)
+ * @returns {{ skillId: string, written: Array<{ id, config_dir, path }>, skipped: Array<{ id, config_dir, reason }> }}
+ */
+function pinSkill(args) {
+  const { projectRoot, skillId } = args || {};
+  if (!projectRoot) throw new TypeError('pinSkill: projectRoot is required');
+  if (!skillId) throw new TypeError('pinSkill: skillId is required');
+
+  const rec = lookupSkill(skillId);
+  if (!rec) {
+    throw new Error(`pinSkill: "${skillId}" is not a known skill in scripts/lib/manifest/skills.json`);
+  }
+
+  const all = args.user
+    ? harnessSkillDirCandidates(projectRoot)
+    : detectHarnessSkillDirs(projectRoot);
+
+  const filter = Array.isArray(args.harnesses) && args.harnesses.length
+    ? new Set(args.harnesses)
+    : null;
+  const targets = filter
+    ? all.filter((c) => filter.has(c.config_dir) || filter.has(c.id))
+    : all;
+
+  const contents = renderStub(skillId, rec);
+  const written = [];
+  const skipped = [];
+  for (const t of targets) {
+    const dest = path.join(t.skillsDir, skillId, 'SKILL.md');
+    try {
+      atomicWrite(dest, contents);
+      written.push({ id: t.id, config_dir: t.config_dir, path: dest });
+    } catch (e) {
+      skipped.push({ id: t.id, config_dir: t.config_dir, reason: e.message });
+    }
+  }
+  return { skillId, written, skipped };
+}
+
+/**
+ * Unpin a skill: delete pinned stubs across harness dirs. REFUSES (skips with a
+ * warning) any SKILL.md whose first non-empty line is not the gdd pin marker, so
+ * a hand-authored skill is never deleted.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.skillId
+ * @returns {{ skillId: string, removed: Array<{ id, config_dir, path }>, refused: Array<{ id, config_dir, path, reason }>, missing: Array<{ id, config_dir, path }> }}
+ */
+function unpinSkill(args) {
+  const { projectRoot, skillId } = args || {};
+  if (!projectRoot) throw new TypeError('unpinSkill: projectRoot is required');
+  if (!skillId) throw new TypeError('unpinSkill: skillId is required');
+
+  // Look across every candidate harness dir (existing or not) so we can clean up
+  // stubs even if the surrounding harness dir was partially removed.
+  const candidates = harnessSkillDirCandidates(projectRoot);
+  const removed = [];
+  const refused = [];
+  const missing = [];
+
+  for (const c of candidates) {
+    const file = path.join(c.skillsDir, skillId, 'SKILL.md');
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      missing.push({ id: c.id, config_dir: c.config_dir, path: file });
+      continue;
+    }
+    const marker = parseMarker(firstNonEmptyLine(content));
+    if (marker == null) {
+      refused.push({
+        id: c.id,
+        config_dir: c.config_dir,
+        path: file,
+        reason: 'first non-empty line lacks the gdd-pinned-skill marker - refusing to delete',
+      });
+      continue;
+    }
+    try {
+      fs.unlinkSync(file);
+      // Remove the now-empty alias dir if nothing else lives there.
+      const aliasDir = path.dirname(file);
+      try {
+        if (fs.readdirSync(aliasDir).length === 0) fs.rmdirSync(aliasDir);
+      } catch { /* leave non-empty dir alone */ }
+      removed.push({ id: c.id, config_dir: c.config_dir, path: file });
+    } catch (e) {
+      refused.push({ id: c.id, config_dir: c.config_dir, path: file, reason: e.message });
+    }
+  }
+  return { skillId, removed, refused, missing };
+}
+
+/**
+ * List pinned skills across harness skills dirs.
+ *
+ * Scans each existing harness skills dir for `<alias>/SKILL.md` files whose first
+ * non-empty line carries the gdd pin marker.
+ *
+ * @param {string} projectRoot
+ * @returns {Array<{ id: string, config_dir: string, alias: string, source: string, pinnedAt: string }>}
+ *   `id` is the harness id, `alias` is the on-disk directory name, `source` is the
+ *   pinned source skill id from the marker, `pinnedAt` is the file mtime ISO string.
+ */
+function listPins(projectRoot) {
+  if (!projectRoot) throw new TypeError('listPins: projectRoot is required');
+  const out = [];
+  for (const dir of detectHarnessSkillDirs(projectRoot)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir.skillsDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const file = path.join(dir.skillsDir, e.name, 'SKILL.md');
+      let content;
+      let stat;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+        stat = fs.statSync(file);
+      } catch {
+        continue;
+      }
+      const source = parseMarker(firstNonEmptyLine(content));
+      if (source == null) continue;
+      out.push({
+        id: dir.id,
+        config_dir: dir.config_dir,
+        alias: e.name,
+        source,
+        pinnedAt: stat.mtime.toISOString(),
+      });
+    }
+  }
+  // Stable order: by config_dir then alias for deterministic output.
+  out.sort((a, b) => (a.config_dir === b.config_dir
+    ? a.alias.localeCompare(b.alias)
+    : a.config_dir.localeCompare(b.config_dir)));
+  return out;
+}
+
+module.exports = {
+  pinSkill,
+  unpinSkill,
+  listPins,
+  // exported for the CLI + tests
+  markerFor,
+  parseMarker,
+  renderStub,
+  MARKER_PREFIX,
+  MARKER_SUFFIX,
+};

package/skills/figma-extract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-figma-extract
-description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+description: "Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context."
 ---
 
 # gdd-figma-extract

package/skills/graphify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-graphify
-description: Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation.
+description: "Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation."
 ---
 
 # gdd-graphify

package/skills/list-pins/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: gdd-list-pins
+description: "Lists pinned skill aliases per harness with their source skill and pin timestamp. Use when you want to see which gdd skills have been pinned as standalone shortcuts and where."
+tools: Read, Bash
+---
+
+# /gdd:list-pins
+
+**Role:** Show every pinned skill alias across the installed harness `skills/` directories. For each one, report the harness it lives in, the on-disk alias directory name, the source skill it points at (from the `<!-- gdd-pinned-skill source=<skill> -->` marker), and when it was pinned (the file modification time).
+
+## Steps
+
+1. **Run the list CLI.** Invoke the shipped script (it takes no arguments). The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" list
+    ```
+
+    The CLI scans each harness `skills/` directory under the current project, finds the stubs carrying the gdd pin marker, and prints one line per pinned alias in the form `[<config-dir>] <alias> -> source=<skill> (pinned <timestamp>)`.
+
+2. **Report the result.** Relay the CLI output verbatim. Exit codes: 0 means one or more pinned aliases were found, 1 means none were found (nothing has been pinned yet), 2 means an error.
+
+## Do Not
+
+- Do not scan the harness directories by hand. The CLI already enforces the marker check, so only genuine gdd pins are listed.
+
+## LIST-PINS COMPLETE

package/skills/live/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-live
+description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support."
+argument-hint: "[--variants N] [--resume <session-id>] [url]"
+tools: Read, Write, Edit, Bash, Glob, Grep, Task
+user-invocable: true
+---
+
+# gdd-live - Live In-Browser Design Mode
+
+Pick a DOM element on a running dev server, generate competing design variants, hot-swap them in place, and accept the winner as a real source edit. Every step persists to `.design/live-sessions/<id>.json` so the session survives a crash or a later resume.
+
+The browser-side runtime, the harness-mode gate, the session store, the events feed, the post-check, the scope guard, and the bandit feed are all separate modules under `scripts/lib/live/`. This skill describes the loop and names the module that owns each step; it does not import them.
+
+For the full surface (the Preview MCP tools, the six `live_*` events, the session file, the bandit feed, degraded mode, the scope guard), see `../../reference/live-mode-integration.md`. For the SKILL.md structural contract, see `../../reference/skill-authoring-contract.md`.
+
+---
+
+## Arguments
+
+- `[url]` - the page to drive. Optional. When omitted, detect the dev server and use its root.
+- `--variants N` - how many variants to generate per pick. Default 3.
+- `--resume <session-id>` - reattach to an in-progress session in `.design/live-sessions/`.
+
+---
+
+## BOOT
+
+1. Probe the Preview MCP per `../../connections/preview.md`: `ToolSearch({ query: "Claude_Preview" })`, then `mcp__Claude_Preview__preview_list`. Empty ToolSearch means the MCP is not loaded.
+2. Resolve the harness live mode. The capability signal is `capability_matrix.mcp_support` in `scripts/lib/manifest/harnesses.json`, projected by `scripts/lib/live/harness-mode.cjs` (`liveModeFor(harnessId)`). A `puppeteer` result means full live mode; a `degraded` result means screenshot-only.
+3. If `mcp_support` is false for this harness, or Preview is unavailable, enter DEGRADED mode and say so plainly: variants are generated and captured as static screenshots, with no in-page hot-swap. Skip the INJECT and PICK steps; generate against the file the user names instead.
+4. Detect the dev server. Look for Vite, Next, Bun, or a static server (check `package.json` scripts plus a `preview_list` entry). Record the server descriptor on the session.
+5. Open or create the session via `scripts/lib/live/session-store.cjs` (`.design/live-sessions/<id>.json`). On `--resume`, load the named session (see RESUME).
+
+---
+
+## INJECT
+
+Inject the browser runtime once. Read `RUNTIME_JS` from `scripts/lib/live/runtime.cjs` and evaluate it in the page with `mcp__Claude_Preview__preview_eval`. The runtime is an idempotent IIFE bound to `window.__gddLive`, so a re-inject after navigation rebinds the same singleton rather than stacking listeners. It installs the pick handler and the variant-swap helpers, and stamps the live variant on the element via the `data-gdd-variant` attribute.
+
+---
+
+## PICK
+
+1. Arm the picker (`window.__gddLive.pick()`), then guide the user to click the target element. Use `preview_click` and `preview_inspect` to confirm the element and read its computed styles and bounding box.
+2. Read the pick report back. Its fields are documented in `pickReportShape` (selector, tagName, classList, boundingRect, computedStyle subset, current variant). The selector strategy prefers id, then a data-testid, then a tag plus class plus nth-of-type path.
+3. Emit a `live_pick` event through `scripts/lib/live/events.cjs` and append a `pick` entry to the session.
+
+---
+
+## GENERATE (one batch)
+
+1. Load the relevant Phase 45 canonical reference index FIRST, so variants are grounded in real guidance: the domain index that matches the picked element (for example `../../reference/spatial.md` for layout, `../../reference/interaction.md` for components and a11y, `../../reference/color.md` for color, `../../reference/typography.md` for type, `../../reference/motion.md` for animation).
+2. Generate all N variants in ONE batch (default 3), each a distinct, hypothesis-tagged design direction for the picked element. Do not generate them one at a time.
+3. For each variant: write the change atomically to the implicated source file, then make it live. With HMR running, the file write is enough; otherwise apply the variant in place with `window.__gddLive.swapVariant({ n, style, html })`, which sets `data-gdd-variant="n"` and applies the variant's style or markup.
+
+---
+
+## POST-CHECK
+
+Run the post-check on each variant via `scripts/lib/live/postcheck.cjs`, which invokes `gdd-detect`. Show the findings inline next to each variant. A variant that trips a finding is flagged, NOT auto-rejected: the user still decides. Append a `live_postcheck` event per variant.
+
+---
+
+## ACCEPT / DISCARD
+
+- ACCEPT one variant: apply the chosen variant as the canonical source edit, and revert the others in the page (`window.__gddLive.revert()` on each non-chosen element). Emit a `live_accept` event and feed the outcome to the design-variants bandit via `scripts/lib/live/bandit-feed.cjs` (a dev-time signal). Append an `accept` entry.
+- DISCARD: revert every variant in the page back to its captured original and leave the source untouched. Emit a `live_discard` event and append a `discard` entry.
+
+Either way, persist the result through `scripts/lib/live/session-store.cjs` before continuing.
+
+---
+
+## PERSIST
+
+Every step (boot, pick, generate, post-check, accept, discard) is written to the session file through `scripts/lib/live/session-store.cjs` as it happens. The on-disk event log uses the `pick`, `generate`, `accept`, `discard` kinds; the telemetry stream uses the six `live_*` event types. Writes are atomic, so an interrupted step never leaves a half-written session.
+
+---
+
+## RESUME
+
+With `--resume <session-id>`, load the named session from `.design/live-sessions/`. Only an `in_progress` session is resumable. Offer the user two choices: continue from the last recorded event (report what that was, for example "last pick was the primary button"), or start fresh (open a new session and leave the old one intact). Never silently replay completed events.
+
+---
+
+## SCOPE GUARD
+
+Never write outside the source files implicated by the picked element. Run every proposed write through `scripts/lib/live/scope-guard.cjs`, which maps the picked selector to its owning source files and rejects edits that fall outside them. If a variant would need a change beyond that scope (a shared token, a parent layout, a new dependency), stop and surface it to the user rather than widening the blast radius.
+
+## Constraints
+
+- Do NOT edit files outside the picked element's implicated sources (enforced by the scope guard).
+- Do NOT generate variants one at a time; generate the full batch, then swap.
+- Do NOT auto-reject a variant on a post-check finding; flag it and let the user decide.
+- In DEGRADED mode, state up front that hot-swap is unavailable and fall back to screenshots.
+- Persist before every user-facing prompt so a crash never loses accepted work.
+
+## LIVE COMPLETE