@vizzly-testing/cli 0.32.0 → 0.34.0

package/README.md

@@ -1,70 +1,80 @@
 # Vizzly CLI
 
-> Visual review for agents and teams
+> Visual regression testing from your terminal
 
-[![npm version](https://img.shields.io/npm/v/@vizzly-testing/cli.svg)](https://www.npmjs.com/package/@vizzly-testing/cli)
+[![package version](https://img.shields.io/npm/v/@vizzly-testing/cli.svg)](https://www.npmjs.com/package/@vizzly-testing/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Vizzly keeps the visual truth behind your UI: approved baselines, meaningful diffs, review state, comments, and preview links in one place. That makes it useful for humans reviewing product changes and for LLM agents that need to understand what the UI is supposed to look like before they edit it.
+<p align="center">
+  <img src="./docs/assets/vizzly-mascot-inspector.png" alt="Vizzly bear inspecting a screenshot" width="220" />
+</p>
 
-Unlike tools that re-render components in isolation, Vizzly captures screenshots directly from your functional tests: the real thing. Whether you're validating AI-generated code or testing manual changes, you get reviewed visual evidence before anything hits production.
+Vizzly is a visual testing and regression platform for teams that ship UI. It
+captures screenshots from your real tests, compares them to approved baselines,
+and gives you useful review data: meaningful diffs, comments, approvals, build
+status, and preview links.
 
-## Why Vizzly?
-
-**Local TDD workflow.** See changes as you type, not after CI. The `vizzly tdd` command runs a local dashboard that compares screenshots instantly and exposes the current workspace as local context.
-
-**Meaningful diff metadata.** Vizzly stores rich diff evidence: changed regions, cluster metadata, fingerprints, hotspots, confirmed regions, and image URLs. Agents can inspect what changed instead of guessing from a pass/fail label.
-
-**Any screenshot source.** Playwright, Cypress, Puppeteer, Selenium, native mobile apps, or even design mockups. If you can capture it, Vizzly can compare it.
-
-**Approved baselines as truth.** Cloud context carries human review state. Local context carries the downloaded or generated baseline metadata. That is the bridge between TDD locally and collaborative review in Vizzly.
+This package is the CLI and local SDK surface. Use it to run local visual TDD,
+upload screenshots from CI, generate static reports, and fetch machine-readable
+build or diff data for scripts, automation, and coding agents.
 
 ## Quick Start
 
-Requires Node.js 22+.
+You need Node.js 22+.
 
 ```bash
-npm install -g @vizzly-testing/cli
+pnpm install -g @vizzly-testing/cli
 
 vizzly init
 ```
 
-### Local Development (TDD Mode)
+For agent-friendly repos, install the Vizzly skill and add a short project
+`AGENTS.md` note:
+
+```bash
+vizzly init --agent-guidance
+```
 
-Start the TDD server, run your tests in watch mode, and see visual diffs instantly at `http://localhost:47392`.
+### Start Local TDD
+
+Start the TDD server, run your tests, and open the dashboard at
+`http://localhost:47392`.
 
 ```bash
 vizzly tdd start
-npm test -- --watch
+pnpm test -- --watch
 ```
 
-The dashboard shows diffs in real-time. Accept or reject changes right from the UI.
+The dashboard shows screenshots, baselines, and diffs as they arrive. Accept or
+reject changes right from the UI.
 
-### Cloud Integration (CI/CD)
+### Run With Cloud Review
 
-For team collaboration and CI pipelines:
+Use cloud builds when you want shared baselines, team review, and CI status:
 
 ```bash
 vizzly login
-vizzly run "npm test" --wait
+vizzly run "pnpm test" --wait
 ```
 
-The `--wait` flag polls for results and exits with code 1 if visual differences are detected.
+`--wait` blocks until Vizzly finishes processing the build. It exits with code
+`1` when visual differences need review.
 
-For CI environments, set your project token:
+In CI, use a project token:
 
 ```bash
 export VIZZLY_TOKEN=your-project-token
-vizzly run "npm test" --wait
+vizzly run "pnpm test" --wait
 ```
 
-### Visual Context For Agents
+### Inspect Builds And Diffs
 
-Use `vizzly context` when you want Vizzly to act like a visual context store, not just a test runner.
+Use `vizzly context` when you need build, comparison, screenshot, or review
+queue data from the terminal.
 
-This is especially useful for LLM agents, automation, and quick debugging loops. Instead of
-making a bunch of narrow API calls, you can ask for one build, comparison, screenshot, or review
-queue bundle and get the evidence in one place.
+This is useful for scripts, coding agents, and debugging loops. Instead of
+making a pile of narrow API calls, ask for one focused bundle and get the
+evidence in one place.
 
 ```bash
 # Cloud context for a build or comparison
@@ -75,15 +85,19 @@ vizzly context comparison def456 --json
 vizzly context build current --source local
 vizzly context build current --source local --agent
 vizzly context screenshot build-detail-screenshots --source local --json
+vizzly context review-queue --source local --json
 ```
 
-`--json` is the durable automation path. `--agent` gives a compact handoff for prompt assembly and local dogfooding. Add `--full` when an agent really needs the complete build context payload, or `--include screenshots,diffs,comments` when the compact JSON needs selected detail.
+`--json` is the durable automation path. `--agent` gives a compact handoff for
+prompt assembly. Add `--full` when you need the whole payload, or
+`--include screenshots,diffs,comments` when compact JSON needs selected detail.
 
-Local context is read-only and file-backed. It reads your existing `.vizzly` workspace state from
-TDD runs, including screenshots, diffs, and any saved hotspot or region metadata.
+Local context is read-only and file-backed. It reads your existing `.vizzly`
+workspace state from TDD runs, including screenshots, diffs, and saved hotspot
+or region metadata.
 
-Cloud context is also read-only right now. That is intentional. It keeps the trust model simple:
-Vizzly helps you see and inspect visual changes, while people still decide what gets approved.
+Cloud context is also read-only right now. That is intentional. Vizzly helps you
+see and inspect visual changes, while people still decide what gets approved.
 
 ## Capture Screenshots
 
@@ -103,7 +117,14 @@ test('homepage looks correct', async ({ page }) => {
 });
 ```
 
-The client SDK is lightweight—it just POSTs to the local server. Works with any test runner. SDKs available for [JavaScript](https://docs.vizzly.dev/integration/sdk/javascript), [Ruby](https://docs.vizzly.dev/integration/sdk/ruby), [Swift](https://docs.vizzly.dev/integration/sdk/swift), and [more](https://docs.vizzly.dev/integration/sdk/overview).
+The client SDK is lightweight. It posts screenshots to the local Vizzly server
+or the cloud build wrapper. It works with any test runner.
+
+SDKs are available for
+[JavaScript](https://docs.vizzly.dev/integration/sdk/javascript),
+[Ruby](https://docs.vizzly.dev/integration/sdk/ruby),
+[Swift](https://docs.vizzly.dev/integration/sdk/swift), and
+[more](https://docs.vizzly.dev/integration/sdk/overview).
 
 Already saving screenshots to disk? Pass the file path instead:
 
@@ -126,36 +147,46 @@ Generate a config file:
 vizzly init
 ```
 
+To teach project agents about Vizzly screenshot memory and the local visual TDD
+loop, add the repo-local skill and AGENTS.md guidance:
+
+```bash
+vizzly init --agent-guidance
+```
+
 Or create `vizzly.config.js` manually:
 
 ```javascript
 export default {
   comparison: {
-    threshold: 2.0  // CIEDE2000 Delta E (0=exact, 2=recommended)
-  }
+    // CIEDE2000 Delta E. 0 is exact. 2 is a good default.
+    threshold: 2.0,
+  },
 };
 ```
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `vizzly tdd start` | Start local TDD server with dashboard |
-| `vizzly tdd run "cmd"` | Run tests once, generate static report |
-| `vizzly run "cmd"` | Run tests with cloud integration |
-| `vizzly context ...` | Fetch visual context bundles for builds, comparisons, and screenshots |
-| `vizzly upload <dir>` | Upload existing screenshots |
-| `vizzly login` | Authenticate via browser |
-| `vizzly doctor` | Validate local setup |
+| Command | What it does |
+| --- | --- |
+| `vizzly tdd start` | Start the local TDD server and dashboard. |
+| `vizzly tdd run "cmd"` | Run tests once and generate a static visual report. |
+| `vizzly run "cmd"` | Run tests with cloud build and review integration. |
+| `vizzly context ...` | Fetch visual context for builds, comparisons, screenshots, and review queues. |
+| `vizzly upload <dir>` | Upload an existing folder of screenshots. |
+| `vizzly login` | Authenticate through the browser. |
+| `vizzly doctor` | Validate your local setup. |
 
 ## Documentation
 
-Full documentation at **[docs.vizzly.dev](https://docs.vizzly.dev)**—including framework guides,
-CI/CD setup, configuration reference, and more.
+Full documentation lives at **[docs.vizzly.dev](https://docs.vizzly.dev)**.
+Start there for framework guides, CI setup, SDK examples, and the configuration
+reference.
 
 ## Contributing
 
-Found a bug? Have an idea? [Open an issue](https://github.com/vizzly-testing/cli/issues) or submit a PR.
+Found a bug or have an idea?
+[Open an issue](https://github.com/vizzly-testing/cli/issues) or send a PR.
 
 ## License
 

package/dist/cli.js

@@ -36,7 +36,7 @@ import { saveUserPath } from './utils/global-config.js';
 import * as output from './utils/output.js';
 import { getPackageVersion } from './utils/package-info.js';
 
-// Custom help formatting with Observatory design system
+// Custom help formatting with BearDen design system
 const formatHelp = (cmd, helper) => {
   let c = colors;
   let lines = [];
@@ -49,7 +49,7 @@ const formatHelp = (cmd, helper) => {
     // Cute grizzly bear mascot with square eyes (like the Vizzly logo!)
     lines.push(c.brand.amber('   ʕ□ᴥ□ʔ'));
     lines.push(`   ${c.brand.amber(c.bold('vizzly'))} ${c.dim(`v${version}`)}`);
-    lines.push(`   ${c.gray('Visual review for agents and teams')}`);
+    lines.push(`   ${c.gray('Visual regression testing from your terminal')}`);
   } else {
     // Compact header for subcommands
     lines.push(`  ${c.brand.amber(c.bold('vizzly'))} ${c.white(cmd.name())}`);
@@ -177,7 +177,7 @@ const formatHelp = (cmd, helper) => {
     lines.push(`      ${c.gray('$')} ${c.white('vizzly tdd start')}`);
     lines.push('');
     lines.push(`      ${c.dim('# CI pipeline')}`);
-    lines.push(`      ${c.gray('$')} ${c.white('vizzly run "npm test" --wait')}`);
+    lines.push(`      ${c.gray('$')} ${c.white('vizzly run "pnpm test" --wait')}`);
     lines.push('');
   }
 
@@ -252,7 +252,7 @@ function normalizeJsonArgv(argv, commandNames) {
   }
   return normalizedArgv;
 }
-program.name('vizzly').description('Vizzly CLI for visual review').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
+program.name('vizzly').description('Vizzly CLI for visual regression testing').version(getPackageVersion()).option('-c, --config <path>', 'Config file path').option('--token <token>', 'Vizzly API token').option('-v, --verbose', 'Verbose output (shorthand for --log-level debug)').option('--log-level <level>', 'Log level: debug, info, warn, error (default: info, or VIZZLY_LOG_LEVEL env var)').option('--json [fields]', 'JSON output, optionally specify fields (e.g., --json id,status,branch)').option('--color', 'Force colored output (even in non-TTY)').option('--no-color', 'Disable colored output').option('--strict', 'Fail on any error (default: be resilient, warn on non-critical issues)').configureHelp({
   formatHelp
 });
 
@@ -303,8 +303,8 @@ try {
 } catch (error) {
   output.debug(`Plugin loading failed: ${error.message}`);
 }
-program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').action(async options => {
-  const globalOptions = program.opts();
+program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').option('--agent-skill', 'Install the repo-local Vizzly agent skill').option('--agent-guidance', 'Add Vizzly guidance to this project AGENTS.md and install the agent skill').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
+  let globalOptions = program.opts();
   await init({
     ...globalOptions,
     ...options,
@@ -411,7 +411,7 @@ tddCmd.command('run <command>').description('Run tests once in TDD mode with loc
     const reportResult = await generateStaticReport(process.cwd());
     if (reportResult.success) {
       const reportUrl = getReportFileUrl(reportResult.reportPath);
-      output.print(`  ${colors.brand.textTertiary('→')} Report: ${colors.blue(reportUrl)}`);
+      output.print(`  ${colors.brand.textTertiary('→')} Report: ${colors.info(reportUrl)}`);
       output.blank();
 
       // Open report in browser unless --no-open
@@ -512,8 +512,8 @@ Examples:
   }
   await comparisonsCommand(options, globalOptions);
 });
-let contextCmd = program.command('context').description('Fetch build context for agents and reviewers');
-contextCmd.command('build').description('Fetch build context for agents and reviewers').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
+let contextCmd = program.command('context').description('Fetch build and diff context');
+contextCmd.command('build').description('Fetch build context').argument('<build-id>', 'Build ID to fetch context for').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('--agent', 'Output compact context for LLM agents').option('--full', 'Return the full build context payload with --agent --json').option('--include <items>', 'Add detail to compact agent JSON: screenshots,diffs,comments').addHelpText('after', `
 Examples:
   $ vizzly context build abc123
   $ vizzly context build current --source local
@@ -890,7 +890,7 @@ program.command('whoami').description('Show current authentication status and us
 });
 
 // Save user's PATH for menubar app (non-blocking, runs in background)
-// This auto-configures the menubar app so it can find npx/node
+// This auto-configures the menubar app so it can find package runners/node
 saveUserPath().catch(() => {});
 let commandNames = new Set(program.commands.map(command => command.name()));
 let normalizedArgv = normalizeJsonArgv(process.argv, commandNames);

package/dist/client/index.js

@@ -192,6 +192,7 @@ function createSimpleClient(serverUrl) {
         let isFilePath = typeof imageBuffer === 'string';
         let image = isFilePath ? imageBuffer : imageBuffer.toString('base64');
         let type = isFilePath ? 'file-path' : 'base64';
+        let requestTimeout = options.requestTimeout || DEFAULT_TIMEOUT_MS;
         let properties = createScreenshotProperties(options);
         let httpStart = Date.now();
         let {
@@ -203,7 +204,7 @@ function createSimpleClient(serverUrl) {
           image,
           type,
           properties
-        }, DEFAULT_TIMEOUT_MS);
+        }, requestTimeout);
         let httpMs = Date.now() - httpStart;
         if (shouldLogClient('debug')) {
           console.debug(`[vizzly-client] ${name} HTTP completed in ${httpMs}ms`);

package/dist/commands/doctor.js

@@ -234,11 +234,11 @@ export async function doctorCommand(options = {}, globalOptions = {}, deps = {})
         output.printErr(`  ${colors.dim('─'.repeat(52))}`);
         for (let item of contextItems) {
           if (item.type === 'success') {
-            output.printErr(`  ${colors.green('✓')} ${colors.gray(item.label)}  ${colors.white(item.value)}`);
+            output.printErr(`  ${colors.success('✓')} ${colors.brand.textMuted(item.label)}  ${colors.white(item.value)}`);
           } else if (item.type === 'warning') {
-            output.printErr(`  ${colors.yellow('!')} ${colors.gray(item.label)}  ${colors.yellow(item.value)}`);
+            output.printErr(`  ${colors.yellow('!')} ${colors.brand.textMuted(item.label)}  ${colors.yellow(item.value)}`);
           } else {
-            output.printErr(`  ${colors.dim('○')} ${colors.gray(item.label)}  ${colors.dim(item.value)}`);
+            output.printErr(`  ${colors.dim('○')} ${colors.brand.textMuted(item.label)}  ${colors.dim(item.value)}`);
           }
         }
       }
@@ -246,7 +246,7 @@ export async function doctorCommand(options = {}, globalOptions = {}, deps = {})
       // Footer with links
       output.printErr('');
       output.printErr(`  ${colors.dim('─'.repeat(52))}`);
-      output.printErr(`  ${colors.dim('Docs')} ${colors.cyan(colors.underline('docs.vizzly.dev'))}  ${colors.dim('GitHub')} ${colors.cyan(colors.underline('github.com/vizzly-testing/cli'))}`);
+      output.printErr(`  ${colors.dim('Docs')} ${colors.info(colors.underline('docs.vizzly.dev'))}  ${colors.dim('GitHub')} ${colors.info(colors.underline('github.com/vizzly-testing/cli'))}`);
 
       // Emit structured data in verbose mode (in addition to visual output)
       if (globalOptions.verbose) {

package/dist/commands/init.js

@@ -1,20 +1,29 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { VizzlyError } from '../errors/vizzly-error.js';
 import { loadPlugins } from '../plugin-loader.js';
 import { loadConfig } from '../utils/config-loader.js';
 import * as output from '../utils/output.js';
+let commandDir = path.dirname(fileURLToPath(import.meta.url));
 let configValueSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(configValueSchema), z.record(z.string(), configValueSchema)]));
 let configSchemaValidator = z.record(z.string(), configValueSchema);
 function createInitDeps(deps = {}) {
   return {
     access: deps.access || fs.access,
+    copy: deps.copy || fs.cp,
     cwd: deps.cwd || (() => process.cwd()),
+    isInteractive: deps.isInteractive || (() => Boolean(process.stdin.isTTY && process.stdout.isTTY)),
     loadConfig: deps.loadConfig || loadConfig,
     loadPlugins: deps.loadPlugins || loadPlugins,
+    mkdir: deps.mkdir || fs.mkdir,
     output: deps.output || output,
+    promptAgentSkill: deps.promptAgentSkill || promptAgentSkill,
+    readFile: deps.readFile || fs.readFile,
+    skillSourcePath: deps.skillSourcePath || getPackagedAgentSkillPath(),
     writeFile: deps.writeFile || fs.writeFile
   };
 }
@@ -28,6 +37,15 @@ function configureOutput(output, options) {
 export function getInitConfigPath(cwd = process.cwd()) {
   return path.join(cwd, 'vizzly.config.js');
 }
+export function getPackagedAgentSkillPath(baseDir = commandDir) {
+  return path.resolve(baseDir, '..', '..', 'skills', 'vizzly');
+}
+export function getProjectAgentSkillPath(cwd = process.cwd()) {
+  return path.join(cwd, '.agents', 'skills', 'vizzly');
+}
+export function getProjectAgentsPath(cwd = process.cwd()) {
+  return path.join(cwd, 'AGENTS.md');
+}
 export async function fileExists(filePath, access = fs.access) {
   try {
     await access(filePath);
@@ -160,7 +178,170 @@ function writeHumanCreatedOutput(output, plugins) {
 function showNextSteps(output) {
   output.blank();
   output.labelValue('Next steps', '');
-  output.list(['Set your API token: export VIZZLY_TOKEN="your-api-key"', 'Run your tests with Vizzly: npx vizzly run "npm test"', 'Upload screenshots: npx vizzly upload ./screenshots']);
+  output.list(['Set your API token: export VIZZLY_TOKEN="your-api-key"', 'Run your tests with Vizzly: pnpm exec vizzly run "pnpm test"', 'Upload screenshots: pnpm exec vizzly upload ./screenshots']);
+}
+async function promptAgentSkill({
+  stdin = process.stdin,
+  stdout = process.stdout
+} = {}) {
+  let rl = createInterface({
+    input: stdin,
+    output: stdout
+  });
+  try {
+    let answer = await rl.question('Add the Vizzly agent skill to this repo? [Y/n] ');
+    return !['n', 'no'].includes(answer.trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+async function shouldInstallAgentSkill(options, deps) {
+  if (options.agentGuidance) {
+    return true;
+  }
+  if (options.skipAgentSkill) {
+    return false;
+  }
+  if (options.agentSkill) {
+    return true;
+  }
+  if (options.json || !deps.isInteractive()) {
+    return false;
+  }
+  return await deps.promptAgentSkill();
+}
+let agentGuidanceStart = '<!-- vizzly-agent-guidance -->';
+let agentGuidanceEnd = '<!-- /vizzly-agent-guidance -->';
+export function createAgentGuidanceContent() {
+  return `${agentGuidanceStart}
+## Visual Testing With Vizzly
+
+Use Vizzly for user-facing UI changes when this repo has Vizzly configured.
+
+- Read visual history before changing UI: \`npx vizzly context build current --source local --agent\`
+- Inspect named screenshot history when useful: \`npx vizzly context screenshot "<screenshot-name>" --source local --json\`
+- Verify visual changes through the existing user workflow that owns the surface: \`npx vizzly tdd run "<test command>" --no-open\`
+
+Prefer existing E2E/user journeys over narrow screenshot-only specs. Treat Vizzly diffs as review evidence; do not approve or reject changes unless asked.
+${agentGuidanceEnd}
+`;
+}
+function appendSection(content, section) {
+  if (!content.trim()) {
+    return section;
+  }
+  return `${content.replace(/\s*$/, '')}\n\n${section}`;
+}
+export async function upsertProjectAgentGuidance({
+  cwd,
+  access = fs.access,
+  readFile = fs.readFile,
+  writeFile = fs.writeFile
+}) {
+  let agentsPath = getProjectAgentsPath(cwd);
+  let guidance = createAgentGuidanceContent();
+  if (!(await fileExists(agentsPath, access))) {
+    await writeFile(agentsPath, guidance, 'utf8');
+    return {
+      status: 'created',
+      agentsPath
+    };
+  }
+  let existingContent = await readFile(agentsPath, 'utf8');
+  if (existingContent.includes(agentGuidanceStart)) {
+    return {
+      status: 'exists',
+      agentsPath
+    };
+  }
+  await writeFile(agentsPath, appendSection(existingContent, guidance), 'utf8');
+  return {
+    status: 'updated',
+    agentsPath
+  };
+}
+export async function installProjectAgentSkill({
+  cwd,
+  sourcePath,
+  access = fs.access,
+  copy = fs.cp,
+  mkdir = fs.mkdir
+}) {
+  let targetPath = getProjectAgentSkillPath(cwd);
+  if (!(await fileExists(path.join(sourcePath, 'SKILL.md'), access))) {
+    return {
+      status: 'missing-source',
+      sourcePath,
+      targetPath
+    };
+  }
+  if (await fileExists(targetPath, access)) {
+    return {
+      status: 'exists',
+      sourcePath,
+      targetPath
+    };
+  }
+  await mkdir(path.dirname(targetPath), {
+    recursive: true
+  });
+  await copy(sourcePath, targetPath, {
+    recursive: true,
+    errorOnExist: true,
+    force: false
+  });
+  return {
+    status: 'installed',
+    sourcePath,
+    targetPath
+  };
+}
+function writeAgentSkillOutput(output, result) {
+  if (!result) {
+    return;
+  }
+  if (result.status === 'installed') {
+    output.complete('Added Vizzly agent skill');
+    output.hint(`Installed at ${result.targetPath}`);
+    return;
+  }
+  if (result.status === 'exists') {
+    output.hint('Vizzly agent skill already exists in this repo');
+    return;
+  }
+  if (result.status === 'missing-source') {
+    output.warn('Vizzly agent skill was not found in this CLI package');
+  }
+}
+function writeAgentGuidanceOutput(output, result) {
+  if (!result) {
+    return;
+  }
+  if (result.status === 'created') {
+    output.complete('Created AGENTS.md with Vizzly guidance');
+    output.hint(`Wrote ${result.agentsPath}`);
+    return;
+  }
+  if (result.status === 'updated') {
+    output.complete('Added Vizzly guidance to AGENTS.md');
+    output.hint(`Updated ${result.agentsPath}`);
+    return;
+  }
+  if (result.status === 'exists') {
+    output.hint('Vizzly guidance already exists in AGENTS.md');
+  }
+}
+function withAgentSetupResults(payload, {
+  agentSkillResult,
+  agentGuidanceResult
+}) {
+  if (agentSkillResult) {
+    payload.agentSkill = agentSkillResult;
+  }
+  if (agentGuidanceResult) {
+    payload.agentGuidance = agentGuidanceResult;
+  }
+  return payload;
 }
 async function writeConfigFile({
   configPath,
@@ -197,14 +378,37 @@ export async function init(options = {}, deps = {}) {
   let plugins = await loadInitPlugins(options, resolvedDeps);
   let configPath = getInitConfigPath(resolvedDeps.cwd());
   let hasConfig = await fileExists(configPath, resolvedDeps.access);
+  let agentSkillResult = null;
+  let agentGuidanceResult = null;
+  if (await shouldInstallAgentSkill(options, resolvedDeps)) {
+    agentSkillResult = await installProjectAgentSkill({
+      cwd: resolvedDeps.cwd(),
+      sourcePath: resolvedDeps.skillSourcePath,
+      access: resolvedDeps.access,
+      copy: resolvedDeps.copy,
+      mkdir: resolvedDeps.mkdir
+    });
+  }
+  if (options.agentGuidance) {
+    agentGuidanceResult = await upsertProjectAgentGuidance({
+      cwd: resolvedDeps.cwd(),
+      access: resolvedDeps.access,
+      readFile: resolvedDeps.readFile,
+      writeFile: resolvedDeps.writeFile
+    });
+  }
   if (hasConfig && !options.force) {
     if (options.json) {
-      resolvedDeps.output.data({
+      let payload = withAgentSetupResults({
         status: 'skipped',
         reason: 'config_exists',
         configPath,
         message: 'A vizzly.config.js file already exists. Use --force to overwrite.'
+      }, {
+        agentSkillResult,
+        agentGuidanceResult
       });
+      resolvedDeps.output.data(payload);
       return {
         status: 'skipped',
         configPath
@@ -213,6 +417,8 @@ export async function init(options = {}, deps = {}) {
     resolvedDeps.output.header('init');
     resolvedDeps.output.warn('A vizzly.config.js file already exists');
     resolvedDeps.output.hint('Use --force to overwrite');
+    writeAgentSkillOutput(resolvedDeps.output, agentSkillResult);
+    writeAgentGuidanceOutput(resolvedDeps.output, agentGuidanceResult);
     return {
       status: 'skipped',
       configPath
@@ -228,11 +434,15 @@ export async function init(options = {}, deps = {}) {
     });
     let pluginNames = getPluginConfigNames(plugins);
     if (options.json) {
-      resolvedDeps.output.data({
+      let payload = withAgentSetupResults({
         status: 'created',
         configPath,
         plugins: pluginNames
+      }, {
+        agentSkillResult,
+        agentGuidanceResult
       });
+      resolvedDeps.output.data(payload);
       return {
         status: 'created',
         configPath,
@@ -240,6 +450,8 @@ export async function init(options = {}, deps = {}) {
       };
     }
     showNextSteps(resolvedDeps.output);
+    writeAgentSkillOutput(resolvedDeps.output, agentSkillResult);
+    writeAgentGuidanceOutput(resolvedDeps.output, agentGuidanceResult);
     resolvedDeps.output.blank();
     resolvedDeps.output.complete('Vizzly CLI setup complete');
     return {

package/dist/commands/preview.js

@@ -335,7 +335,7 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       output.blank();
       output.print('  Run visual tests first, then upload your preview:');
       output.blank();
-      output.print('    vizzly run "npm test"');
+      output.print('    vizzly run "pnpm test"');
       output.print('    vizzly preview ./dist');
       output.blank();
       output.print('  Or specify a build explicitly:');
@@ -591,13 +591,13 @@ export async function previewCommand(path, options = {}, globalOptions = {}, dep
       output.print(`  ${colors.brand.textTertiary('Files')}       ${colors.white(result.uploaded)} (${formatBytes(result.totalBytes)} compressed)`);
       if (result.reusedBlobs > 0) {
         let savedBytes = result.totalBytes - result.newBytes;
-        output.print(`  ${colors.brand.textTertiary('Deduped')}     ${colors.green(result.reusedBlobs)} files (saved ${formatBytes(savedBytes)})`);
+        output.print(`  ${colors.brand.textTertiary('Deduped')}     ${colors.success(result.reusedBlobs)} files (saved ${formatBytes(savedBytes)})`);
       }
       if (result.basePath) {
         output.print(`  ${colors.brand.textTertiary('Base path')}   ${colors.dim(result.basePath)}`);
       }
       output.blank();
-      output.print(`  ${colors.brand.textTertiary('Preview')}     ${colors.cyan(colors.underline(result.previewUrl))}`);
+      output.print(`  ${colors.brand.textTertiary('Preview')}     ${colors.info(colors.underline(result.previewUrl))}`);
 
       // Open in browser if requested
       if (options.open) {

package/dist/commands/run.js

@@ -348,7 +348,7 @@ export async function runCommand(testCommand, options = {}, globalOptions = {},
           getTokenContext
         });
         if (displayUrl) {
-          output.print(`  ${colors.brand.textTertiary('Results')}      ${colors.cyan(colors.underline(displayUrl))}`);
+          output.print(`  ${colors.brand.textTertiary('Results')}      ${colors.info(colors.underline(displayUrl))}`);
         } else {
           output.print(`  ${colors.brand.textTertiary('Build')}        ${colors.dim(result.buildId)}`);
         }