@vizzly-testing/cli 0.38.1 → 0.39.1

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

@@ -1,12 +1,12 @@
-# CLI Context
+# CLI context
 
-Use the repository's established CLI invocation and existing authentication.
-If cloud authentication is unavailable, report the blocker. Do not start an
-interactive login unless setup is in scope.
+Use the repo's usual CLI command and existing credentials. If cloud auth isn't
+available, report it. Only start an interactive login when setup is part of
+the task.
 
-## Query The Cloud API
+## Query the cloud API
 
-Discover the live review API instead of guessing endpoints or adding command flags:
+Check the live API schema for endpoints and options:
 
 ```bash
 vizzly api schema --json
@@ -15,34 +15,38 @@ vizzly api schema <operation-id> -q view=fields --json
 vizzly api schema <operation-id> -q view=response --json
 ```
 
-The index lists available operations. The default operation view describes the
-method, path, parameters, authentication, and example arguments. Request field
-choices or response types only when needed. API JSON payloads are under
-`data.response`.
+The index lists available requests. Each operation shows the method, path,
+parameters, auth, and example arguments. Ask for field choices or response types
+as needed. API results are under `data.response`.
 
-Call the discovered path using `vizzly api <path>`, `-X` for its method, `-H`
-for headers, and `-q` for query parameters. Send the discovered API version
-header on data requests. Use `fields` to select just the evidence needed.
-Follow the response's pagination values explicitly; the CLI fetches one page
-per request. Keep cursors opaque and preserve the query they belong to.
+Call the returned path with `vizzly api <path>`. Use `-X` for the method, `-H`
+for headers, and `-q` for query parameters. Include the API version header from
+the schema on data requests. Use `fields` to ask for just the data you need.
 
-For a review, discover projects/builds, then inspect the build's screenshots,
+The CLI fetches one page per request. Use the response's page fields to get
+more results. Pass cursors back unchanged and keep the same query.
+
+To review a build, find the project and build, then check its screenshots,
 comparisons, and image endpoints. Download images with `--output <new-file>`
-and view baseline, current, and diff together. Use file output for large analysis
-responses too. Existing files are not overwritten. Export the full schema only
-when needed: `vizzly api schema --full --output <new-file> --json`.
+and view the baseline, current, and diff together. File output also helps with
+large analysis results. Existing files won't be overwritten. Export the full
+schema only when needed:
+
+```bash
+vizzly api schema --full --output <new-file> --json
+```
 
-Review decisions require an authorized task, user credentials, and the documented
-organization header. Discover the decision operation's body before sending it
-with `-d @<file>` or `-d @-` for stdin. Generate a fresh `commandId` for each
-intended decision, then read back the review state. Generic writes are not
-automatically replayed; after an uncertain result, inspect state before retrying.
-Treat schema examples as argument arrays, not shell scripts.
+Review decisions need the user's authorization, user credentials, and the
+organization header listed in the schema. Check the decision request's body
+before sending it with `-d @<file>` or `-d @-` for stdin. Make a fresh `commandId`
+for each intended decision, then read back the review state. Writes aren't
+retried automatically. If you're unsure whether one succeeded, check the state
+before trying again. Treat schema examples as argument arrays, not shell scripts.
 
-## Choose The Evidence
+## Choose the evidence
 
-Use an ID supplied by the task. If no cloud build is supplied, list recent
-builds and select the one matching the branch, commit, or pull request:
+Use the ID supplied by the task. If no cloud build is named, find recent builds
+and choose the one matching the branch, commit, or pull request:
 
 ```bash
 vizzly builds --branch <branch> --limit 5 --json
@@ -50,12 +54,11 @@ vizzly status <build-id> --json
 vizzly api schema sdk.getBuildContext --json
 ```
 
-Use status for lifecycle facts, then follow the discovered build-context
-operation for visual evidence. Do not assume the first returned comparison is
-the most important; preserve API order and inspect the records relevant to the
-task.
+Use status to check build progress, then follow the build-context API for
+screenshots and diffs. Keep the API's comparison order and inspect the records
+that matter to the task. The first comparison isn't necessarily the most useful.
 
-For saved local evidence:
+For saved local results:
 
 ```bash
 vizzly context build current --source local --json
@@ -63,18 +66,18 @@ vizzly context screenshot "<screenshot-name>" --source local --json
 vizzly context review-queue --source local --json
 ```
 
-Confirm the stored build, branch, timestamp, and baseline are current enough
+Check that the saved build, branch, timestamp, and baseline are recent enough
 for the task.
 
-## Generate Fresh Evidence
+## Generate fresh evidence
 
-For one run, let Vizzly own the local session:
+For one run, let Vizzly start and stop the local server:
 
 ```bash
 vizzly tdd run "<existing visual test command>" --no-open
 ```
 
-For repeated runs, start the detached daemon once:
+For repeated runs, start a background server once:
 
 ```bash
 vizzly tdd start --json
@@ -83,13 +86,12 @@ vizzly tdd status --json
 vizzly tdd stop --json
 ```
 
-`tdd run` and `tdd start` are alternatives. Stop only a daemon started for the
-current task.
+Choose `tdd run` or `tdd start`. Only stop a server started for this task.
 
-## Review A Local TDD Run
+## Review a local TDD run
 
-After `tdd run` exits, inspect captures directly from `.vizzly`. These
-commands don't need a running TDD daemon or cloud credentials:
+After `tdd run` exits, read captures from `.vizzly/`. You don't need a running
+server or cloud credentials:
 
 ```bash
 vizzly tdd screenshots list --page 1 --page-size 20
@@ -97,49 +99,61 @@ vizzly tdd screenshots latest
 vizzly tdd screenshots show <comparison-id>
 ```
 
-`latest` prints the current screenshot path for the most recent capture. Use
-`list` to find a comparison ID when you need a specific screenshot or browser
-variant. During UI iteration, inspect the current image first; request
-`--image diff` or `--image all` when comparison diagnostics help answer the
-question. Open the printed image paths with the available image viewer.
+`latest` prints the newest current screenshot's path. Use `list` to find a
+specific comparison ID or browser variant. While changing UI, open the current
+image first. Add `--image diff` or `--image all` when you need to compare it.
+Open the printed paths with an image viewer.
 
-`accept` replaces one local baseline and updates that report entry. Use it only
-when the task explicitly authorizes accepting a baseline; don't accept a change
-just to make a diff disappear:
+`accept` replaces one local baseline and updates the report entry. Use it only
+when the task explicitly authorizes accepting a baseline:
 
 ```bash
 vizzly tdd screenshots accept <comparison-id>
 ```
 
-When a cloud build is in scope:
+Don't accept a change just to make a diff disappear.
+
+When the task calls for a cloud build:
 
 ```bash
-vizzly run "<existing visual test command>" --wait --json
+vizzly run "<existing visual test command>" --json
 vizzly api schema --json
 ```
 
-## Inspect A Comparison
+To make visual differences fail CI, see the
+[CI guide](ci.md#cloud-ci).
+
+## Inspect a comparison
 
-Discover comparison and image operations from the schema:
+Find comparison and image requests in the schema:
 
 ```bash
 vizzly api schema getComparisonContext --json
 vizzly api schema sdk.getComparisonImage --json
 ```
 
-Open all three images together. Prefer `original_url` and fall back to `url`:
+Request `comparison.images` to check which current, baseline, and diff images
+are available. Download them through `sdk.getComparisonImage`, using the
+comparison ID and image kind. Include the version header from the schema and
+use `--output <new-file>` to save each image.
 
-- Current: `comparison.screenshot.original_url` or
-  `comparison.screenshot.url`
-- Baseline: `comparison.baseline.original_url` or `comparison.baseline.url`
-- Diff: `comparison.analysis.diff_image_url`
+View the available images together. A new capture may have no baseline, and an
+identical capture may have no diff. Report missing or inaccessible images;
+don't invent them. Request `comparison.review` to check the review decision.
 
-Then compare the visible change with diff regions, fingerprint, and the
-separate `similar_by_fingerprint` and `recent_by_name` history streams.
-Previous review decisions help explain recurring evidence but do not decide the
-current review.
+Changed regions and full analysis use separate requests. Discover them when
+the images alone don't answer the question:
 
-Useful supporting commands:
+```bash
+vizzly api schema sdk.getComparisonRegions --json
+vizzly api schema sdk.getComparisonAnalysis --json
+```
+
+Use `--output <new-file>` for full analysis. Compare those details with the
+images and earlier comparisons. Previous decisions can help explain a recurring
+change; they don't decide the current review.
+
+Other useful commands:
 
 ```bash
 vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
@@ -147,10 +161,6 @@ vizzly context similar <fingerprint-hash> --source cloud --json
 vizzly context review-queue --source <local-or-cloud> --json
 ```
 
-Use the documented response and pagination fields to request only the evidence
-needed. Request comments only when human review context matters.
-
-## Continue Without Guessing
-
-Use IDs and pagination values from API responses. Keep cursors opaque and
-preserve the query they belong to when requesting the next page.
+Use IDs and page values from the API response. Pass cursors back unchanged,
+keep the same query, and request only what you need. Fetch comments when they
+help explain a review.

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

@@ -1,28 +1,27 @@
-# Dynamic Content
+# Dynamic content
 
 Dates, timers, random data, API content, generated images, and responsive text
-can cause a diff. They are possible explanations, not conclusions.
+can cause diffs. Check the images before deciding that's what happened.
 
-## Diagnose Before Tuning
+## Check before changing settings
 
-1. Inspect the actual images and screenshot history:
+1. Open the images and check screenshot history:
 
    ```bash
    vizzly context screenshot "<screenshot-name>" --source <local-or-cloud> --json
    ```
 
-2. Record the visible region, recurrence, render metadata, and whether the same
-   change appears across builds or variants.
-3. Prefer deterministic fixtures when they can remove irrelevant variation.
-4. Use diff regions only to locate changed pixels; they do not approve a
-   comparison or explain why it changed.
-5. Preserve `threshold` and `minClusterSize` unless repeated evidence
-   justifies a change.
+2. Note where the change appears, how often it happens, the capture details,
+   and whether it appears in other builds or variants.
+3. Use fixed test data when it can remove changes unrelated to the test.
+4. Use diff regions to find changed pixels. They don't tell you why the pixels
+   changed or whether to approve them.
+5. Keep `threshold` and `minClusterSize` unless repeated captures show they
+   need to change.
 
-Avoid broad masks, global threshold changes for one region, and claims based on
-metadata alone. A recurring change can still be a bug, especially when content
-movement affects nearby layout.
+Avoid broad masks or global threshold changes to hide a problem in one region.
+Metadata alone can't explain a visual change. A recurring change can still be
+a bug, especially if moving content changes nearby layout.
 
-Report the observed change first. Label fixture drift, layout shift, capture
-timing, or baseline mismatch as a possible cause until the evidence establishes
-it.
+Describe what you see first. Treat changing test data, layout shifts, capture
+timing, or a wrong baseline as possible causes until you can confirm them.

package/skills/vizzly/references/sdks.md

@@ -1,8 +1,8 @@
-# SDK Capture
+# SDK capture
 
-Use the repository's existing Vizzly integration and user journey. The
-JavaScript example applies only when no framework-specific capture path already
-owns the workflow.
+Use the repo's existing Vizzly integration and test flow. Use this JavaScript
+example only if the repo doesn't already capture screenshots through a
+framework integration.
 
 ## JavaScript
 
@@ -14,28 +14,28 @@ await vizzlyScreenshot('settings-profile-edit-mode', screenshot);
 ```
 
 `vizzlyScreenshot(name, image, options)` accepts PNG bytes or a file path.
-Options include `properties`, `threshold`, `minClusterSize`, and
-`fullPage`. Preserve existing tuning unless visual evidence justifies changing
-it.
+Options include `properties`, `threshold`, `minClusterSize`, and `fullPage`.
+Keep existing settings unless the images show why they need to change.
 
-## Keep Identity Stable
+## Keep names and baseline matching consistent
 
-Use a descriptive name. Identity always includes the name, viewport width, and
-browser. Configured `signatureProperties` add custom identity fields; other
-properties are metadata.
+Use descriptive names and keep them the same across runs. Baseline matching
+always uses the name, viewport width, and browser. To also match on custom
+properties, use `signatureProperties` in `vizzly.config.js` for local baselines.
+Cloud baselines use the project's signature settings. Other properties are
+metadata.
 
-Do not assume theme, locale, or state creates a separate baseline unless the
-configuration says so. Avoid generic names such as `screenshot1` and names
-with slashes.
+Theme, locale, or state won't create a separate baseline unless the matching
+settings include them. Avoid generic names like `screenshot1` and names with
+slashes.
 
-## Follow Existing Integrations
+## Follow the existing setup
 
-- Keep the Vizzly Vitest matcher when it is already configured:
+Keep the Vitest matcher if it's already configured:
 
-  ```javascript
-  await expect(page).toMatchScreenshot('hero-section.png');
-  ```
+```javascript
+await expect(page).toMatchScreenshot('hero-section.png');
+```
 
-- Prefer existing Storybook, static-site, Ember, or Swift capture flows over a
-  parallel test path.
-- Inspect the repository's integration setup before changing capture code.
+Check the repo's setup before changing capture code. Use its Storybook,
+static-site, Ember, or Swift integration if it has one.

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

@@ -1,44 +0,0 @@
-# Setup And CI
-
-Use this reference only when the task includes initialization, CI changes, or
-configuration troubleshooting. These workflows mutate files or external build
-state.
-
-## Initialize
-
-Initialize only with authorization:
-
-```bash
-vizzly init
-```
-
-Use [CLI context](cli-context.md) for local evidence and TDD lifecycle commands.
-
-## Cloud CI
-
-Use a project-scoped token from the repository's existing secret system. Never
-print it or write it into the repository.
-
-```bash
-vizzly run "<existing visual test command>" --wait --json
-```
-
-For parallel CI, give every shard the same workflow-specific parallel ID. Run
-shards without `--wait`, then finalize once after all shards finish:
-
-```bash
-vizzly run "<shard test command>" --parallel-id "<shared-ci-run-id>" --json
-vizzly finalize "<shared-ci-run-id>" --json
-```
-
-## Troubleshoot
-
-- `vizzly doctor`: local configuration
-- `vizzly tdd status --json`: a local daemon started by the task
-- `vizzly status <build-id> --json`: cloud lifecycle
-- `vizzly api schema --json`: discover supported cloud review operations and
-  their request and response schemas.
-
-If screenshots are absent, verify the existing integration, the test path that
-should capture them, and the active session. If authentication is absent,
-report it rather than logging in unless setup is in scope.