@vizzly-testing/cli 0.35.2 → 0.35.3-beta.0

package/skills/vizzly/SKILL.md

@@ -1,107 +1,74 @@
 ---
 name: vizzly
-description: "Use when a repo has Vizzly configured and you need screenshot memory or visual history: before/after UI changes, visual regression review, screenshot history, approved baselines, diffs, dynamic regions, docs/manual images, public screenshots, or Vizzly builds. Teaches agents to use Vizzly CLI/context for local TDD, cloud builds, review state, comments, hotspots, previews, and SDK capture patterns."
+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."
 ---
 
 # Vizzly
 
-Vizzly is the project's screenshot memory database. It stores approved baselines, current screenshots, diffs, review state, comments, hotspots, previews, and public screenshot URLs.
-
-Use Vizzly when you need to understand what the UI looked like before, what changed, what humans already reviewed, or which screenshots already exist. Browser automation is still useful for interacting with a live app; Vizzly is usually the faster first stop for visual history.
-
-## First Instinct
-
-Before changing UI, check whether Vizzly already has local screenshot context:
-
-```bash
-vizzly context build current --source local --agent
-```
-
-If a task names a screen, component, or screenshot, inspect that screenshot's history before changing thresholds or re-capturing blindly:
-
-```bash
-vizzly context screenshot "<screenshot-name>" --source local --json
-```
-
-When you make or verify UI changes, use the local TDD server as the active feedback loop:
-
-```bash
-vizzly tdd start &
-npm run test:e2e -- tests/e2e/path.spec.js
-vizzly context build current --source local --agent --json
-```
-
-The user may choose whether the TDD server runs in the foreground or background. Once it is
-running, run tests normally from the repo. The SDK discovers `.vizzly/server.json`, posts
-screenshots to the active TDD server, and refreshes `.vizzly/current`, `.vizzly/diffs`, report
-data, and local context.
-
-Use `vizzly tdd run` for true one-off runs where you want the CLI to own starting the visual
-session and running the command:
-
-```bash
-vizzly tdd run "<test command>" --no-open
-```
-
-For specific evidence, drill in:
-
-```bash
-vizzly context comparison <comparison-id> --json
-vizzly context screenshot "<screenshot-name>" --json
-vizzly context review-queue --json
-```
-
-If local context is unavailable and the project uses cloud builds, use the build id from CI or CLI output:
-
-```bash
-vizzly context build <build-id> --agent --json --include diffs,comments
-```
-
-## What Vizzly Knows
-
-- **Approved baselines**: expected UI.
-- **Current screenshots**: what the latest run rendered.
-- **Diffs**: where pixels/layout/content changed.
-- **Review state and comments**: human context attached to builds and screenshots.
-- **Hotspots and confirmed regions**: known dynamic areas.
-- **Preview links**: static or deployed UI context for a build.
-- **Public screenshots**: stable URLs for documentation and manuals.
-
-## Acting On Visual Context
-
-- Treat approved baselines as visual truth.
-- Treat diffs as evidence, not as approval instructions.
-- Do not approve or reject visual changes unless the user explicitly asks.
-- Prefer existing E2E or user journeys over narrow screenshot-only specs.
-- For dynamic content, inspect screenshot context before changing thresholds.
-- Prefer deterministic test data, per-screenshot `threshold`, per-screenshot `minClusterSize`, hotspots, or confirmed regions over global tolerance changes.
-- Report visual findings with screenshot names, build/comparison links when available, and the command you ran.
-
-## Capturing Screenshots
-
-Use the existing integration when one is present. For direct JavaScript capture:
-
-```javascript
-import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
-
-let screenshot = await page.screenshot();
-await vizzlyScreenshot('checkout-form', screenshot, {
-  properties: {
-    browser: 'chromium',
-    viewport: 'desktop',
-    state: 'valid-card'
-  },
-  threshold: 2,
-  minClusterSize: 4
-});
-```
-
-Use `properties` to separate variants such as theme, locale, viewport, role, state, component, page, or docs/manual grouping.
-
-## When You Need More Detail
-
-- For SDK examples and capture patterns, read `references/sdks.md`.
-- For CLI/context commands and JSON output, read `references/cli-context.md`.
-- For dynamic content, thresholds, and hotspots, read `references/dynamic-content.md`.
-- For public screenshot URLs and docs/manual images, read `references/public-screenshots.md`.
-- For project setup and CI, read `references/setup-ci.md`.
+Use Vizzly as visual evidence for user-facing changes. Keep the repository's
+existing test workflow in charge of how the UI is exercised.
+
+## Start From The Repository
+
+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.
+
+## Follow The Evidence Loop
+
+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:
+
+   ```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.
+
+## 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
+  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.
+
+## Load References Only 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.

package/skills/vizzly/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Vizzly"
-  short_description: "Use Vizzly visual context while changing UI."
-  default_prompt: "Use Vizzly to inspect visual context before and after UI changes."
+  short_description: "Inspect and debug visual changes with Vizzly"
+  default_prompt: "Use $vizzly to inspect the visual evidence for this UI change and explain what changed."

package/skills/vizzly/references/cli-context.md

@@ -1,48 +1,96 @@
 # CLI And Context
 
-Use these commands to gather Vizzly evidence before making UI assumptions.
+Use the repository's existing CLI invocation. The examples use `vizzly` for
+brevity; substitute the repository's package script or package-manager command
+when needed.
 
-## Local TDD
+Use existing authentication and project configuration. If cloud authentication
+is missing, report the blocker. Do not start an interactive login or change
+credentials unless the task includes setup.
+
+## Inspect Existing Local Evidence
+
+Request structured local evidence with both `--agent` and `--json`:
+
+```bash
+vizzly context build current --source local --agent --json
+vizzly context screenshot "<screenshot-name>" --source local --json
+vizzly context review-queue --source local --json
+```
+
+Pin hand-written local drill-downs with `--source local`. Without it, automatic
+source resolution may fall back to cloud data when a local item is unavailable.
+
+Local context reads persisted `.vizzly` artifacts. Confirm that their build,
+branch, timestamp, and baseline match the task before treating them as current.
+
+## Generate Fresh Local Evidence
+
+For a one-off run, let Vizzly own the complete local session:
 
 ```bash
-vizzly tdd start --open
-vizzly tdd status
-vizzly tdd stop
-vizzly tdd run "<test command>" --no-open
-vizzly context build current --source local --agent
+vizzly tdd run "<existing visual test command>" --no-open
 vizzly context build current --source local --agent --json
 ```
 
-If `tdd start` prints a non-default port, pass that same port to
-`tdd status --port <port>` and `tdd stop --port <port>`.
+For repeated test runs, start the detached daemon once:
 
-Local context reads `.vizzly` state and does not require cloud auth. After a
-one-shot `tdd run`, prefer the printed `contextCommand` before editing UI.
+```bash
+vizzly tdd start --json
+vizzly tdd status --json
+<existing visual test command>
+vizzly context build current --source local --agent --json
+vizzly tdd stop --json
+```
+
+Treat `tdd run` and `tdd start` as alternatives. Do not shell-background
+`tdd start`; it already launches a detached daemon. Stop only a server started
+for the current task, and reuse the printed port for status or stop commands
+when Vizzly selects a non-default port.
+
+## Inspect Cloud Evidence
 
-## Cloud Builds
+When the task already has a build ID:
 
 ```bash
-export VIZZLY_TOKEN="project-token"
-vizzly run "<test command>" --wait --json
-vizzly context build <build-id> --agent --json --include diffs,comments
+vizzly status <build-id> --json
+vizzly context build <build-id> --source cloud --agent --json
 ```
 
-`vizzly run --wait --json` returns a `contextCommand` when a cloud build is created. Prefer that command over constructing URLs by hand.
+Use status for server-owned lifecycle, processing, comparison, and review
+facts. Use build context for visual debugging.
 
-## Drilldowns
+When creating a cloud build is in scope, wrap the repository's existing test
+command:
 
 ```bash
-vizzly context comparison <comparison-id> --json
-vizzly context screenshot "<screenshot-name>" --json
-vizzly context similar <fingerprint-hash> --json
-vizzly context review-queue --json
+vizzly run "<existing visual test command>" --wait --json
+vizzly context build <build-id> --source cloud --agent --json
 ```
 
-Use comparison context for one diff. Use screenshot context for history and recurring dynamic areas. Use review queue context when triaging unresolved visual work.
+## Read And Drill Into Evidence
 
-## Good Agent Behavior
+For each evidence record:
+
+1. Inspect the current, baseline, and diff images with an available harness
+   capability. State the limitation if an image cannot be accessed.
+2. Read render metadata, review state, and compact Honeydiff diagnostics next
+   to the images.
+3. Run the returned `suggested_commands` instead of reconstructing identifiers
+   or URLs.
+4. Add `--include diffs` only when raw Honeydiff region geometry is needed.
+   Request comments only when human review context matters.
+
+Useful manual drill-downs are:
+
+```bash
+vizzly context comparison <comparison-id> --source <local-or-cloud> --json
+vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
+vizzly context similar <fingerprint-hash> --source cloud --json
+vizzly context review-queue --source <local-or-cloud> --json
+```
 
-- Use `--json` for automation and summaries.
-- Use `--agent` when building prompt context or asking another agent to continue.
-- Keep human-readable command output in final summaries only when it changes the user's next action.
-- Do not approve/reject unless explicitly asked.
+Use the source from the evidence you are inspecting in place of
+`<local-or-cloud>`. `context similar` is cloud-only. Keep missing values
+unknown, and do not turn metadata into a visual conclusion when the underlying
+images are unavailable.

package/skills/vizzly/references/dynamic-content.md

@@ -1,44 +1,39 @@
 # Dynamic Content
 
-Dynamic content is common: dates, calendars, generated images, avatars, timers, randomized data, responsive text, and API-backed content.
+Treat dates, timers, randomized data, API-backed content, generated images, and
+responsive text as possible causes of change, not automatic explanations.
 
-## Order Of Operations
+## Diagnose Before Tuning
 
-1. Make test data deterministic when the changing content is not what you are testing.
-2. Inspect screenshot context before changing code:
+1. Inspect screenshot history and the actual image evidence:
 
-```bash
-vizzly context screenshot "<screenshot-name>" --json
-```
+   ```bash
+   vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
+   ```
 
-3. Use per-screenshot tolerances for local noise:
-
-```javascript
-await vizzlyScreenshot('plant-calendar', screenshot, {
-  properties: { surface: 'calendar' },
-  threshold: 4,
-  minClusterSize: 12
-});
-```
-
-4. Use hotspots or confirmed regions for recurring valid dynamic regions.
+2. Replace `<local-or-cloud>` with the source of the evidence being diagnosed.
+   Record the observed region, recurrence, render metadata, and whether the
+   same change appears across builds or variants.
+3. Check whether deterministic fixtures can remove irrelevant variation.
+4. Treat hotspots and confirmed regions as server- or user-owned evidence.
+   They can affect comparison results, but this CLI exposes them for inspection
+   rather than authoring.
+5. Preserve existing per-screenshot `threshold` and `minClusterSize` values
+   unless the task and repeated evidence justify a change. Do not invent new
+   tolerance values from one diff.
 
 ## Avoid
 
-- Raising global project thresholds for one dynamic area.
-- Masking a whole page when a small region changes.
-- Treating every daily diff as product breakage.
-- Ignoring structural changes because a region is known to be dynamic.
-
-## How To Explain Findings
-
-Say whether the diff looks like:
+- Raising a global threshold for one unstable area.
+- Masking a whole page when only a small region changes.
+- Assuming a recurring change is harmless without inspecting it.
+- Ignoring structural movement because a region contains dynamic content.
+- Claiming a cause when only metadata, rather than images or history, is
+  available.
 
-- expected dynamic content
-- deterministic fixture drift
-- real content disappearance
-- layout shift
-- screenshot timing/capture instability
-- baseline mismatch
+## Report Findings
 
-Then name the screenshot and include the relevant context command or link.
+State the observed change first. Then distinguish a likely explanation—such as
+fixture drift, content disappearance, layout shift, capture timing, or baseline
+mismatch—from unresolved alternatives. Include the screenshot identity and the
+context command or link used.

package/skills/vizzly/references/sdks.md

@@ -1,6 +1,7 @@
 # SDK Capture Patterns
 
-Vizzly works best when screenshots are attached to real user journeys and stable names.
+Prefer the repository's existing Vizzly integration and user journey. Add a new
+capture path only when the task requires it.
 
 ## JavaScript Client
 
@@ -8,55 +9,41 @@ Vizzly works best when screenshots are attached to real user journeys and stable
 import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
 
 let screenshot = await page.screenshot();
-await vizzlyScreenshot('settings-profile-edit-mode', screenshot, {
-  properties: {
-    browser: 'chromium',
-    viewport: 'desktop',
-    state: 'edit'
-  },
-  threshold: 2,
-  minClusterSize: 4
-});
+await vizzlyScreenshot('settings-profile-edit-mode', screenshot);
 ```
 
-`vizzlyScreenshot(name, image, options)` accepts a PNG buffer or file path.
+`vizzlyScreenshot(name, image, options)` accepts PNG bytes or a file path.
+Available options include:
 
-Important options:
-
-- `properties`: metadata used for baseline identity and filtering.
+- `properties`: metadata attached to the screenshot.
 - `threshold`: per-screenshot CIEDE2000 Delta E tolerance.
 - `minClusterSize`: minimum changed-pixel cluster size.
-- `fullPage`: marks full-page captures.
-
-## Vitest
-
-Use the Vizzly Vitest plugin when present. It keeps the native `toMatchScreenshot` style:
+- `fullPage`: whether the screenshot represents a full-page capture.
 
-```javascript
-await expect(page.getByRole('heading')).toMatchScreenshot('hero-section.png', {
-  properties: {
-    theme: 'dark',
-    viewport: 'desktop'
-  },
-  threshold: 2,
-  fullPage: true
-});
-```
+Do not add arbitrary tuning values. Preserve the repository's existing values
+unless visual evidence justifies changing them.
 
-## Storybook And Static Sites
+## Screenshot Identity
 
-If the repo uses Vizzly Storybook or static-site clients, prefer those existing flows over adding custom Playwright screenshots. They already know how to crawl stories/pages, name screenshots, and attach viewport metadata.
+Use a stable, descriptive name. Vizzly's signature always includes the name,
+viewport width, and browser. Only properties named in the project's
+`signatureProperties` configuration participate in baseline identity.
 
-## Swift
+Treat other `properties` as metadata. Do not assume values such as theme,
+locale, or state create separate baselines unless the configuration says so.
 
-Swift/XCTest projects use `VizzlyXCTest` helpers such as `app.vizzlyScreenshot(name:properties:threshold:minClusterSize:)`. For iOS work, verify against the Swift package docs in the repo before changing examples.
+## Existing Integrations
 
-## Naming
+- Use the Vizzly Vitest matcher when the project already configures the plugin:
 
-Use stable, descriptive screenshot names:
+  ```javascript
+  await expect(page).toMatchScreenshot('hero-section.png');
+  ```
 
-- Good: `checkout-payment-form-valid-card`
-- Good: `settings-profile-edit-mode`
-- Avoid: `screenshot1`, `test`, names with slashes
+- Prefer existing Storybook, static-site, or Ember capture flows over adding a
+  parallel Playwright path.
+- For Swift/XCTest, inspect the repository's Vizzly Swift package documentation
+  and existing `VizzlyXCTest` usage before changing capture code.
 
-Use properties for variants instead of stuffing every variant into the name.
+Use properties for searchable metadata and configured variants. Avoid generic
+names such as `screenshot1` or `test`, and avoid names with slashes.

package/skills/vizzly/references/setup-ci.md

@@ -1,44 +1,68 @@
 # Setup And CI
 
-Use Vizzly locally for fast feedback and in CI for shared review.
+Use this reference only when the user asks to initialize Vizzly, change CI, or
+troubleshoot configuration. These workflows mutate project files or external
+build state.
 
 ## Local Setup
 
+Initialize only with authorization:
+
 ```bash
 vizzly init
-vizzly tdd start --open
-vizzly tdd run "<test command>" --no-open
 ```
 
-The local SDK discovers `.vizzly/server.json` and sends screenshots to the TDD server when it is running.
-For one-off checks, `vizzly tdd run` writes local review data under `.vizzly/`
-and prints a context command for follow-up inspection.
+After setup, choose one local execution mode:
+
+```bash
+vizzly tdd run "<existing visual test command>" --no-open
+```
 
-## Cloud Setup
+or:
 
 ```bash
-export VIZZLY_TOKEN="project-token"
-vizzly run "<test command>" --wait
+vizzly tdd start --json
+<existing visual test command>
+vizzly tdd stop --json
 ```
 
-Use project tokens in CI. Avoid committing tokens.
+Do not run `tdd start` before `tdd run`; both own a local TDD server lifecycle.
 
-## Parallel CI
+## Cloud CI
+
+Use a project-scoped token supplied by the user's existing secret-management
+system. Never print it, write it into the repository, or replace working
+credentials while debugging.
 
-Use `--parallel-id` when jobs are sharded:
+Wrap the CI job's existing visual test command:
 
 ```bash
-vizzly run "npm test -- --shard=1/4" --parallel-id shard-1 --wait
+vizzly run "<existing visual test command>" --wait --json
 ```
 
-Keep fast PR checks and broad scheduled checks separate:
+## Parallel CI
+
+Give every shard in one build the same parallel ID, unique to that workflow
+attempt. Run all shards without `--wait`, then finalize that shared ID once
+after every shard finishes:
+
+```bash
+vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
+vizzly finalize "<shared-ci-run-id>" --json
+```
 
-- PR builds: critical flows and changed surfaces.
-- Nightly builds: full-page sweeps, generated image suites, docs/manual captures.
+Do not create a different parallel ID per shard, and do not wait for a parallel
+build to complete before it has been finalized. Use one finalizer rather than
+having every shard race to finalize the build.
 
-## Troubleshooting
+## Troubleshoot
 
 - Run `vizzly doctor` for local configuration checks.
-- Run `vizzly status <build-id>` for cloud build status.
-- Run `vizzly context build <build-id> --agent --json` for review evidence.
-- If no screenshots appear, verify the SDK/import is present and the TDD server or `vizzly run` wrapper is active.
+- Run `vizzly tdd status --json` for a local daemon started by the task.
+- Run `vizzly status <build-id> --json` for cloud lifecycle facts.
+- Run `vizzly context build <build-id> --source cloud --agent --json` for visual
+  evidence.
+- If screenshots are absent, verify the existing SDK or integration, the test
+  path that should capture them, and the active local or cloud session.
+- If authentication is absent, report it rather than initiating login unless
+  setup is explicitly in scope.

package/skills/vizzly/references/public-screenshots.md

@@ -1,44 +0,0 @@
-# Public Screenshots
-
-Public screenshots are Vizzly's path for stable image URLs in docs and manuals.
-
-Use this when a user asks for hotlinked UI screenshots, generated manual images, docs that stay current with UI, or CDN-like screenshot URLs.
-
-## Mental Model
-
-Do not use arbitrary build screenshot URLs as stable docs assets. Use Public Properties.
-
-The flow:
-
-1. Capture screenshots with stable metadata.
-2. Configure project Public Properties in Vizzly.
-3. Approve/publish the baseline build.
-4. Use the Public URLs tab to copy the stable URL.
-
-Example capture:
-
-```javascript
-await vizzlyScreenshot('watering-widget', screenshot, {
-  properties: {
-    manual: 'plant-care',
-    component: 'watering-widget',
-    viewport: 'desktop'
-  }
-});
-```
-
-Configure a Public Property like `manual=plant-care`. Vizzly publishes matching approved baseline screenshots and keeps stable URLs for each screenshot/property identity.
-
-## Good Uses
-
-- Product manuals
-- User docs
-- Component catalogs
-- In-app UI examples
-- Screenshots that should update when approved UI changes
-
-## Cautions
-
-- Public screenshots are public. Do not publish private user data, secrets, or internal-only UI.
-- A new unapproved build does not automatically become the public docs image.
-- Use stable names and properties so URLs do not churn.