@sun-asterisk/sungen 2.5.0 → 2.5.1

package/src/orchestrator/ai-rules-updater.ts

@@ -41,6 +41,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-capture-figma.md', '.claude/skills/sungen-capture-figma/SKILL.md'],
   ['claude-skill-capture-local.md', '.claude/skills/sungen-capture-local/SKILL.md'],
   ['claude-skill-capture-live.md', '.claude/skills/sungen-capture-live/SKILL.md'],
+  ['claude-skill-figma-source.md', '.claude/skills/sungen-figma-source/SKILL.md'],
 
   // Skills — GitHub Copilot
   ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -55,6 +56,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-capture-figma.md', '.github/skills/sungen-capture-figma/SKILL.md'],
   ['github-skill-sungen-capture-local.md', '.github/skills/sungen-capture-local/SKILL.md'],
   ['github-skill-sungen-capture-live.md', '.github/skills/sungen-capture-live/SKILL.md'],
+  ['github-skill-sungen-figma-source.md', '.github/skills/sungen-figma-source/SKILL.md'],
 ];
 
 export class AIRulesUpdater {

package/src/orchestrator/figma/figma-scaffolder-helpers.ts

@@ -0,0 +1,126 @@
+/**
+ * Internal helpers for figma-scaffolder.ts.
+ * Extracted to keep the main orchestration file under 200 LOC.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Ora } from 'ora';
+import { downloadToPath } from '../../tools/figma/figma-image-downloader';
+import * as FigmaCache from '../../tools/figma/figma-cache';
+
+// ---------------------------------------------------------------------------
+// Name utilities
+// ---------------------------------------------------------------------------
+
+/** Sanitize a Figma frame/variant name to a safe filename (lowercase, dashes). */
+export function sanitizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// Version / stub helpers
+// ---------------------------------------------------------------------------
+
+/** Read generator version from root package.json. Falls back to "sungen". */
+export function readGeneratorVersion(cwd: string): string {
+  try {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
+      if (pkg.version) return `sungen v${pkg.version}`;
+    }
+  } catch {
+    // fall through
+  }
+  return 'sungen';
+}
+
+/** Minimal spec.md stub pointing users to spec_figma.md. */
+export function minimalSpecMd(screenName: string): string {
+  return `# ${screenName} Screen Specification
+
+<!-- This file is the human-authored source of truth. -->
+<!-- spec_figma.md contains auto-generated Figma data — copy useful sections here. -->
+
+## Overview
+- **URL Path:** /${screenName}
+- **Auth Required:** no
+- **Platform:** web
+
+## Sections
+
+<!-- Add sections, fields, validation rules, and business rules here. -->
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Image download orchestration
+// ---------------------------------------------------------------------------
+
+export interface DownloadImagesOptions {
+  cwd: string;
+  fileKey: string;
+  versionId: string;
+  uiDir: string;
+  imageNodeIds: string[];
+  mainNodeId: string;
+  variantNames: string[];
+  /** Pre-warmed cache entries (nodeId → bytes). */
+  cachedImages: Map<string, Buffer>;
+  /** URL map from getImageUrls response (nodeId → signed URL). */
+  imageUrls: Record<string, string | null>;
+  frameBaseName: string;
+  scaleKind: `${number}x`;
+  spinner: Ora;
+}
+
+/**
+ * Download (or copy from cache) images for each node ID.
+ * Returns relative paths (e.g. "ui/login-frame.png") for each successfully written file.
+ */
+export async function downloadImages(opts: DownloadImagesOptions): Promise<string[]> {
+  const imagePaths: string[] = [];
+
+  for (let i = 0; i < opts.imageNodeIds.length; i++) {
+    const nodeId = opts.imageNodeIds[i];
+    const isMain = nodeId === opts.mainNodeId;
+    const nameSuffix = isMain
+      ? opts.frameBaseName
+      : sanitizeName(opts.variantNames[i - 1] ?? `variant-${i}`);
+    const destPath = path.join(opts.uiDir, `${nameSuffix}.png`);
+    const relPath = `ui/${nameSuffix}.png`;
+
+    // Cache hit path
+    if (opts.cachedImages.has(nodeId)) {
+      opts.spinner.start(`Writing cached image: ${nameSuffix}.png`);
+      fs.writeFileSync(destPath, opts.cachedImages.get(nodeId)!);
+      imagePaths.push(relPath);
+      opts.spinner.succeed(`  ui/${nameSuffix}.png (cached)`);
+      continue;
+    }
+
+    const url = opts.imageUrls[nodeId];
+    if (!url) {
+      opts.spinner.warn(`  No image URL for node ${nodeId} — skipping`);
+      continue;
+    }
+
+    opts.spinner.start(`Downloading ui/${nameSuffix}.png…`);
+    try {
+      await downloadToPath(url, destPath);
+      // Cache downloaded bytes for future runs
+      const bytes = fs.readFileSync(destPath);
+      FigmaCache.put(opts.cwd, opts.fileKey, opts.versionId, nodeId, opts.scaleKind, bytes);
+      imagePaths.push(relPath);
+      opts.spinner.succeed(`  ui/${nameSuffix}.png`);
+    } catch {
+      opts.spinner.warn(`  Failed to download ui/${nameSuffix}.png — skipping`);
+    }
+  }
+
+  return imagePaths;
+}

package/src/orchestrator/figma/figma-scaffolder-types.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared input/output types for FigmaScaffolder.
+ * Kept separate to avoid growing figma-client-types.ts beyond its scope.
+ */
+
+export interface FigmaScaffolderOptions {
+  /** Screen name (e.g. "login", "dashboard"). */
+  screenName: string;
+  /** Full Figma share URL. */
+  figmaUrl: string;
+  /** Absolute or cwd-relative working directory. Default: process.cwd(). */
+  cwd?: string;
+  /** When true, bypass cache and re-fetch from Figma API. Default: false. */
+  refresh?: boolean;
+  /** Render scale for PNG export. Default: 2. */
+  scale?: number;
+}
+
+export interface FigmaScaffolderResult {
+  /** Absolute path to the written spec_figma.md. */
+  specFigmaPath: string;
+  /** Absolute paths to downloaded PNG files. */
+  imagePaths: string[];
+  /** True when spec.md was newly created (was not already present). */
+  specMdCreated: boolean;
+}

package/src/orchestrator/figma/figma-scaffolder.ts

@@ -0,0 +1,209 @@
+/**
+ * FigmaScaffolder: orchestrates Figma URL → spec_figma.md + ui/*.png.
+ *
+ * Flow: parseFigmaUrl → assertSafeToUse → loadPat → cache check
+ *       → getFileNodes → filterFigmaNode → getImageUrls → downloadImages
+ *       → renderSpecFigma → write files
+ *
+ * Idempotent: re-running overwrites spec_figma.md and PNGs.
+ * spec.md: written only if absent (never overwritten).
+ * Cache: keyed by file+version+node; bypassed when refresh=true.
+ *
+ * Helpers (image download, name utils, stubs) live in figma-scaffolder-helpers.ts.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ora from 'ora';
+
+import { parseFigmaUrl } from '../../tools/figma/figma-url-parser';
+import { assertSafeToUse, loadPat } from '../../tools/figma/figma-auth';
+import { getFileNodes, getImageUrls } from '../../tools/figma/figma-rest-client';
+import { filterFigmaNode, extractTextLabels, extractVariants } from '../../tools/figma/figma-node-filter';
+import * as FigmaCache from '../../tools/figma/figma-cache';
+import { renderSpecFigma } from './spec-figma-renderer';
+import {
+  sanitizeName,
+  readGeneratorVersion,
+  minimalSpecMd,
+  downloadImages,
+} from './figma-scaffolder-helpers';
+import type { FigmaScaffolderOptions, FigmaScaffolderResult } from './figma-scaffolder-types';
+
+// Max variant images to download in addition to the main frame.
+const MAX_VARIANT_IMAGES = 5;
+
+export class FigmaScaffolder {
+  /**
+   * Orchestrate the full Figma → screen files flow.
+   *
+   * @throws Error with remediation instructions on auth / parse / network failure.
+   */
+  static async run(options: FigmaScaffolderOptions): Promise<FigmaScaffolderResult> {
+    const cwd = options.cwd ?? process.cwd();
+    const refresh = options.refresh ?? false;
+    const scale = options.scale ?? 2;
+    const spinner = ora({ stream: process.stderr });
+
+    // 1. Parse and validate Figma URL
+    const ref = parseFigmaUrl(options.figmaUrl);
+    if (!ref) {
+      throw new Error(
+        `Invalid Figma URL: "${options.figmaUrl}"\n` +
+          'Expected format: https://www.figma.com/design/<KEY>/<name>?node-id=1-23',
+      );
+    }
+    if (!ref.nodeId) {
+      throw new Error(
+        'Figma URL must include a node-id query parameter.\n' +
+          'Select a specific frame in Figma, right-click → "Copy link to selection".',
+      );
+    }
+
+    // 2. Security scan + PAT load
+    spinner.start('Checking Figma auth…');
+    await assertSafeToUse(cwd);
+
+    const pat = loadPat(cwd);
+    if (!pat) {
+      spinner.fail('Figma PAT not found.');
+      throw new Error('Figma PAT is not configured.\nRun: sungen figma auth set');
+    }
+    spinner.succeed('Figma auth OK');
+
+    // 3. Ensure screen directories exist
+    const screenDir = path.join(cwd, 'qa', 'screens', options.screenName);
+    const requirementsDir = path.join(screenDir, 'requirements');
+    const uiDir = path.join(requirementsDir, 'ui');
+    fs.mkdirSync(uiDir, { recursive: true });
+
+    // 4. Resolve node: prefer raw-JSON cache to spare Starter-tier REST quota.
+    // On Figma Starter, `/v1/files/:key/nodes` counts against a tiny daily
+    // bucket (observed Retry-After up to 4+ days). If we already have a
+    // cached raw response, reuse it and skip the call entirely.
+    let versionId: string;
+    let nodeDocument: unknown;
+    let fromCache = false;
+
+    if (!refresh) {
+      const cachedVersion = FigmaCache.findLatestCachedVersion(cwd, ref.fileKey, ref.nodeId);
+      if (cachedVersion) {
+        const cachedRaw = FigmaCache.get(cwd, ref.fileKey, cachedVersion, ref.nodeId, 'raw');
+        if (cachedRaw) {
+          try {
+            nodeDocument = JSON.parse(cachedRaw.toString('utf8'));
+            versionId = cachedVersion;
+            fromCache = true;
+            spinner.info(`Reusing cached Figma node (version ${versionId}) — pass --refresh to re-fetch`);
+          } catch {
+            // Corrupt cache → fall through to API fetch
+          }
+        }
+      }
+    }
+
+    if (!fromCache) {
+      spinner.start(`Fetching Figma node ${ref.nodeId}…`);
+      let nodesResponse: Awaited<ReturnType<typeof getFileNodes>>;
+      try {
+        nodesResponse = await getFileNodes(pat, ref.fileKey, [ref.nodeId]);
+      } catch (err) {
+        spinner.fail('Failed to fetch Figma node.');
+        throw err;
+      }
+
+      versionId = nodesResponse.version;
+      const nodeEntry = nodesResponse.nodes[ref.nodeId];
+      if (!nodeEntry) {
+        spinner.fail(`Node ${ref.nodeId} not found in Figma file.`);
+        throw new Error(
+          `Node "${ref.nodeId}" was not found in file "${ref.fileKey}".\n` +
+            'Check the Figma URL — the node-id may be incorrect.',
+        );
+      }
+      spinner.succeed(`Fetched node: ${nodeEntry.document.name}`);
+      nodeDocument = nodeEntry.document;
+
+      // Persist raw (unfiltered) node JSON for downstream LLM synthesis + future
+      // cache-first runs. Re-runs overwrite atomically.
+      FigmaCache.put(
+        cwd,
+        ref.fileKey,
+        versionId,
+        ref.nodeId,
+        'raw',
+        JSON.stringify(nodeDocument),
+      );
+    }
+
+    // nodeEntry.document shape — trust the cached bytes we wrote earlier.
+    const nodeEntry = { document: nodeDocument as Parameters<typeof filterFigmaNode>[0] };
+
+    // 5. Filter node tree + extract metadata
+    const filteredNode = filterFigmaNode(nodeEntry.document);
+    const textLabels = extractTextLabels(filteredNode);
+    const variants = extractVariants(filteredNode);
+
+    // 6. Resolve image node IDs (main + up to MAX_VARIANT_IMAGES variants)
+    const imageNodeIds = [ref.nodeId, ...variants.slice(0, MAX_VARIANT_IMAGES).map((v) => v.nodeId)];
+    const scaleKind = `${scale}x` as `${number}x`;
+
+    // 7. Warm image cache (skipped when refresh=true)
+    const cachedImages = new Map<string, Buffer>();
+    if (!refresh) {
+      for (const nodeId of imageNodeIds) {
+        const cached = FigmaCache.get(cwd, ref.fileKey, versionId, nodeId, scaleKind);
+        if (cached) cachedImages.set(nodeId, cached);
+      }
+    }
+
+    // 8. Fetch image URLs for uncached nodes
+    const uncachedIds = imageNodeIds.filter((id) => !cachedImages.has(id));
+    let imageUrls: Record<string, string | null> = {};
+    if (uncachedIds.length > 0) {
+      spinner.start(`Fetching image URLs for ${uncachedIds.length} node(s)…`);
+      try {
+        const urlsResponse = await getImageUrls(pat, ref.fileKey, uncachedIds, { scale, format: 'png' });
+        imageUrls = urlsResponse.images;
+      } catch (err) {
+        spinner.fail('Failed to fetch image URLs.');
+        throw err;
+      }
+      spinner.succeed('Image URLs fetched');
+    }
+
+    // 9. Download (or copy from cache) images
+    const frameBaseName = sanitizeName(filteredNode.name);
+    const variantNames = variants.slice(0, MAX_VARIANT_IMAGES).map((v) => v.name);
+    const imagePaths = await downloadImages({
+      cwd, fileKey: ref.fileKey, versionId, uiDir,
+      imageNodeIds, mainNodeId: ref.nodeId, variantNames,
+      cachedImages, imageUrls, frameBaseName, scaleKind, spinner,
+    });
+
+    // 10. Render and write spec_figma.md (always overwritten)
+    spinner.start('Rendering spec_figma.md…');
+    const markdown = renderSpecFigma({
+      filteredNode, variants, textLabels, imagePaths,
+      fileKey: ref.fileKey, nodeId: ref.nodeId, versionId,
+      fetchedAt: new Date().toISOString(),
+      generatorVersion: readGeneratorVersion(cwd),
+    });
+    const specFigmaPath = path.join(requirementsDir, 'spec_figma.md');
+    fs.writeFileSync(specFigmaPath, markdown, 'utf8');
+    spinner.succeed('spec_figma.md written');
+
+    // 11. Write spec.md stub only if absent
+    const specMdPath = path.join(requirementsDir, 'spec.md');
+    const specMdCreated = !fs.existsSync(specMdPath);
+    if (specMdCreated) {
+      fs.writeFileSync(specMdPath, minimalSpecMd(options.screenName), 'utf8');
+      spinner.info('spec.md created (stub — fill in your requirements)');
+    }
+
+    // 12. Evict old cache versions (keep last 3)
+    FigmaCache.bustOldVersions(cwd, ref.fileKey, versionId);
+
+    return { specFigmaPath, imagePaths, specMdCreated };
+  }
+}

package/src/orchestrator/figma/node-path-collapser.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure helper: collapse consecutive repeated segments in a Figma node path.
+ *
+ * Delimiter: " > " (space-angle-space).
+ * Collapsed runs use the multiplication sign × (U+00D7).
+ *
+ * Examples:
+ *   "A > B > C"                              → "A > B > C"          (unchanged)
+ *   "A > B > B > C"                          → "A > B×2 > C"
+ *   "Container > Container > Container > X"  → "Container×3 > X"
+ *   "A > A > A > A > A > B > C"             → "A×5 > B > C"
+ *   "A"                                       → "A"                  (single)
+ *   ""                                        → ""                   (empty)
+ */
+export function collapseNodePath(path: string): string {
+  if (!path) return path;
+
+  const DELIMITER = ' > ';
+  const segments = path.split(DELIMITER);
+
+  const collapsed: string[] = [];
+  let i = 0;
+
+  while (i < segments.length) {
+    const current = segments[i];
+    let count = 1;
+
+    // Count consecutive identical segments
+    while (i + count < segments.length && segments[i + count] === current) {
+      count++;
+    }
+
+    collapsed.push(count > 1 ? `${current}×${count}` : current);
+    i += count;
+  }
+
+  return collapsed.join(DELIMITER);
+}

package/src/orchestrator/figma/spec-figma-renderer.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure function: filtered Figma node → spec_figma.md envelope string.
+ *
+ * The envelope is deterministic and stable across runs: frontmatter,
+ * auto-gen banner, Frame metadata, Screenshots, and a SYNTHESIS marker.
+ * Narrative sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
+ * Data Columns, Navigation) are appended BELOW the marker by the
+ * sungen-figma-source skill, which reads the raw cached node JSON.
+ *
+ * Section renderers live in spec-figma-section-renderers.ts.
+ *
+ * This module never reads from disk or makes network calls.
+ */
+
+import type {
+  FilteredFigmaNode,
+  FigmaTextLabel,
+  FigmaVariantDefinition,
+} from '../../tools/figma/figma-client-types';
+import {
+  renderFrontmatter,
+  renderFrame,
+  renderScreenshots,
+  SYNTHESIS_MARKER,
+} from './spec-figma-section-renderers';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RenderSpecFigmaInput {
+  /** Root filtered node (the requested frame / component). */
+  filteredNode: FilteredFigmaNode;
+  /** Variant definitions from a COMPONENT_SET parent, or [] if none. Kept for compatibility. */
+  variants: FigmaVariantDefinition[];
+  /** Flat text labels extracted from the node tree. Kept for compatibility. */
+  textLabels: FigmaTextLabel[];
+  /** Relative paths of downloaded image files (e.g., ["ui/home.png", "ui/home-dark.png"]). */
+  imagePaths: string[];
+  /** Figma file key. */
+  fileKey: string;
+  /** Node ID in API form (e.g. "1:23"). */
+  nodeId: string;
+  /** Figma file version ID at fetch time. */
+  versionId: string;
+  /** ISO timestamp of when data was fetched. */
+  fetchedAt: string;
+  /** Generator version string (e.g., "sungen v2.4.5"). */
+  generatorVersion: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the deterministic envelope for spec_figma.md.
+ * The LLM synthesis step (sungen-figma-source skill) appends the narrative
+ * sections AFTER the SYNTHESIS_MARKER comment. Re-synthesis replaces
+ * everything from the marker to EOF.
+ *
+ * Pure function — no I/O side effects.
+ */
+export function renderSpecFigma(input: RenderSpecFigmaInput): string {
+  const sections = [
+    renderFrontmatter(input),
+    '',
+    '> Envelope is AUTO-GENERATED. Narrative sections below the marker are LLM-synthesized.',
+    '> To refine, copy useful parts into ../spec.md (authoritative).',
+    '',
+    renderFrame(input.filteredNode),
+    '',
+    renderScreenshots(input.imagePaths),
+    '',
+    SYNTHESIS_MARKER,
+    '',
+  ];
+
+  return sections.join('\n') + '\n';
+}

package/src/orchestrator/figma/spec-figma-section-renderers.ts

@@ -0,0 +1,46 @@
+/**
+ * Section-render helpers for spec-figma-renderer.ts.
+ *
+ * After the shift to LLM-synthesized narrative sections, the envelope only
+ * needs: frontmatter, Frame metadata, Screenshots, and the SYNTHESIS marker.
+ * All prose sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
+ * Data Columns, Navigation) are appended below the marker by the
+ * sungen-figma-source skill.
+ *
+ * Pure — no I/O.
+ */
+
+import type { FilteredFigmaNode } from '../../tools/figma/figma-client-types';
+import type { RenderSpecFigmaInput } from './spec-figma-renderer';
+
+/**
+ * Sentinel comment that separates the deterministic envelope (above) from
+ * the LLM-synthesized narrative (below). Re-synthesis replaces everything
+ * from this marker to EOF.
+ */
+export const SYNTHESIS_MARKER = '<!-- SYNTHESIS-BELOW -->';
+
+export function renderFrontmatter(input: RenderSpecFigmaInput): string {
+  return [
+    '---',
+    'source: figma',
+    `file_key: ${input.fileKey}`,
+    `node_id: ${input.nodeId}`,
+    `figma_version_id: ${input.versionId}`,
+    `fetched_at: ${input.fetchedAt}`,
+    `generator: ${input.generatorVersion}`,
+    '---',
+  ].join('\n');
+}
+
+export function renderFrame(node: FilteredFigmaNode): string {
+  const bb = node.boundingBox;
+  const dims = bb ? `${bb.w}x${bb.h}` : '—';
+  return ['## Frame', `- Name: ${node.name}`, `- Dimensions: ${dims}`, `- Type: ${node.type}`].join('\n');
+}
+
+export function renderScreenshots(imagePaths: string[]): string {
+  if (imagePaths.length === 0) return '## Screenshots\n- (no images downloaded)';
+  const items = imagePaths.map((p, i) => `- \`${p}\` — ${i === 0 ? 'default state' : `variant ${i}`}`);
+  return ['## Screenshots', ...items].join('\n');
+}

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -1,7 +1,7 @@
 ---
 name: add-screen
 description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can capture visuals from Figma (pre-launch) or live page via the capture skills'
-argument-hint: [screen-name] [url-path]
+argument-hint: [screen-name] [url-path] [--figma <url>]
 allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot
 ---
 
@@ -11,37 +11,82 @@ You are adding a new Sungen screen for test generation.
 
 Parse from `$ARGUMENTS`:
 - **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
-- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`)
+- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - optional when `--figma` is provided
+- **--figma \<url\>** — Figma share URL (optional)
+- **--refresh** — bypass Figma cache and re-fetch (optional, use with `--figma`)
+- **--scale \<n\>** — PNG export scale factor, default 2 (optional)
+- **--hi-res** — export at 4× scale, shorthand for `--scale 4` (optional)
 
 If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
-If **path** is missing, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+If **path** is missing and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
 
 ## Steps
 
 ### 1. Scaffold the screen
 
-Run:
+**Standard path (no `--figma`):**
 ```bash
 sungen add --screen <screen> --path <path>
 ```
 
-### 2. Fill spec.md
+**Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
 
-Use `AskUserQuestion`: *"Fill `spec.md` now?"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+Invoke the `sungen-figma-source` skill by running:
+```bash
+sungen add --screen <screen> --figma '<url>' [--path <path>] [--refresh] [--scale <n>]
+# Single-quote the URL — Figma links contain `&` which bash otherwise treats as a background operator.
+```
+
+This CLI command automatically:
+1. Parses the Figma URL and fetches the design node.
+2. Downloads frame + variant PNGs to `qa/screens/<screen>/requirements/ui/`.
+3. Writes `qa/screens/<screen>/requirements/spec_figma.md` (auto-generated, always overwritten on re-run).
+4. Creates `qa/screens/<screen>/requirements/spec.md` stub **only if the file does not already exist** — never overwrites existing human content.
+
+**Important coexistence rules:**
+- `--figma` and `--path` can be passed together: `--path` provides the live URL for `run-test`; `--figma` provides design context.
+- `spec.md` is the human-authored source of truth. Never modify it automatically.
+- `spec_figma.md` is auto-generated — always overwritten; tell the user to copy useful sections into `spec.md`.
+- `--capture` (Playwright screenshot) and `--figma` can be used simultaneously; they produce different outputs.
+
+**If Figma auth is missing**, the command will fail with a message like:
+> Figma PAT is not configured. Run: sungen figma auth set
+
+In that case, guide the user to run `sungen figma auth set` and retry.
 
-If yes → open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
+### 1a. Synthesize narrative sections (Figma branch only)
 
-### 3. Capture visual source
+After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is deterministic but the narrative below the `<!-- SYNTHESIS-BELOW -->` marker is empty. Invoke the `sungen-figma-source` skill to fill it:
 
-Use `AskUserQuestion`: *"Capture a visual reference for this screen?"* — always offer all three so pre-launch projects work:
+1. Read `qa/screens/<screen>/requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter.
+2. Read the cached raw node JSON at `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores).
+3. Follow the skill's 7-section template (Purpose / ASCII Layout / Regions / Actions / Form Fields / Data Columns / Navigation) and **replace** everything from the marker to EOF.
+4. Preserve the envelope above the marker byte-for-byte.
 
+**Review gate.** Before moving on, show the user the synthesized narrative and use `AskUserQuestion`:
+
+- **Approve** — narrative looks right, continue to Step 2
+- **Edit** — user will tweak `spec_figma.md` now; wait for confirmation before continuing
+- **Cancel** — abort; advise the user that `spec.md` was NOT modified and they can re-run `sungen add --figma --refresh` later
+
+### 2. Capture visual source
+
+**If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Use `AskUserQuestion` to offer:
+- **Continue** — Figma visuals are enough (Recommended)
+- **Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture-live` skill)
+
+**If standard path (no `--figma`)** → go straight to source selection. Use `AskUserQuestion`: *"Pick a visual source for this screen:"*
 - **Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
 - **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
-- **Skip** — user will drop images manually into `requirements/ui/` later, or rely on `/sungen:create-test` to prompt again
+- **Skip** — user will drop images manually into `requirements/ui/` later
 
 Each capture skill writes outputs into `qa/screens/<screen>/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill so behavior stays consistent with `/sungen:create-test`.
 
-If the user has additional UI designs (mockups, hand-drawn sketches), suggest copying them to `requirements/ui/` — `sungen-capture-local` will pick them up during `/sungen:create-test`.
+### 3. Fill spec.md
+
+Use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+
+If yes → open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Reference the captured visuals from Step 2 to suggest field names, form elements, and UI states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
 ### 4. Next steps