@sun-asterisk/sungen 2.5.0 → 2.5.2

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-add-screen.md

@@ -1,46 +1,90 @@
 ---
 name: sungen-add-screen
 description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
-argument-hint: '[screen-name] [url-path]'
+argument-hint: '[screen-name] [url-path] [--figma <url>]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
 ---
 
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
+Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.
 
 You are adding a new Sungen screen for test generation.
 
 ## Parameters
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
-- **path** — ${input:path:URL path (e.g., /login, /dashboard)}
+- **path** — ${input:path:URL path (e.g., /login, /dashboard)} — 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)
 
 ## Steps
 
 ### 1. Scaffold the screen
 
+**Standard path (no --figma):**
+
 Run with #tool:terminal:
 ```bash
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
-### 2. Fill spec.md
+**Figma branch (when --figma \<url\> is provided):**
+
+Run with #tool:terminal:
+```bash
+sungen add --screen ${input:screen} --figma <figma-url> [--path ${input:path}] [--refresh] [--scale <n>]
+```
+
+This CLI command automatically:
+1. Parses the Figma URL and fetches the design node.
+2. Downloads frame + variant PNGs to `qa/screens/${input:screen}/requirements/ui/`.
+3. Writes `qa/screens/${input:screen}/requirements/spec_figma.md` (auto-generated, always overwritten on re-run).
+4. Creates `qa/screens/${input: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.
+- `spec.md` is the human-authored source of truth — never modify it automatically.
+- `spec_figma.md` is auto-generated — tell the user to copy useful sections into `spec.md`.
+- `--capture` (Playwright screenshot) and `--figma` can be used simultaneously.
 
-Ask: *"Fill `spec.md` now?"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
+**If Figma auth is missing**, guide the user to run `sungen figma auth set` and retry.
 
-If yes → open `qa/screens/${input: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:
 
-Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
+1. Read `qa/screens/${input:screen}/requirements/spec_figma.md` frontmatter for `file_key`, `node_id`, `figma_version_id`.
+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 ask:
+
+- **1) Approve** — narrative looks right, continue to Step 2
+- **2) Edit** — user will tweak `spec_figma.md` now; wait for confirmation before continuing
+- **3) 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. Offer:
+- **1) Continue** — Figma visuals are enough (Recommended)
+- **2) 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:
 - **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
 - **2) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
-- **3) Skip** — user will drop images manually into `requirements/ui/` later, or rely on `/sungen-create-test` to prompt again
+- **3) Skip** — user will drop images manually into `requirements/ui/` later
 
 Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — 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
+
+Ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
+
+If yes → open `qa/screens/${input: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
 

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-create-test.md

@@ -1,6 +1,6 @@
 ---
 name: sungen-create-test
-description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (20+ scenarios per viewpoint). Uses sungen-gherkin-syntax and sungen-tc-generation skills.'
+description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (tier-based: critical+high first, expand later). Uses sungen-gherkin-syntax and sungen-tc-generation skills.'
 argument-hint: '[screen-name]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
@@ -10,7 +10,7 @@ tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwri
 
 ## Role
 
-You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
+You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
 
 ## Parameters
 
@@ -20,27 +20,32 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 1. Verify `qa/screens/${input:screen}/` exists. If not → run `/sungen-add-screen` first.
 2. Check if `.feature` already has scenarios. If yes → summarize existing coverage and ask: **1) Add new sections**, **2) Add viewpoints to existing sections**, or **3) Replace all**. See `sungen-tc-generation` skill for update mode details.
-3. **Read requirements** — check `qa/screens/${input:screen}/requirements/`:
+3. **Read requirements & resolve visual source** — check `qa/screens/${input:screen}/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
-   - If `ui/` has images → read them for visual context (layout, element positions, states).
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
      - **2) Continue without it** — generate tests from spec and other sources only
-   - Summarize what you found in requirements and present to the user.
-4. **Screen input** (supplements requirements, or is primary source if no requirements):
-   - Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
-     - **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
-     - **2) UI images** (existing screenshots/mockups in `requirements/ui/`) — invoke `sungen-capture-local` skill
-     - **3) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
-   - Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent.
-   - After the capture skill returns, cross-check its output against `spec.md` and flag any discrepancies before moving on.
-5. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
-6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
-7. Show summary and offer next steps:
+
+   **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
+   1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
+   2. If `ui/` has images (`.png`, `.jpg`, etc.) → read them for visual context (layout, element positions, states).
+   3. If neither exists → ask: *"No visual source found. Pick one:"*
+      - **1) Figma PAT** — ask for URL, run `sungen add --screen ${input:screen} --figma '<url>'`, then invoke `sungen-figma-source` skill
+      - **2) Figma MCP** — invoke `sungen-capture-figma` skill
+      - **3) Live page scan** — invoke `sungen-capture-live` skill
+      - **4) Skip** — generate from spec.md only
+
+   **Cross-check**: if both `spec.md` and visual sources exist, flag any discrepancies (missing fields, different labels) before moving on. When `spec_figma.md` is present, follow the Figma supplement rules in `sungen-tc-generation` skill (reading order, Text Inventory, conflict handling).
+
+   Summarize what you found in requirements and present to the user.
+
+4. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
+5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+6. Show summary and offer next steps:
 
 - **`/sungen-review ${input:screen}`** — Review syntax, coverage, viewpoint quality (Recommended)
 - **`/sungen-run-test ${input:screen}`** — Skip review, generate selectors and run tests now
-- **`/sungen-create-test ${input:screen}`** — Add more test cases for another section/viewpoint
+- **`/sungen-create-test ${input:screen}`** — Expand coverage: add @normal + @low scenarios
 - **Done for now** — I'll come back later
 
 **No selectors.yaml** — selectors are generated during `/sungen-run-test`.

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-delivery.md

@@ -1,8 +1,8 @@
 ---
-name: delivery
+name: sungen-delivery
 description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
 argument-hint: "[screen-name...] (omit for all screens)"
-allowed-tools: Bash, Read, AskUserQuestion
+tools: [read, execute, edit, vscode/askQuestions]
 ---
 
 ## Role

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-review.md

@@ -20,9 +20,10 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 1. Read `qa/screens/${input:screen}/features/${input:screen}.feature` and `qa/screens/${input:screen}/test-data/${input:screen}.yaml`. If missing → `/sungen-create-test` first.
 2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). Use `sungen-viewpoint` for pattern checklists.
-3. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
-4. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
-5. After PASS (or user decides to proceed), offer next steps:
+3. **Unverified Selectors check** — if `qa/screens/${input:screen}/selectors/${input:screen}.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric (see `sungen-tc-review` skill for report format). Does NOT affect the 60% threshold.
+4. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
+5. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
+6. After PASS (or user decides to proceed), offer next steps:
 
 - **`/sungen-run-test ${input:screen}`** — Generate selectors, compile, and run tests (Recommended)
 - **`/sungen-create-test ${input:screen}`** — Add more test cases before running

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -1,8 +1,8 @@
 ---
-name: run-test
+name: sungen-run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: [screen-name]
-allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
+argument-hint: '[screen-name]'
+tools: [read, execute, edit, vscode/askQuestions, playwright/*]
 ---
 
 ## Role
@@ -16,7 +16,39 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
-2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
+2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
+
+   ```
+   Phase 0 — Selector Generation decision tree
+
+   Live page reachable? (URL provided and loads without error)
+     YES → existing flow: browser_navigate → one browser_snapshot → generate selectors.yaml (verified entries)
+     NO  → spec_figma.md exists in requirements/?
+             YES → provisional flow (sungen-figma-source + sungen-selector-fix skills):
+                   1. Read filtered Figma node data from spec_figma.md (## Components + ## Text Inventory)
+                   2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
+                   3. Write selectors.yaml — every provisional entry gets this comment on the line above:
+                          # @needs-live-verify source=figma node_id=<id>
+                   4. Compile: sungen generate --screen <screen> — must succeed
+                   5. Phase 1 smoke check runs; tests using unverified selectors may fail
+                      → auto-fix triggers on next run-test invocation when a live page is available
+             NO  → hard stop: print the following message and stop:
+                   "Cannot generate selectors: no live page URL and no spec_figma.md found.
+                    Options:
+                    • Provide the live URL so Playwright MCP can snapshot the page, OR
+                    • Run: sungen add --screen <screen> --figma <figma-url>  to generate spec_figma.md first"
+   ```
+
+   **Auto-fix on subsequent runs**: when `run-test` is invoked again with a reachable live page, Phase 0 compares the DOM snapshot against existing `selectors.yaml` entries. Entries tagged `# @needs-live-verify` are treated as candidates — if the actual selector differs, the entry is replaced and the comment removed (entry becomes verified). Entries that already match are also promoted to verified (comment removed).
+
+   **`@needs-live-verify` comment format** (one comment line, directly above the YAML key):
+   ```yaml
+   # @needs-live-verify source=figma node_id=<figma-node-id>
+   submit-button:
+     type: role
+     value: button
+     name: "Submit"
+   ```
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
 4. Compile: `sungen generate --screen <screen>` (default: runtime data loading from YAML). Use `--inline-data` only if user requests compile-time hardcoded values.
 

package/dist/orchestrator/templates/ai-instructions/copilot-config.md

@@ -19,6 +19,7 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-capture-figma` | Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP |
 | `sungen-capture-local` | Load existing UI assets (screenshots, mockups, Figma exports) from `requirements/ui/` |
 | `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
+| `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
 
 ## Workflow (5 AI commands)
 

package/dist/orchestrator/templates/ai-instructions/copilot-skill-figma-source.md

@@ -0,0 +1,151 @@
+---
+name: sungen-figma-source
+description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
+user-invocable: false
+---
+
+## When This Skill Loads
+
+Auto-load triggers (any one is sufficient):
+
+- Any sungen AI command invoked with `--figma` flag
+- `requirements/spec_figma.md` exists in the screen directory
+- User mentions a Figma URL or says "generate from Figma"
+
+---
+
+## Prerequisites
+
+- [ ] `sungen figma auth check` succeeds — PAT is stored and valid
+- [ ] Figma file URL is available (shared file or frame link)
+- [ ] If auth missing → run `sungen figma auth set` and follow the walkthrough
+
+**Never paste the PAT into any transcript, spec file, or commit.**
+
+---
+
+## Two-Layer Architecture
+
+`spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
+
+| Layer | Producer | Overwrite Rule |
+|---|---|---|
+| **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
+| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
+
+The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
+
+---
+
+## Inputs You Read
+
+The scaffolder persists a raw (unfiltered) Figma node tree to:
+
+```
+.sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
+```
+
+Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
+
+---
+
+## Synthesis Task
+
+Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
+
+### 1. Purpose
+One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
+
+### 2. ASCII Layout
+Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
+
+```
+┌──────────────────────────────────────┐
+│ [Logo]                     [Sign In] │
+├──────────────────────────────────────┤
+│  Welcome back                        │
+│  ┌────────────────────────────────┐  │
+│  │ email@example.com              │  │
+│  └────────────────────────────────┘  │
+│  [ Continue ]                        │
+└──────────────────────────────────────┘
+```
+
+### 3. Regions
+Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
+
+### 4. Actions
+Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
+
+```
+- **<Action name>** — <what it does> (source: <node name>)
+```
+
+### 5. Form Fields
+Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
+
+```
+| Label | Type | Required | Placeholder |
+|---|---|---|---|
+```
+
+Omit entirely (write `_none_`) if no inputs exist.
+
+### 6. Data Columns
+If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
+
+### 7. Navigation
+Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
+
+---
+
+## Synthesis Workflow
+
+1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
+2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
+3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
+4. Produce the 7 sections above
+5. **Locate the insertion point** in `spec_figma.md`:
+   - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
+   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
+   - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
+6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
+
+---
+
+## Re-synthesis
+
+- If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
+- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
+- Never edit content ABOVE the marker — that is the scaffolder's territory
+
+---
+
+## Selector Heuristics (for downstream `run-test`)
+
+During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
+
+| Figma Signal | Provisional YAML Entry |
+|---|---|
+| Node name ends `Button`, has text | `role: button` + `name: "<text>"` |
+| Node name ends `Input`/`Field` | `placeholder: "<placeholder text>"` |
+| Node name ends `Link`, has text | `role: link` + `name: "<text>"` |
+| componentProperties has `data-testid` | `testid: <value>` |
+| Plain text leaf (outside interactive) | `text: "<content>"` |
+| Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
+
+Every provisional entry MUST carry:
+
+```
+# @needs-live-verify source=figma node_id=<id>
+```
+
+Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
+
+---
+
+## Security
+
+- Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file
+- Never log or echo the PAT in terminal output
+- Read only from `.sungen/figma-cache/` and screen directories — never from `.env`

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-figma-source.md

@@ -0,0 +1,151 @@
+---
+name: sungen-figma-source
+description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
+user-invocable: false
+---
+
+## When This Skill Loads
+
+Auto-load triggers (any one is sufficient):
+
+- Any sungen AI command invoked with `--figma` flag
+- `requirements/spec_figma.md` exists in the screen directory
+- User mentions a Figma URL or says "generate from Figma"
+
+---
+
+## Prerequisites
+
+- [ ] `sungen figma auth check` succeeds — PAT is stored and valid
+- [ ] Figma file URL is available (shared file or frame link)
+- [ ] If auth missing → run `sungen figma auth set` and follow the walkthrough
+
+**Never paste the PAT into any transcript, spec file, or commit.**
+
+---
+
+## Two-Layer Architecture
+
+`spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
+
+| Layer | Producer | Overwrite Rule |
+|---|---|---|
+| **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
+| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
+
+The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
+
+---
+
+## Inputs You Read
+
+The scaffolder persists a raw (unfiltered) Figma node tree to:
+
+```
+.sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
+```
+
+Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
+
+---
+
+## Synthesis Task
+
+Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
+
+### 1. Purpose
+One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
+
+### 2. ASCII Layout
+Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
+
+```
+┌──────────────────────────────────────┐
+│ [Logo]                     [Sign In] │
+├──────────────────────────────────────┤
+│  Welcome back                        │
+│  ┌────────────────────────────────┐  │
+│  │ email@example.com              │  │
+│  └────────────────────────────────┘  │
+│  [ Continue ]                        │
+└──────────────────────────────────────┘
+```
+
+### 3. Regions
+Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
+
+### 4. Actions
+Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
+
+```
+- **<Action name>** — <what it does> (source: <node name>)
+```
+
+### 5. Form Fields
+Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
+
+```
+| Label | Type | Required | Placeholder |
+|---|---|---|---|
+```
+
+Omit entirely (write `_none_`) if no inputs exist.
+
+### 6. Data Columns
+If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
+
+### 7. Navigation
+Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
+
+---
+
+## Synthesis Workflow
+
+1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
+2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
+3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
+4. Produce the 7 sections above
+5. **Locate the insertion point** in `spec_figma.md`:
+   - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
+   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
+   - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
+6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
+
+---
+
+## Re-synthesis
+
+- If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
+- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
+- Never edit content ABOVE the marker — that is the scaffolder's territory
+
+---
+
+## Selector Heuristics (for downstream `run-test`)
+
+During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
+
+| Figma Signal | Provisional YAML Entry |
+|---|---|
+| Node name ends `Button`, has text | `role: button` + `name: "<text>"` |
+| Node name ends `Input`/`Field` | `placeholder: "<placeholder text>"` |
+| Node name ends `Link`, has text | `role: link` + `name: "<text>"` |
+| componentProperties has `data-testid` | `testid: <value>` |
+| Plain text leaf (outside interactive) | `text: "<content>"` |
+| Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
+
+Every provisional entry MUST carry:
+
+```
+# @needs-live-verify source=figma node_id=<id>
+```
+
+Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
+
+---
+
+## Security
+
+- Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file
+- Never log or echo the PAT in terminal output
+- Read only from `.sungen/figma-cache/` and screen directories — never from `.env`

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -52,6 +52,67 @@ If existing selectors already cover the feature file, **skip Phase 0** and go st
 
 ---
 
+## Phase 0 (Provisional): Figma-Only Selector Generation (no live page)
+
+**Trigger**: Phase 0 decision tree (in `run-test` command) determined the live page is not reachable AND `requirements/spec_figma.md` exists.
+
+**Goal**: produce a compilable `selectors.yaml` seeded from Figma node data so that `sungen generate` succeeds and the test suite can run. Every entry is provisional — it must be verified against a real DOM when the page becomes available.
+
+### Inputs
+
+- `requirements/spec_figma.md` — specifically:
+  - `## Components` table (Name, Type, Role, Text, Variants columns)
+  - `## Text Inventory` list (node_id → label text pairs)
+
+### Steps
+
+1. **Parse references**: collect every `[Reference]` element from the `.feature` file (same as live Phase 0 step 2).
+2. **Match to Figma nodes**: for each `[Reference]`, find the best matching entry in `spec_figma.md` by comparing the reference name against component names and text labels (case-insensitive, partial match allowed).
+3. **Apply heuristic priority** (same order as live Phase 0 — use first applicable):
+
+   | Priority | Type | Figma Signal |
+   |---|---|---|
+   | 1 | `testid` | Dev annotation `data-testid=X` in component metadata |
+   | 2 | `role` + name | Component type is Button/Link + has text label |
+   | 3 | `placeholder` | Component type is Input/Field + has placeholder text |
+   | 4 | `label` | Component has associated label text (not placeholder) |
+   | 5 | `locator` (CSS) | No accessible name derivable from Figma data |
+   | 6 | `text` | Plain text node (not inside interactive component) |
+
+   See `sungen-figma-source` skill for the authoritative heuristics table mapping Figma signals to YAML entry types.
+
+4. **Write entries**: add each entry to `selectors.yaml`, prefixed with the required comment:
+   ```yaml
+   # @needs-live-verify source=figma node_id=<figma-node-id>
+   submit-button:
+     type: role
+     value: button
+     name: "Submit"
+   ```
+   - Key naming follows `sungen-selector-keys` conventions (lowercase, Unicode preserved, `--type` / `--N` suffixes).
+   - Copy text character-for-character from `## Text Inventory`. Never infer from the Gherkin label.
+   - Merge, don't overwrite — preserve the page selector and any user-authored entries.
+
+5. **Compile**: `sungen generate --screen <screen>` — must succeed before Phase 1.
+
+### Auto-fix on live page (subsequent run-test invocations)
+
+When `run-test` is called again and the live page is now reachable:
+- Phase 0 takes ONE `browser_snapshot`.
+- For each entry tagged `# @needs-live-verify` in `selectors.yaml`:
+  - Compare the provisional selector against the actual DOM element found in the snapshot.
+  - If match → remove the comment line (entry promoted to verified).
+  - If mismatch → replace the YAML value with the snapshot-derived selector, then remove the comment (entry corrected and verified).
+- Entries with no corresponding DOM element → log as unresolved, leave comment in place for manual inspection.
+
+### Pitfalls
+
+- Inferring selector names from Gherkin labels instead of Figma `## Text Inventory` → mismatch on live verification.
+- Omitting `# @needs-live-verify` comment → reviewer has no way to count unverified selectors.
+- Overwriting user-authored selectors during merge → always check for existing keys before adding.
+
+---
+
 ## Phase 0.5: Auth Persistence (MCP alternative to `sungen makeauth`)
 
 Capture an authenticated session from the MCP browser into `specs/.auth/<role>.json` — the same path `sungen makeauth` writes to, which compiled tests already reference via `test.use({ storageState })` based on `@auth:<role>` tags. No `playwright.config.ts` edits needed. Run once per auth lifetime, not on every selector fix.