@vizzly-testing/cli 0.35.3-beta.1 → 0.35.3-beta.3

package/dist/utils/visual-context-normalizers.js

@@ -1,44 +1,43 @@
 /**
- * Read the API's canonical visual-review state with legacy approval fallbacks.
+ * Read the API's visual-review state.
  *
  * @param {Object} record - Comparison or review record from the API.
  * @returns {string|null} The review state when the API supplied one.
  */
 export function getVisualReviewState(record = {}) {
-  return record.visual_review?.state || record.review_state || record.approval_status || null;
+  return record.visual_review?.state || null;
 }
 
 /**
- * Keep visual outcome separate from processing status when both are available.
+ * Read the visual comparison result.
  *
  * @param {Object} comparison - Comparison record from the API.
- * @returns {string|null} The visual result, or the legacy status fallback.
+ * @returns {string|null} The visual result when the API supplied one.
  */
 export function getComparisonResult(comparison = {}) {
-  return comparison.result || comparison.status || null;
+  return comparison.result || null;
 }
 
 /**
- * Resolve a screenshot name across current and legacy response shapes.
+ * Read the current screenshot name.
  *
  * @param {Object} comparison - Comparison record from the API.
- * @returns {string|null} The first API-provided name or identity fallback.
+ * @returns {string|null} The screenshot name when the API supplied one.
  */
 export function getComparisonName(comparison = {}) {
-  return comparison.name || comparison.screenshot_name || comparison.current_screenshot?.name || comparison.screenshot?.name || comparison.current_name || comparison.id || null;
+  return comparison.screenshot?.name || null;
 }
 
 /**
- * Resolve CSS viewport dimensions without confusing them with bitmap size.
+ * Read CSS viewport dimensions without confusing them with bitmap size.
  *
  * @param {Object} comparison - Comparison record from the API.
  * @returns {{width: number|null, height: number|null}|null} Viewport dimensions.
  */
 export function getComparisonViewport(comparison = {}) {
-  let current = comparison.current_screenshot || comparison.screenshot || {};
-  let viewport = comparison.viewport || current.viewport || {};
-  let width = viewport.width ?? comparison.viewport_width ?? current.viewport_width ?? comparison.current_viewport_width ?? null;
-  let height = viewport.height ?? comparison.viewport_height ?? current.viewport_height ?? comparison.current_viewport_height ?? null;
+  let viewport = comparison.screenshot?.viewport || {};
+  let width = viewport.width ?? null;
+  let height = viewport.height ?? null;
   return width != null || height != null ? {
     width,
     height
@@ -46,26 +45,25 @@ export function getComparisonViewport(comparison = {}) {
 }
 
 /**
- * Resolve the browser from nested current screenshot or legacy metadata fields.
+ * Read the browser from the current screenshot.
  *
  * @param {Object} comparison - Comparison record from the API.
  * @returns {string|null} The browser name when present.
  */
 export function getComparisonBrowser(comparison = {}) {
-  return comparison.browser || comparison.current_screenshot?.browser || comparison.screenshot?.browser || comparison.current_browser || comparison.current_metadata?.browser || comparison.current_metadata?.properties?.browser || null;
+  return comparison.screenshot?.browser || null;
 }
 
 /**
- * Resolve bitmap dimensions from nested or flat screenshot fields.
+ * Read bitmap dimensions from a screenshot record.
  *
- * @param {Object} record - Preferred screenshot record.
- * @param {Object} fallback - Legacy fields to use when the record is incomplete.
+ * @param {Object} record - Screenshot record from the API.
  * @returns {{width: number|null, height: number|null}|null} Bitmap dimensions.
  */
-function getBitmap(record = {}, fallback = {}) {
-  let bitmap = record.bitmap || fallback.bitmap || {};
-  let width = bitmap.width ?? record.bitmap_width ?? fallback.bitmap_width ?? null;
-  let height = bitmap.height ?? record.bitmap_height ?? fallback.bitmap_height ?? null;
+function getBitmap(record = {}) {
+  let bitmap = record.bitmap || {};
+  let width = bitmap.width ?? null;
+  let height = bitmap.height ?? null;
   return width != null || height != null ? {
     width,
     height
@@ -73,16 +71,15 @@ function getBitmap(record = {}, fallback = {}) {
 }
 
 /**
- * Resolve viewport dimensions from one screenshot-shaped record.
+ * Read viewport dimensions from a screenshot record.
  *
- * @param {Object} record - Preferred screenshot record.
- * @param {Object} fallback - Legacy fields to use when the record is incomplete.
+ * @param {Object} record - Screenshot record from the API.
  * @returns {{width: number|null, height: number|null}|null} Viewport dimensions.
  */
-function getRecordViewport(record = {}, fallback = {}) {
-  let viewport = record.viewport || fallback.viewport || {};
-  let width = viewport.width ?? record.viewport_width ?? fallback.viewport_width ?? null;
-  let height = viewport.height ?? record.viewport_height ?? fallback.viewport_height ?? null;
+function getRecordViewport(record = {}) {
+  let viewport = record.viewport || {};
+  let width = viewport.width ?? null;
+  let height = viewport.height ?? null;
   return width != null || height != null ? {
     width,
     height
@@ -93,30 +90,22 @@ function getRecordViewport(record = {}, fallback = {}) {
  * Normalize current screenshot identity, render facts, metadata, and asset URL.
  *
  * @param {Object} comparison - Comparison record from the API.
- * @returns {Object} A stable current screenshot projection.
+ * @returns {Object} Current screenshot details.
  */
 function getCurrentScreenshot(comparison = {}) {
-  let screenshot = comparison.current_screenshot || comparison.screenshot || {};
+  let screenshot = comparison.screenshot || {};
   return {
-    id: screenshot.id || comparison.current_screenshot_id || null,
-    name: screenshot.name || getComparisonName(comparison),
-    status: screenshot.status || comparison.screenshot_status || null,
-    browser: screenshot.browser || getComparisonBrowser(comparison),
-    device: screenshot.device || comparison.device || null,
-    viewport: getRecordViewport(screenshot, {
-      viewport: comparison.viewport,
-      viewport_width: comparison.current_viewport_width ?? comparison.viewport_width,
-      viewport_height: comparison.current_viewport_height ?? comparison.viewport_height
-    }) || getComparisonViewport(comparison),
-    bitmap: getBitmap(screenshot, {
-      bitmap: comparison.bitmap,
-      bitmap_width: comparison.current_width ?? comparison.bitmap_width,
-      bitmap_height: comparison.current_height ?? comparison.bitmap_height
-    }),
-    metadata: screenshot.metadata || comparison.current_metadata || comparison.metadata || null,
-    signature: screenshot.signature || comparison.current_signature || comparison.signature || null,
-    url: screenshot.url || screenshot.original_url || comparison.current_url || comparison.current_original_url || comparison.current_screenshot_url || null,
-    error_message: screenshot.error_message || comparison.error_message || null
+    id: screenshot.id || null,
+    name: screenshot.name || null,
+    status: screenshot.status || null,
+    browser: screenshot.browser || null,
+    device: screenshot.device || null,
+    viewport: getRecordViewport(screenshot),
+    bitmap: getBitmap(screenshot),
+    metadata: screenshot.metadata || null,
+    signature: screenshot.signature || null,
+    url: screenshot.url || null,
+    error_message: screenshot.error_message || null
   };
 }
 
@@ -124,31 +113,28 @@ function getCurrentScreenshot(comparison = {}) {
  * Normalize the baseline screenshot without inventing missing render facts.
  *
  * @param {Object} comparison - Comparison record from the API.
- * @returns {Object} A stable baseline screenshot projection.
+ * @returns {Object} Baseline screenshot details.
  */
 function getBaselineScreenshot(comparison = {}) {
-  let current = comparison.current_screenshot || comparison.screenshot || {};
-  let baseline = comparison.baseline_screenshot || comparison.baseline || current.baseline || {};
+  let baseline = comparison.screenshot?.baseline || {};
   return {
-    id: baseline.id || comparison.baseline_screenshot_id || null,
-    build_id: baseline.build_id || comparison.baseline_build_id || null,
-    name: baseline.name || comparison.baseline_name || null,
+    id: baseline.id || null,
+    build_id: baseline.build_id || null,
+    name: baseline.name || null,
     browser: baseline.browser || null,
     viewport: getRecordViewport(baseline),
     bitmap: getBitmap(baseline),
-    metadata: baseline.metadata || comparison.baseline_metadata || null,
-    signature: baseline.signature || comparison.baseline_signature || null,
-    url: baseline.url || baseline.original_url || comparison.baseline_url || comparison.baseline_original_url || comparison.baseline_screenshot_url || null
+    metadata: baseline.metadata || null,
+    signature: baseline.signature || null,
+    url: baseline.url || null
   };
 }
 
 /**
- * Project compact Honeydiff facts without making raw geometry the default.
+ * Keep the useful Honeydiff facts without including raw geometry by default.
  *
- * Agents need stable counts, fingerprints, URLs, the API projection, and the
- * server's authoritative artifact manifest for first-pass diagnosis. Keeping
- * that manifest intact prevents the CLI from becoming less authoritative than
- * the API. Raw regions and scoring details stay behind an explicit include
+ * Agents need counts, fingerprints, URLs, analysis details, and the server's
+ * artifact list for first-pass diagnosis. Raw regions and scoring details stay behind an explicit include
  * because they can dominate an otherwise bounded handoff.
  *
  * @param {Object} comparison - Comparison record from the API.
@@ -156,20 +142,19 @@ function getBaselineScreenshot(comparison = {}) {
  * @returns {Object} Compact diff evidence suitable for context summaries.
  */
 function getComparisonDiff(comparison = {}, includeDiffs = false) {
-  let diff = comparison.diff || comparison.diff_image || comparison.analysis || {};
-  let analysis = comparison.analysis || {};
-  let regions = diff.regions || diff.diff_regions || analysis.diff_regions || comparison.diff_regions;
-  let projection = diff.projection || diff.analysis_projection || analysis.projection || analysis.analysis_projection || comparison.analysis_projection || comparison.projection || null;
-  let artifacts = diff.artifacts ?? analysis.artifacts ?? comparison.artifacts ?? null;
+  let diff = comparison.diff || {};
+  let regions = diff.regions;
+  let details = diff.details || null;
+  let artifacts = diff.artifacts ?? null;
   let compact = {
-    percentage: diff.percentage ?? analysis.percentage ?? analysis.diff_percentage ?? comparison.diff_percentage ?? null,
-    changed_pixels: diff.changed_pixels ?? analysis.changed_pixels ?? comparison.changed_pixels ?? null,
-    total_pixels: diff.total_pixels ?? analysis.total_pixels ?? comparison.total_pixels ?? null,
-    threshold: diff.threshold ?? analysis.threshold ?? comparison.threshold ?? null,
-    fingerprint_hash: diff.fingerprint_hash || analysis.fingerprint_hash || comparison.fingerprint_hash || null,
-    region_count: diff.region_count ?? analysis.region_count ?? comparison.region_count ?? projection?.clusters?.count ?? (Array.isArray(regions) ? regions.length : null),
-    projection,
-    image_url: diff.image_url || diff.url || analysis.diff_image_url || comparison.diff_url || comparison.diff_image_url || null
+    percentage: diff.percentage ?? null,
+    changed_pixels: diff.changed_pixels ?? null,
+    total_pixels: diff.total_pixels ?? null,
+    threshold: diff.threshold ?? null,
+    fingerprint_hash: diff.fingerprint_hash || null,
+    region_count: diff.region_count ?? details?.clusters?.count ?? (Array.isArray(regions) ? regions.length : null),
+    details,
+    image_url: diff.image_url || null
   };
 
   // Preserve server-owned evidence exactly so agents can verify and download
@@ -179,10 +164,10 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
   }
   if (includeDiffs) {
     compact.regions = regions || [];
-    compact.cluster_metadata = diff.cluster_metadata || analysis.cluster_metadata || comparison.cluster_metadata || null;
-    compact.ssim_score = diff.ssim_score ?? analysis.ssim_score ?? comparison.ssim_score ?? null;
-    compact.gmsd_score = diff.gmsd_score ?? analysis.gmsd_score ?? comparison.gmsd_score ?? null;
-    compact.diff_lines = diff.diff_lines || analysis.diff_lines || comparison.diff_lines || [];
+    compact.cluster_metadata = diff.cluster_metadata || null;
+    compact.ssim_score = diff.ssim_score ?? null;
+    compact.gmsd_score = diff.gmsd_score ?? null;
+    compact.diff_lines = diff.diff_lines || [];
   }
   return compact;
 }
@@ -191,7 +176,7 @@ function getComparisonDiff(comparison = {}, includeDiffs = false) {
  * Prefer explicit review need and return null when the API supplied no review fact.
  *
  * @param {Object} comparison - Comparison record from the API.
- * @param {string|null} reviewState - Canonical review state for the record.
+ * @param {string|null} reviewState - Review state for the record.
  * @returns {boolean|null} Whether the comparison needs review, when known.
  */
 function comparisonNeedsReview(comparison = {}, reviewState = null) {
@@ -205,28 +190,24 @@ function comparisonNeedsReview(comparison = {}, reviewState = null) {
 }
 
 /**
- * Normalize one comparison across grouped and legacy flat API response shapes.
+ * Normalize one comparison from the current build-context API.
  *
  * @param {Object} comparison - Comparison record from the API.
  * @param {Object} options - Normalization options.
- * @param {string|null} [options.fallbackName] - Group name for unnamed variants.
  * @param {boolean} [options.includeDiffs] - Include raw Honeydiff diagnostics.
  * @returns {Object} A stable comparison evidence record.
  */
 export function normalizeComparisonRecord(comparison = {}, options = {}) {
   let reviewState = getVisualReviewState(comparison);
-  let name = comparison.name || comparison.screenshot_name || comparison.current_screenshot?.name || comparison.screenshot?.name || comparison.current_name || options.fallbackName || comparison.id || null;
   return {
     id: comparison.id || null,
-    name,
+    name: getComparisonName(comparison),
     result: getComparisonResult(comparison),
     status: comparison.status || null,
     review_state: reviewState,
     visual_review: comparison.visual_review || null,
-    approval_status: comparison.approval_status || null,
     build_branch: comparison.build_branch || null,
     needs_review: comparisonNeedsReview(comparison, reviewState),
-    is_flaky: comparison.is_flaky == null ? null : comparison.is_flaky === true,
     browser: getComparisonBrowser(comparison),
     viewport: getComparisonViewport(comparison),
     screenshot: getCurrentScreenshot(comparison),
@@ -236,13 +217,13 @@ export function normalizeComparisonRecord(comparison = {}, options = {}) {
 }
 
 /**
- * Read the server's total variant count across supported response shapes.
+ * Read the server's total variant count.
  *
  * @param {Object} group - Screenshot group from the API.
  * @returns {number|null} The explicit total when present.
  */
 function getExplicitVariantCount(group = {}) {
-  return group.variant_count ?? group.total_variants ?? group.totalVariants ?? null;
+  return group.total_variants ?? null;
 }
 
 /**
@@ -250,13 +231,9 @@ function getExplicitVariantCount(group = {}) {
  *
  * @param {Object} group - Screenshot group from the API.
  * @param {Object[]} variants - Returned normalized variants.
- * @param {boolean} forcedComplete - Whether the caller owns the complete set.
  * @returns {boolean} Whether aggregate derivation is safe.
  */
-function hasCompleteVariants(group = {}, variants = [], forcedComplete = false) {
-  if (forcedComplete || group.variants_complete === true) {
-    return true;
-  }
+function hasCompleteVariants(group = {}, variants = []) {
   let explicitCount = getExplicitVariantCount(group);
   return explicitCount != null && explicitCount === variants.length;
 }
@@ -264,7 +241,7 @@ function hasCompleteVariants(group = {}, variants = [], forcedComplete = false)
 /**
  * Derive only facts backed by a complete variant set and complete source fields.
  *
- * Unknown review, flaky, result, or diff values stay null instead of becoming
+ * Unknown review, result, or diff values stay null instead of becoming
  * client-authored false or zero values.
  *
  * @param {Object[]} variants - Complete normalized variants for one screenshot.
@@ -278,12 +255,10 @@ function deriveAggregateFacts(variants = [], complete = false) {
   let results = variants.map(variant => variant.result);
   let reviewStates = variants.map(variant => variant.review_state);
   let needsReview = variants.map(variant => variant.needs_review);
-  let flaky = variants.map(variant => variant.is_flaky);
   let percentages = variants.map(variant => variant.diff.percentage).filter(value => value != null);
   let allResultsKnown = results.every(value => value != null);
   let allReviewStatesKnown = reviewStates.every(value => value != null);
   let allNeedsReviewKnown = needsReview.every(value => value != null);
-  let allFlakyKnown = flaky.every(value => value != null);
   return {
     has_changes: results.includes('changed') ? true : allResultsKnown ? false : null,
     has_new: results.includes('new') ? true : allResultsKnown ? false : null,
@@ -292,27 +267,24 @@ function deriveAggregateFacts(variants = [], complete = false) {
     needs_review_count: allNeedsReviewKnown ? needsReview.filter(value => value === true).length : null,
     failed_count: allResultsKnown ? results.filter(result => ['failed', 'error'].includes(result)).length : null,
     has_rejected: reviewStates.includes('rejected') ? true : allReviewStatesKnown ? false : null,
-    has_flaky: flaky.includes(true) ? true : allFlakyKnown ? false : null,
     max_diff_percentage: percentages.length === variants.length && percentages.length > 0 ? Math.max(...percentages) : null
   };
 }
 
 /**
- * Normalize a screenshot group while keeping explicit server aggregates authoritative.
+ * Normalize a screenshot group while keeping explicit server totals unchanged.
  *
  * @param {Object} group - Grouped visual-review record from the API.
  * @param {Object} options - Normalization options.
- * @param {boolean} [options.variantsComplete] - Marks a caller-owned complete set.
  * @returns {Object} A normalized screenshot group and its variants.
  */
 export function normalizeComparisonGroup(group = {}, options = {}) {
-  let rawVariants = group.variants || group.comparisons || [];
-  let groupName = group.name || group.test_name || group.testName || null;
+  let rawVariants = group.comparisons || [];
+  let groupName = group.name || null;
   let variants = rawVariants.map(variant => normalizeComparisonRecord(variant, {
-    fallbackName: groupName,
     includeDiffs: options.includeDiffs
   }));
-  let complete = hasCompleteVariants(group, variants, options.variantsComplete === true);
+  let complete = hasCompleteVariants(group, variants);
   let derived = deriveAggregateFacts(variants, complete);
   let aggregate = group.aggregate_status || {};
   let needsReviewCount = aggregate.needs_review_count ?? derived.needs_review_count ?? null;
@@ -329,36 +301,11 @@ export function normalizeComparisonGroup(group = {}, options = {}) {
       needs_review_count: needsReviewCount,
       failed_count: aggregate.failed_count ?? derived.failed_count ?? null,
       has_rejected: aggregate.has_rejected ?? derived.has_rejected ?? null,
-      has_flaky: aggregate.has_flaky ?? derived.has_flaky ?? null,
       max_diff_percentage: aggregate.max_diff_percentage ?? derived.max_diff_percentage ?? null
     }
   };
 }
 
-/**
- * Group a complete legacy flat comparison list by screenshot name.
- *
- * @param {Object[]} comparisons - Complete flat comparisons from build context.
- * @param {Object} options - Normalization options passed to each comparison.
- * @returns {Object[]} Normalized screenshot groups in API order.
- */
-function groupFlatComparisons(comparisons = [], options = {}) {
-  let grouped = new Map();
-  for (let comparison of comparisons) {
-    let name = getComparisonName(comparison) || 'unknown screenshot';
-    let group = grouped.get(name) || {
-      name,
-      variants: []
-    };
-    group.variants.push(comparison);
-    grouped.set(name, group);
-  }
-  return [...grouped.values()].map(group => normalizeComparisonGroup(group, {
-    ...options,
-    variantsComplete: true
-  }));
-}
-
 /**
  * Join compact group variants to the exact comparison records in the same API
  * response.
@@ -375,11 +322,10 @@ function groupFlatComparisons(comparisons = [], options = {}) {
 function joinGroupComparisons(groups = [], comparisons = []) {
   let comparisonsById = new Map(comparisons.filter(comparison => comparison?.id).map(comparison => [comparison.id, comparison]));
   return groups.map(group => {
-    let variantKey = Array.isArray(group.variants) ? 'variants' : 'comparisons';
-    let variants = Array.isArray(group[variantKey]) ? group[variantKey] : [];
+    let comparisons = Array.isArray(group.comparisons) ? group.comparisons : [];
     return {
       ...group,
-      [variantKey]: variants.map(variant => ({
+      comparisons: comparisons.map(variant => ({
         ...variant,
         ...(comparisonsById.get(variant.id) || {})
       }))
@@ -399,9 +345,10 @@ function joinGroupComparisons(groups = [], comparisons = []) {
  */
 function normalizeFailedCapture(screenshot = {}, options = {}) {
   let normalized = normalizeComparisonRecord({
-    ...screenshot,
     screenshot,
-    result: screenshot.result || screenshot.status || 'failed'
+    result: 'failed',
+    status: screenshot.status || null,
+    visual_review: screenshot.comparison?.visual_review || null
   }, options);
   return {
     ...normalized,
@@ -410,14 +357,14 @@ function normalizeFailedCapture(screenshot = {}, options = {}) {
 }
 
 /**
- * Collect failed captures from explicit and screenshot-list response shapes.
+ * Collect failed captures from the build context response.
  *
  * @param {Object} context - Raw build context response.
  * @param {Object} options - Normalization options passed to each capture.
  * @returns {Object[]} Deduplicated failed captures in API order.
  */
 function getFailedCaptures(context = {}, options = {}) {
-  let explicit = Array.isArray(context.failed_captures) ? context.failed_captures : Array.isArray(context.failed_screenshots) ? context.failed_screenshots : [];
+  let explicit = Array.isArray(context.failed_captures) ? context.failed_captures : [];
   let screenshots = (context.screenshots || []).filter(screenshot => ['failed', 'error'].includes(screenshot.status));
   let captures = [...explicit, ...screenshots];
   let seen = new Set();
@@ -432,7 +379,7 @@ function getFailedCaptures(context = {}, options = {}) {
 }
 
 /**
- * Adapt raw build context for human presentation across current and legacy APIs.
+ * Adapt raw build context for human presentation.
  *
  * Raw JSON output intentionally bypasses this lossy presentation boundary.
  *
@@ -445,7 +392,7 @@ export function normalizeBuildContext(context = {}, options = {}) {
   let rawComparisons = context.comparisons || [];
   let comparisons = rawComparisons.map(comparison => normalizeComparisonRecord(comparison, options));
   let joinedGroups = joinGroupComparisons(context.groups || [], rawComparisons);
-  let groups = joinedGroups.length > 0 ? joinedGroups.map(group => normalizeComparisonGroup(group, options)) : groupFlatComparisons(rawComparisons, options);
+  let groups = joinedGroups.map(group => normalizeComparisonGroup(group, options));
   return {
     ...context,
     comparisons,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.35.3-beta.1",
+  "version": "0.35.3-beta.3",
   "description": "Visual regression testing from your terminal",
   "keywords": [
     "llm-context",
@@ -94,7 +94,7 @@
   },
   "dependencies": {
     "@vizzly-testing/bear-den": "0.1.4",
-    "@vizzly-testing/honeydiff": "^0.15.0",
+    "@vizzly-testing/honeydiff": "^0.16.0",
     "ansis": "^4.2.0",
     "commander": "^15.0.0",
     "cosmiconfig": "^9.0.0",
@@ -121,7 +121,7 @@
     "@babel/preset-env": "^8.0.2",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^8.0.1",
-    "@biomejs/biome": "^2.3.8",
+    "@biomejs/biome": "^2.5.10",
     "@heroicons/react": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@playwright/test": "^1.55.1",
@@ -138,7 +138,7 @@
     "tsd": "^0.33.0",
     "tui-driver": "github:vizzly-testing/tui-driver",
     "typescript": "^7.0.2",
-    "vite": "^8.0.0",
+    "vite": "^8.2.2",
     "wouter": "^3.7.1"
   }
 }

package/skills/vizzly/SKILL.md

@@ -1,74 +1,64 @@
 ---
 name: vizzly
-description: "Inspect, explain, and debug Vizzly visual regression evidence; use an existing Vizzly workflow before and after UI changes; add or adjust screenshot capture; troubleshoot local TDD or cloud builds; or configure Vizzly CI. Use when a task mentions Vizzly, screenshot baselines, comparisons, Honeydiff, visual review, dynamic regions, or a repository's Vizzly setup."
+description: Inspect and explain Vizzly visual regression evidence, verify UI changes, troubleshoot local or cloud builds, adjust screenshot capture, or configure Vizzly CI. Use when a task mentions Vizzly, screenshot baselines, comparisons, Honeydiff, visual review, or an existing Vizzly workflow.
 ---
 
 # Vizzly
 
-Use Vizzly as visual evidence for user-facing changes. Keep the repository's
-existing test workflow in charge of how the UI is exercised.
+Use Vizzly as evidence for user-facing changes. Keep the repository's existing
+test workflow in charge of how the UI is exercised.
 
-## Start From The Repository
+## Prepare
 
-1. Confirm that the repository uses Vizzly by checking its configuration,
-   dependencies, scripts, or existing `.vizzly` data.
-2. Use the repository's established CLI invocation. The examples in this skill
-   use `vizzly`; substitute its package script, `pnpm exec vizzly`, or
-   `npx vizzly` when that is how the repository runs local binaries.
-3. Do not install, initialize, log in, or change credentials unless the task
-   explicitly includes setup. Never print or persist a token.
+1. Confirm the repository uses Vizzly by checking its config, dependencies,
+   scripts, or `.vizzly` data.
+2. Use the repository's established CLI invocation exactly. Otherwise, replace
+   `vizzly` in these examples with `pnpm exec vizzly`; use `npx vizzly` when the
+   repository uses npm.
+3. Do not install, initialize, log in, or change credentials unless setup is in
+   scope. Never print or persist a token.
 
-## Follow The Evidence Loop
+## Inspect And Verify
 
-1. Choose the most relevant source:
-   - Use a supplied cloud build or comparison ID when the task names one.
-   - Use existing local context when `.vizzly` contains the run under review.
-   - Generate fresh evidence through the repository's existing visual test
-     workflow when stored evidence may be stale or absent.
-2. Request the bounded, machine-readable build context:
+1. Choose the supplied cloud build or comparison when one is named. Otherwise,
+   use current local evidence or find the relevant cloud build.
+2. Request bounded JSON:
 
    ```bash
    vizzly context build current --source local --agent --json
    vizzly context build <build-id> --source cloud --agent --json
    ```
 
-3. Check the build identity, source, branch, timestamps, baseline selection,
-   review state, and truncation fields before interpreting the evidence. Treat
-   omitted fields as unknown.
-4. Inspect the current, baseline, and diff images together using whatever
-   image, browser, URL, or local-file capability is available. If an image is
-   inaccessible, say so and do not infer its visual contents from metadata.
-5. Read viewport, browser, screenshot metadata, review state, and Honeydiff
-   facts alongside the images. Follow the returned `suggested_commands` for
-   exact comparison or screenshot drill-downs. Request raw diff regions only
-   when the compact summary is insufficient.
-6. Separate observations from explanations. State what the evidence shows,
-   then label any proposed cause with appropriate confidence.
-7. Make the smallest justified UI or test change, rerun the owning user
-   workflow, and inspect the resulting evidence again.
+3. Confirm the build, source, branch, timestamps, baseline, review state, and
+   pagination before drawing conclusions. If `has_more` is true, run the
+   returned next-page command before concluding. Missing fields remain unknown.
+4. Follow `suggested_commands` to inspect a comparison. View its baseline,
+   current, and diff images together. If an image cannot be opened, label the
+   result metadata-only; do not call it visual verification.
+5. Read image dimensions, viewport, browser, diff regions, fingerprint, and
+   relevant history alongside the images. A prior approval is supporting
+   evidence, not permission to approve the current comparison.
+6. State observations before possible causes. Make the smallest justified
+   change, rerun the owning workflow, and inspect the new evidence.
 
 ## Guardrails
 
-- Treat an approved baseline as the accepted reference for that comparison,
-  not infallible truth. Check its identity and selection reason.
-- Do not invent progress, counts, review state, visual causes, or missing API
+- Do not invent progress, ranking, review state, visual causes, or missing API
   values.
-- Do not approve, reject, comment on, publish, or replace visual evidence
-  unless the user explicitly asks for that mutation.
-- Preserve existing thresholds, cluster sizes, signature properties, and
-  dynamic-region behavior unless the task and evidence justify changing them.
-- Prefer deterministic fixtures and existing end-to-end journeys over hiding a
-  diff with broader tolerances or a new screenshot-only test.
-- Report the screenshot or comparison identity, the relevant build or link,
-  the observed evidence, any access limitations, and the command used.
+- Do not approve, reject, comment on, publish, or replace evidence unless the
+  task explicitly asks for that mutation.
+- Preserve thresholds, cluster sizes, signature properties, and other capture
+  settings unless repeated evidence justifies a change.
+- Prefer deterministic fixtures and existing user journeys over hiding a diff
+  with broader tolerances or a new screenshot-only test.
+- Report the comparison or screenshot identity, observed evidence, access
+  limitations, and the command or link used.
 
-## Load References Only When Needed
+## Load A Reference When Needed
 
-- Read [references/cli-context.md](references/cli-context.md) for local and
-  cloud inspection commands, TDD lifecycle, and evidence drill-downs.
-- Read [references/sdks.md](references/sdks.md) only when adding or changing
-  screenshot capture code.
-- Read [references/dynamic-content.md](references/dynamic-content.md) when a
-  diff may involve unstable content, hotspots, or confirmed regions.
-- Read [references/setup-ci.md](references/setup-ci.md) only when the task asks
-  to initialize Vizzly, change CI, or troubleshoot configuration.
+- [CLI context](references/cli-context.md): local and cloud evidence, build
+  discovery, drill-downs, images, and TDD lifecycle.
+- [SDK capture](references/sdks.md): add or change screenshot capture code.
+- [Dynamic content](references/dynamic-content.md): investigate unstable
+  content and screenshot-specific tolerances.
+- [Setup and CI](references/setup-ci.md): initialize Vizzly or change CI.