@sun-asterisk/sungen 2.6.1 → 2.6.3

package/src/dashboard/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Schemas for the sungen dashboard snapshot.
+ *
+ * A snapshot is a self-describing JSON document that powers a single render
+ * of qa/dashboard/index.html. Past snapshots live in qa/dashboard/history/.
+ */
+
+export const SNAPSHOT_VERSION = 1 as const;
+
+export interface DashboardSnapshot {
+  version: typeof SNAPSHOT_VERSION;
+  runId: string;                       // ISO-ish: 2026-04-28T10-32-15Z (filename-safe)
+  generatedAt: string;                 // full ISO timestamp
+  environment: SnapshotEnvironment;
+  summary: AggregateSummary;
+  screens: ScreenSnapshot[];
+}
+
+export interface SnapshotEnvironment {
+  baseURL: string;
+  projectName: string;
+  executor: string;
+  sungenVersion: string;
+  gitBranch?: string;
+  gitSha?: string;
+}
+
+export interface AggregateSummary {
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+  na: number;
+  notCompiled: number;
+  passRate: number;                    // 0..1, only counting executed (passed+failed)
+  byPriority: Record<string, number>;  // Critical/High/Normal/Low
+  byCategory: Record<string, number>;  // Accessing/GUI/Function
+  byType: Record<string, number>;      // Auto/Manual/Not compiled
+}
+
+export interface ScreenSnapshot {
+  name: string;                        // "kudos" or "flow/checkout"
+  isFlow: boolean;
+  featureName: string;
+  featurePath?: string;
+  specLink?: string;                   // relative path to requirements/spec.md
+  summary: ScreenSummaryStats;
+  scenarios: ScenarioSnapshot[];
+}
+
+export interface ScreenSummaryStats {
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+  na: number;
+  notCompiled: number;
+  passRate: number;
+}
+
+export interface ScenarioSnapshot {
+  tcId: string;                        // KUDOS-UI-001
+  category1: string;                   // scenario name (VP-prefix stripped)
+  category2: string;                   // Accessing | GUI | Function
+  category3: string;                   // feature name
+  category4: string;                   // screen name
+  vpId?: string;                       // VP-UI-001 if present
+  priority: 'Critical' | 'High' | 'Normal' | 'Low';
+  type: 'Auto' | 'Manual' | 'Not compiled';
+  status: 'Passed' | 'Failed' | 'Pending' | 'N/A';
+  tags: string[];
+  precondition: string;
+  testData: string;
+  steps: string[];                     // numbered, one entry per step
+  expectedResults: string[];
+  duration?: number;                   // ms
+  errorMessage?: string;
+  tracePath?: string;
+  executedDate?: string;               // dd/mm/yyyy
+  testEnvironment?: string;
+  testExecutor?: string;
+}
+
+// ----------------------------------------------------------------------------
+// Diff schemas (Phase 2 will populate these in the dashboard UI from history)
+// ----------------------------------------------------------------------------
+
+export interface SnapshotDiff {
+  baseRunId: string;
+  headRunId: string;
+  summary: DiffSummary;
+  screens: ScreenDiff[];
+  tests: TestDiff[];
+}
+
+export interface DiffSummary {
+  added: number;
+  removed: number;
+  newlyPassing: number;
+  newlyFailing: number;
+  statusChanged: number;
+  priorityChanged: number;
+  totalDelta: number;                  // head.total - base.total
+  passRateDelta: number;               // head - base
+}
+
+export interface ScreenDiff {
+  name: string;
+  totalDelta: number;
+  passedDelta: number;
+  failedDelta: number;
+  passRateDelta: number;
+  isNew: boolean;
+  isRemoved: boolean;
+}
+
+export interface TestDiff {
+  tcId: string;
+  screen: string;
+  changeType:
+    | 'added'
+    | 'removed'
+    | 'newly_passing'
+    | 'newly_failing'
+    | 'status_changed'
+    | 'priority_changed'
+    | 'unchanged';
+  baseStatus?: ScenarioSnapshot['status'];
+  headStatus?: ScenarioSnapshot['status'];
+  basePriority?: ScenarioSnapshot['priority'];
+  headPriority?: ScenarioSnapshot['priority'];
+  category1: string;
+}
+
+// ----------------------------------------------------------------------------
+// Wire-format embedded into the HTML template
+// ----------------------------------------------------------------------------
+
+/**
+ * The single payload injected into qa/dashboard/index.html at build time.
+ * Holds the current snapshot plus all retained history runs (max 10).
+ *
+ * The dashboard UI reads `window.__SUNGEN_DASHBOARD__` at boot.
+ */
+export interface DashboardPayload {
+  current: DashboardSnapshot;
+  history: DashboardSnapshot[];        // oldest → newest, current excluded
+}

package/src/exporters/json-exporter.ts

@@ -0,0 +1,162 @@
+/**
+ * Convert merged Gherkin/spec/results data → structured JSON for the dashboard.
+ *
+ * Mirrors csv-exporter's buildTestCaseRows / buildSummary, but emits the
+ * richer ScenarioSnapshot / ScreenSnapshot shape used by the dashboard UI.
+ */
+
+import { MergedScenario } from './scenario-merger';
+import {
+  extractAuthRole,
+  extractPriority,
+  extractTestcaseType,
+  generateTcId,
+  mapVpToCategory2,
+  splitVpAndName,
+} from './feature-parser';
+import { formatPrecondition, cleanStepLine } from './step-formatter';
+import { formatTestData } from './test-data-resolver';
+import {
+  formatExecutedDate,
+  statusToTestResult,
+} from './playwright-report-parser';
+import { EnvironmentInfo, PlaywrightResult } from './types';
+import {
+  ScenarioSnapshot,
+  ScreenSnapshot,
+  ScreenSummaryStats,
+} from '../dashboard/types';
+
+export interface BuildScreenSnapshotInput {
+  screen: string;
+  isFlow: boolean;
+  featureName: string;
+  featurePath?: string;
+  specLink?: string;
+  merged: MergedScenario[];
+  testData: Record<string, string>;
+  results: Map<string, PlaywrightResult> | null;
+  env: EnvironmentInfo;
+}
+
+/**
+ * Build a ScreenSnapshot from merged scenarios.
+ */
+export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnapshot {
+  const scenarios: ScenarioSnapshot[] = [];
+  let fallbackIndex = 1;
+
+  for (const m of input.merged) {
+    const { vpId, category1 } = splitVpAndName(m.feature.name);
+    const tcId = generateTcId(input.screen, vpId, fallbackIndex);
+    if (!vpId) fallbackIndex++;
+
+    const category2 = mapVpToCategory2(vpId);
+    const priority = extractPriority(m.feature.tags) as ScenarioSnapshot['priority'];
+    const baseType = extractTestcaseType(m.feature.tags);
+    const authRole = extractAuthRole(m.feature.tags);
+
+    let stepsRaw: string[];
+    let expectedRaw: string[];
+    let givenForPrecondition: string[];
+
+    if (m.spec) {
+      givenForPrecondition = m.spec.precondition;
+      stepsRaw = m.spec.steps;
+      expectedRaw = m.spec.expectations;
+    } else {
+      givenForPrecondition = m.feature.rawGivenSteps;
+      stepsRaw = m.feature.rawWhenSteps;
+      expectedRaw = m.feature.rawThenSteps;
+    }
+
+    const precondition = formatPrecondition(authRole, givenForPrecondition);
+    const steps = stepsRaw.map(cleanStepLine).filter(Boolean);
+    const expectedResults = expectedRaw.map(cleanStepLine).filter(Boolean);
+    const testDataStr = formatTestData(m.feature.referencedVars, input.testData);
+
+    let result: PlaywrightResult | undefined;
+    if (input.results && m.spec) {
+      result = input.results.get(m.spec.testTitle);
+    }
+
+    let status: ScenarioSnapshot['status'];
+    let executedDate: string | undefined;
+    let errorMessage: string | undefined;
+    let tracePath: string | undefined;
+    let testEnvironment: string | undefined;
+    let testExecutor: string | undefined;
+    let type: ScenarioSnapshot['type'];
+
+    if (!m.spec) {
+      type = baseType === 'Manual' ? 'Manual' : 'Not compiled';
+      status = baseType === 'Manual' ? 'Pending' : 'N/A';
+    } else {
+      type = baseType;
+      if (!result) {
+        status = 'Pending';
+      } else {
+        status = statusToTestResult(result.status) as ScenarioSnapshot['status'];
+        executedDate = formatExecutedDate(result.startTime);
+        if (result.error) errorMessage = String(result.error).split('\n')[0].trim();
+        if (result.tracePath) tracePath = result.tracePath;
+        testEnvironment = `${input.env.baseURL} (${input.env.projectName})`;
+        testExecutor = input.env.executor;
+      }
+    }
+
+    scenarios.push({
+      tcId,
+      category1,
+      category2,
+      category3: input.featureName,
+      category4: input.screen,
+      vpId,
+      priority,
+      type,
+      status,
+      tags: m.feature.tags,
+      precondition,
+      testData: testDataStr,
+      steps,
+      expectedResults,
+      executedDate,
+      errorMessage,
+      tracePath,
+      testEnvironment,
+      testExecutor,
+    });
+  }
+
+  return {
+    name: input.screen,
+    isFlow: input.isFlow,
+    featureName: input.featureName,
+    featurePath: input.featurePath,
+    specLink: input.specLink,
+    summary: summarizeScreen(scenarios),
+    scenarios,
+  };
+}
+
+function summarizeScreen(scenarios: ScenarioSnapshot[]): ScreenSummaryStats {
+  const stats: ScreenSummaryStats = {
+    total: scenarios.length,
+    passed: 0,
+    failed: 0,
+    pending: 0,
+    na: 0,
+    notCompiled: 0,
+    passRate: 0,
+  };
+  for (const s of scenarios) {
+    if (s.status === 'Passed') stats.passed++;
+    else if (s.status === 'Failed') stats.failed++;
+    else if (s.status === 'Pending') stats.pending++;
+    else if (s.status === 'N/A') stats.na++;
+    if (s.type === 'Not compiled') stats.notCompiled++;
+  }
+  const executed = stats.passed + stats.failed;
+  stats.passRate = executed > 0 ? stats.passed / executed : 0;
+  return stats;
+}

package/src/exporters/playwright-report-parser.ts

@@ -74,7 +74,11 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
   const result = new Map<string, PlaywrightResult>();
   for (const [fullTitle, spec] of specMap.entries()) {
     const test = spec.tests?.[0];
-    const res = test?.results?.[0];
+    // With retries enabled, take the LAST attempt — that's the final outcome.
+    // A flaky test (failed once, passed retry) shows as "passed" in the dashboard
+    // because the user-visible end state is "passed".
+    const results = test?.results || [];
+    const res = results[results.length - 1];
     const status = normalizeStatus(res?.status);
     const errorMsg = res?.error?.message || '';
     const trace = res?.attachments?.find((a) => a.name === 'trace' || a.contentType === 'application/zip')?.path;
@@ -141,15 +145,18 @@ export function statusToTestResult(status: PlaywrightResult['status']): string {
 }
 
 /**
- * Format startTime (ISO string) → "dd/mm/yyyy".
+ * Format startTime (ISO string) → "dd/mm/yyyy" in Vietnam time (UTC+7),
+ * so reports stay consistent regardless of where Playwright was executed.
  */
 export function formatExecutedDate(startTime: string | undefined): string {
   if (!startTime) return '';
   const d = new Date(startTime);
   if (isNaN(d.getTime())) return '';
-  const dd = String(d.getDate()).padStart(2, '0');
-  const mm = String(d.getMonth() + 1).padStart(2, '0');
-  const yyyy = d.getFullYear();
+  const VN_OFFSET_MS = 7 * 60 * 60 * 1000;
+  const shifted = new Date(d.getTime() + VN_OFFSET_MS);
+  const dd = String(shifted.getUTCDate()).padStart(2, '0');
+  const mm = String(shifted.getUTCMonth() + 1).padStart(2, '0');
+  const yyyy = shifted.getUTCFullYear();
   return `${dd}/${mm}/${yyyy}`;
 }
 

package/src/exporters/spec-parser.ts

@@ -15,13 +15,18 @@ function extractTestBlock(content: string, startIdx: number): {
   body: string;
   endIdx: number;
 } | null {
-  // Match test('title', async ({ page }) => {
-  const testRegex = /test\s*\(\s*['"]([^'"]+)['"]\s*,\s*async\s*\([^)]*\)\s*=>\s*\{/g;
+  // Match both legacy and tag-pass-through forms:
+  //   test('title', async ({ page }) => {
+  //   test('title', { tag: [...] }, async ({ page }) => {
+  // Backreference \1 lets the inner title contain the opposite quote type
+  // (e.g. test('Footer "X" link', ...) — common when scenarios cite UI labels).
+  const testRegex = /test\s*\(\s*(['"])((?:(?!\1).)+)\1\s*,\s*(?:\{[^}]*\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;
 
-  const title = match[1];
+  // [1] = outer quote char, [2] = title
+  const title = match[2];
   const bodyStart = match.index + match[0].length;
 
   // Find matching closing brace (accounting for nested braces)

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

@@ -21,6 +21,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-cmd-run-test.md', '.claude/commands/sungen/run-test.md'],
   ['claude-cmd-review.md', '.claude/commands/sungen/review.md'],
   ['claude-cmd-delivery.md', '.claude/commands/sungen/delivery.md'],
+  ['claude-cmd-dashboard.md', '.claude/commands/sungen/dashboard.md'],
 
   // Commands — GitHub Copilot
   ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
@@ -29,6 +30,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['copilot-cmd-run-test.md', '.github/prompts/sungen-run-test.prompt.md'],
   ['copilot-cmd-review.md', '.github/prompts/sungen-review.prompt.md'],
   ['copilot-cmd-delivery.md', '.github/prompts/sungen-delivery.prompt.md'],
+  ['copilot-cmd-dashboard.md', '.github/prompts/sungen-dashboard.prompt.md'],
 
   // Skills — Claude Code
   ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -40,6 +42,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
   ['claude-skill-delivery.md', '.claude/skills/sungen-delivery/SKILL.md'],
+  ['claude-skill-dashboard.md', '.claude/skills/sungen-dashboard/SKILL.md'],
   ['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'],
@@ -58,6 +61,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
   ['github-skill-sungen-delivery.md', '.github/skills/sungen-delivery/SKILL.md'],
+  ['github-skill-sungen-dashboard.md', '.github/skills/sungen-dashboard/SKILL.md'],
   ['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'],

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

@@ -0,0 +1,62 @@
+---
+name: dashboard
+description: 'Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export.'
+argument-hint: "[screen-name...] (omit for all)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+## Role
+
+You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `sungen dashboard` CLI which builds a self-contained HTML report. The HTML is shareable as-is (open via `file://`, no server required).
+
+## Parameters
+
+Parse **screens** from `$ARGUMENTS`:
+- If empty → CLI will include **all** screens and flows.
+- If provided → pass them through.
+
+## Steps
+
+### 1. Invoke the CLI
+
+```bash
+npx sungen dashboard <screens>
+```
+
+- No args → all screens + flows.
+- With args → only those targets.
+- Add `--open` to auto-open the rendered HTML in the user's browser.
+
+The CLI handles:
+- Discovery of `qa/screens/*` and `qa/flows/*`.
+- Reuses the same parsers as `sungen delivery` (feature, spec.ts, test-data.yaml, results.json).
+- Builds `DashboardSnapshot` JSON.
+- Persists `qa/dashboard/history/<runId>.json` (max 10 retained, oldest pruned).
+- Renders `qa/dashboard/index.html` (~1MB, single file, fully self-contained).
+- Prints a summary table.
+
+### 2. Show the result + offer next steps
+
+Forward the CLI's summary verbatim, then use `AskUserQuestion`:
+
+- **Open the dashboard** — Suggest `npx sungen dashboard --open` to open in the default browser, or just open `qa/dashboard/index.html` manually.
+- **Re-run after a test run** — Run `/sungen:run-test <screen>` to refresh `test-results/results.json`, then re-invoke `/sungen:dashboard`.
+- **Build for a single screen** — Run `/sungen:dashboard <screen>` to scope the report.
+- **Share the file** — The HTML at `qa/dashboard/index.html` can be emailed / Slacked / committed; recipients open it directly without any server.
+- **Done** — Exit.
+
+## Important notes
+
+- **Do NOT parse files yourself** — the CLI is the source of truth.
+- **The HTML is stateless** — the snapshot is embedded in `<script id="__SUNGEN_DASHBOARD__" type="application/json">…</script>`. Re-running the CLI overwrites this file.
+- **History is retained in `qa/dashboard/history/`** — these JSON files power the Trends and Compare views. Keep them in git so collaborators see the same trend.
+- **CSV/XLSX export** in the dashboard runs entirely in the browser (SheetJS) and matches the `sungen delivery` format. Use it for quick exports without re-running the CLI.
+
+## CLI Reference
+
+```
+sungen dashboard [screens...]
+  [--no-history]            Do not persist this run under qa/dashboard/history/
+  [--max-history <n>]       Cap retained history files (default: 10)
+  [--open]                  Open the rendered HTML in the default browser
+```

package/src/orchestrator/templates/ai-instructions/claude-skill-dashboard.md

@@ -0,0 +1,121 @@
+---
+name: sungen-dashboard
+description: 'Build a single-file HTML dashboard summarising test cases & Playwright results. Auto-loaded by /sungen:dashboard.'
+user-invocable: false
+---
+
+## Purpose
+
+Generate `qa/dashboard/index.html` — a single-file, share-ready test report covering all (or selected) screens and flows. The HTML embeds the snapshot data inline, so it can be emailed, Slacked, or committed and opened by anyone via `file://` without any server.
+
+**This skill delegates all heavy work to the `sungen dashboard` CLI.** The CLI is the source of truth for parsing logic — do NOT re-parse files in AI. Your role is only to:
+
+1. Invoke the CLI.
+2. Show its output verbatim.
+3. Help the user decide next actions.
+
+---
+
+## Architecture
+
+```
+User → /sungen:dashboard [screen...]
+       │
+       ▼
+  sungen dashboard CLI  (deterministic — no AI tokens)
+  ├─ Discovery: qa/screens/* + qa/flows/*
+  ├─ Reuse delivery parsers (.feature, .spec.ts, test-data.yaml, results.json)
+  ├─ Build DashboardSnapshot JSON
+  ├─ Write qa/dashboard/history/<runId>.json (max 20 retained, oldest pruned)
+  ├─ Inject payload into pre-built HTML template
+  └─ Write qa/dashboard/index.html (~1MB, fully self-contained)
+```
+
+Source modules: `src/dashboard/*.ts` + `src/exporters/json-exporter.ts`.
+UI source: `dashboard/` (built once, ships in npm package as `dist/dashboard/templates/index.html`).
+
+---
+
+## Required sources (CLI tolerates missing files)
+
+| # | Source | Path | Required? |
+|---|--------|------|-----------|
+| 1 | Feature file | `qa/screens/<name>/features/<name>.feature` (or `qa/flows/...`) | Yes — screens without a feature are skipped |
+| 2 | Test data | `qa/screens/<name>/test-data/<name>.yaml` | Optional — `{{vars}}` fall back to literal |
+| 3 | Compiled spec | `specs/generated/<name>/<name>.spec.ts` | Optional — flagged as "Not compiled" if missing |
+| 4 | Test results | `specs/generated/<name>/<name>-test-result.json` (or `test-results/results.json`) | Optional — TCs show as "Pending" if missing |
+
+Unlike `sungen delivery`, the dashboard CLI is **forgiving** — it always renders whatever data is available. Pre-flight is implicit, not blocking.
+
+---
+
+## Output structure
+
+```
+qa/dashboard/
+├── index.html                      # share-ready single-file report
+└── history/
+    ├── 2026-04-26T...Z.json        # past snapshots, oldest → newest
+    ├── 2026-04-27T...Z.json
+    └── …                           # max 20, older pruned automatically
+```
+
+Both should be committed to git so collaborators see the same trend lines.
+
+---
+
+## Dashboard views
+
+| View | What it shows |
+|------|---------------|
+| **Overview** | Stat cards (total/passed/failed/pending), pass-rate donut, priority bar chart, trend mini-chart, per-screen progress bars |
+| **Suites** | Tree: screen → scenarios; filter by search/status/priority; click → detail modal with steps, expected, error, trace |
+| **Trends** | Pass-rate line chart + stacked status bars across all retained runs (requires ≥2 runs) |
+| **Compare** | Pick base/head run; per-screen Δ table; lists of newly passing/failing/added/removed/changed tests |
+| **Export** | Browser-side CSV / XLSX download. One-button generation, no server. Same column layout as `sungen delivery` |
+
+Trends + Compare are disabled in the sidebar until at least 2 runs exist in history.
+
+---
+
+## CLI command reference
+
+```bash
+# All screens + flows
+sungen dashboard
+
+# Specific targets
+sungen dashboard kudos awards flow/checkout
+
+# Skip history persistence (one-off / CI ephemeral)
+sungen dashboard --no-history
+
+# Cap retained history (default: 20)
+sungen dashboard --max-history 50
+
+# Auto-open in default browser
+sungen dashboard --open
+```
+
+---
+
+## Skill responsibilities (when invoked from /sungen:dashboard)
+
+1. **Run the CLI** with whatever arguments came from `$ARGUMENTS`.
+2. **Show the CLI output verbatim** — do not summarize, paraphrase, or omit warnings.
+3. **Offer next-step options via `AskUserQuestion`** based on what just happened:
+   - On success → open dashboard, share file, run more tests, build for another screen, done.
+   - On error → diagnose from the error message; common causes are missing `qa/` directories or no targets.
+4. **Do NOT** parse `.feature`, `.spec.ts`, or results files yourself — that is the CLI's job.
+5. **Do NOT** touch files under `qa/dashboard/` directly — only the CLI writes there.
+
+---
+
+## Sharing the dashboard
+
+The HTML is self-contained:
+- No CDN or external font — system font stack only.
+- All JS, CSS, charts, and the SheetJS library are inlined.
+- The snapshot payload sits in `<script id="__SUNGEN_DASHBOARD__" type="application/json">…</script>`.
+
+Acceptable sharing: email, Slack upload, S3 bucket, committed in git. The recipient opens it directly, no install required. ~1MB on disk, ~300KB gzipped over the wire.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-dashboard.md

@@ -0,0 +1,62 @@
+---
+name: sungen-dashboard
+description: 'Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export.'
+argument-hint: "[screen-name...] (omit for all)"
+tools: [read, execute, edit, vscode/askQuestions]
+---
+
+## Role
+
+You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `sungen dashboard` CLI which builds a self-contained HTML report. The HTML is shareable as-is (open via `file://`, no server required).
+
+## Parameters
+
+Parse **screens** from `$ARGUMENTS`:
+- If empty → CLI will include **all** screens and flows.
+- If provided → pass them through.
+
+## Steps
+
+### 1. Invoke the CLI
+
+```bash
+npx sungen dashboard <screens>
+```
+
+- No args → all screens + flows.
+- With args → only those targets.
+- Add `--open` to auto-open the rendered HTML in the user's browser.
+
+The CLI handles:
+- Discovery of `qa/screens/*` and `qa/flows/*`.
+- Reuses the same parsers as `sungen delivery` (feature, spec.ts, test-data.yaml, results.json).
+- Builds `DashboardSnapshot` JSON.
+- Persists `qa/dashboard/history/<runId>.json` (max 10 retained, oldest pruned).
+- Renders `qa/dashboard/index.html` (~1MB, single file, fully self-contained).
+- Prints a summary table.
+
+### 2. Show the result + offer next steps
+
+Forward the CLI's summary verbatim, then ask the user what they want next:
+
+- **Open the dashboard** — Suggest `npx sungen dashboard --open` or open `qa/dashboard/index.html` manually.
+- **Re-run after a test run** — Run `/sungen:run-test <screen>` to refresh `test-results/results.json`, then re-invoke `/sungen:dashboard`.
+- **Build for a single screen** — Run `/sungen:dashboard <screen>` to scope the report.
+- **Share the file** — The HTML at `qa/dashboard/index.html` can be emailed / Slacked / committed; recipients open it directly without any server.
+- **Done** — Exit.
+
+## Important notes
+
+- **Do NOT parse files yourself** — the CLI is the source of truth.
+- **The HTML is stateless** — the snapshot is embedded in `<script id="__SUNGEN_DASHBOARD__" type="application/json">…</script>`. Re-running the CLI overwrites this file.
+- **History is retained in `qa/dashboard/history/`** — these JSON files power the Trends and Compare views. Keep them in git so collaborators see the same trend.
+- **CSV/XLSX export** in the dashboard runs entirely in the browser (SheetJS) and matches the `sungen delivery` format. Use it for quick exports without re-running the CLI.
+
+## CLI Reference
+
+```
+sungen dashboard [screens...]
+  [--no-history]            Do not persist this run under qa/dashboard/history/
+  [--max-history <n>]       Cap retained history files (default: 10)
+  [--open]                  Open the rendered HTML in the default browser
+```